Skip to main content
Your frontend shows a session with the client SDK: give it a session ID and a session token, and it loads the session’s history, follows its live stream, reconnects on its own, and folds everything into one state object. Your frontend writes no streaming, reconnection, or state code, and a user who closes the tab mid-turn and comes back hours later sees everything the agent did in the meantime.

1. Mint a session token on your backend

Your API key never leaves your backend. For the browser, create a session token: it works on one session only, for a lifetime you choose between 60 seconds and 24 hours.
Check in your own backend that the signed-in user may see that session before you mint its token; paddock does not know your users. The token grants on its session everything the server SDK can do there: read, send, stop, stream, and delete. See Authentication.

2. Show the session with React

useSession(sessionId, { token, baseUrl? }) returns the session’s state with send and stop. Components that call it with the same base URL, token, and session ID share one connection; it opens with the first and closes with the last. During server rendering it returns the empty state and makes no request. To point every hook at another base URL, such as a local stack, wrap your app in PaddockProvider:

The session state

Each entry of messages is a message with its seq (null while it is streaming), turnId, and createdAt. A few rules make rendering simple:
  • Streaming text. While the agent writes a reply, an entry of kind streaming holds the whole text so far, under the ID of the assistant message that will complete it. When that message arrives it replaces the entry in place, so a key of m.id keeps your list stable. A streaming entry its turn did not complete is removed when the turn ends.
  • Your own messages. send resolves with the stored user message’s event, and the message is already in messages. It is waiting while its seq is above processedSeq, and held while it is also at or below heldSeq.
  • Tool calls. A tool_call and its tool_result share toolCall.callId and toolResult.callId; pair them to show a call with its result.
  • Unknown kinds. A message of a kind your SDK version does not know is kept in order with its raw fields; skip it or render it generically.

Reconnection and expiry

The client reconnects on its own with capped backoff after a dropped connection, a server error, or 45 seconds without a byte, and resumes after the newest seq the load or the stream delivered, so it never loses or repeats an event. An event that send or stop added to the state early does not count, so an earlier event another writer stored is still fetched. connection is reconnecting meanwhile. The client does not refresh tokens. When the token expires, the stream ends with connection: "closed" and connectionError set to a PaddockError with code unauthorized: mint a new token on your backend and pass it to useSession, and the hook opens a new connection with it. When the session is deleted, the stream ends the same way with code not_found, or, for a connection opened after the deletion, unauthorized with details.reason session_deleted: the session is gone, so do not mint a new token for it.

Without React

@paddock/client is the framework-independent client the hook is built on:
The first subscriber loads the session and opens the stream; the last one to leave closes it. handle.state is the current state, replaced on every change, never mutated. See Browser client.

From your backend

The server SDKs stream a session too, for example to log a turn or to wait for its reply. A stream first yields the session’s snapshot, then every event after after in seq order, then live events. It reconnects on its own and never yields an event twice.
A stream ends with an error on the stream’s error event, such as not_found when the session is deleted, and on any non-2xx answer other than a 5xx when it connects: Go yields a *paddock.Error, and Python and TypeScript raise PaddockError. An event that does not decode ends it with an error too. Network errors and 5xx answers are never surfaced; the stream reconnects instead. Omit after to receive every event of the session from the start. To resume a stream you closed, pass the highest seq you processed.

What the stream sends

The stream is Server-Sent Events at GET /sessions/{id}/stream?after=<seq>. The SDKs parse it for you; this is the wire format if you read it yourself. A : keepalive comment is sent after 15 seconds of silence. Only events with an id are stored and replayed; snapshots, streaming messages, and status updates are live only, and the next one carries the whole current value. Requests carry the token in the Authorization header, never in the URL, and any origin may call the API.