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.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
streamingholds the whole text so far, under the ID of theassistantmessage that will complete it. When that message arrives it replaces the entry in place, so a key ofm.idkeeps your list stable. A streaming entry its turn did not complete is removed when the turn ends. - Your own messages.
sendresolves with the stored user message’s event, and the message is already inmessages. It is waiting while itsseqis aboveprocessedSeq, and held while it is also at or belowheldSeq. - Tool calls. A
tool_calland itstool_resultsharetoolCall.callIdandtoolResult.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 newestseq 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:
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 afterafter in seq order, then live events. It reconnects on its own and never yields an event twice.
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 atGET /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.