Skip to main content
AgentHttpServer (SDK ≥ 0.11.0) is the HTTP front door for an AgentSocketServer: the agent’s streams over Server-Sent Events (GET answers a text/event-stream response), and its RPC surface over POST to …/rpc/<method>. It is a second encoder over the same server — same frames, same authorize / onAttach policy, same dispatch as the WebSocket path — so a plain page with an EventSource and fetch() needs no SDK at all. Construct one over the socket server the actor’s webSocket delegates to, and route HTTP requests from the actor’s fetch into fetch():
On the SSE path the credential rides the token query parameter — an EventSource cannot set headers — and subscribe picks the streams (subscribe=state,messages; omitted = every stream the server offers). Each server frame becomes one SSE event, and the id: carries resume cursors so the browser’s automatic reconnect replays only what it missed. On the RPC path the credential rides Authorization: Bearer <token> (preferred) or the same query parameter; the JSON-array request body is the argument list, and the response body is the same result / error frame a WebSocket caller would receive. Two limits, by design: SSE is one-way, so there are no server→client calls mid-stream (RPC is client-initiated POST only), and there is no ping/pong — an EventSource detects a dropped stream and reconnects by itself.

fetch()

fetch(req): Promise<Response>
Route one HTTP request: POST …/rpc/<method> dispatches an RPC, any other GET opens an SSE stream, anything else is refused with 405. Parameters Returns Promise<Response> The SSE stream, the RPC answer, or an error response.

handleRpc()

handleRpc(req, method?): Promise<Response>
Dispatch one RPC over POST (see the class doc for the URL contract). The request body is the argument list: a plain JSON array, or the SDK codec’s encoded form of one ({"json": […], …}) when rich values need to round-trip. The answer is the result or error frame — the same frame a WebSocket caller would receive — with the HTTP status mapped from the error code (the code strings themselves are unchanged). The call runs through the socket server’s own gates, in bootstrap order — onConnect, authorize (Authorization: Bearer preferred, token query parameter otherwise), onAttach, then the "rpc" claim gate — but it holds NO connection: no snapshot source is read for it, it is never counted as a watcher, and broadcasts never reach it. A gate that refuses the call answers exactly like a refused connection (see the class doc’s rejection shapes). Parameters Returns Promise<Response> The call’s answer frame as JSON.

handleSse()

handleSse(req): Promise<Response>
Serve the agent’s streams as one SSE response (see the class doc for the URL contract and the event format). The connection is negotiated through the socket server’s own bootstrap: authorize resolves the token from the query string (or an Authorization header), onAttach may veto, and the subscribed streams replay their backlog past the Last-Event-ID cursors before live pushes begin. A rejected connection answers with the error frame as JSON (401 for a rejected credential) instead of a stream. When the response is torn down — the EventSource closed, the request aborted, the network dropped — the subscription is released immediately: the connection leaves the watcher set and broadcasts stop targeting it. Parameters Returns Promise<Response> A text/event-stream response, or an error response.