WebSocket Subscriptions
A client opens a WebSocket to an app environment, sends signed Subscribe actions, and receives live updates about an account, an agent, a session, or a run.

An app environment can tell you about changes as they happen. You open a WebSocket and send one signed Subscribe action for each thing you want to follow. The server then sends you updates about that account, agent, session or run. The signed envelope is the same one the signed API uses.

Endpoint:

/hm/api/apps/ws

/hm/api/apps is the main prefix of the app environment's API. The same socket answers at /hm/api/agents/ws, the path released clients use. It also answers at /agents/ws, for older clients whose server URL has no path.

getAgentWebSocketUrl() in frontend/packages/ui/src/agents/client.ts builds the URL. It picks the main path or an older one from the shape of the server URL.

Transport

The client sends:

    a binary frame with a SignedActionEnvelope, encoded as DAG-CBOR, whose action is Subscribe. A JSON text frame that holds the same bytes as an array of numbers works too. The server checks the envelope's protocol as it does for an HTTP action. A version that is too old gets an error frame with code protocol_too_old.

The server sends:

    AgentWSEvent values, each as a JSON text frame.

The server does not sign each event. It checks your right to follow a key once, when you subscribe.

There is no message to unsubscribe, and no heartbeat or ping. The server does not slow down for a slow client, and it does not limit the number of subscriptions.

Subscribe action

type Subscribe = { _: 'Subscribe' key: `account/${string}` | `agents/${string}` | `sessions/${string}` | `runs/${string}` afterSeq?: number }

Leave afterSeq out when you have no value for it: never sign undefined. The action carries a signed ts timestamp. The server refuses a subscription whose ts is more than five minutes from its own clock, as it does for HTTP actions.

Server events

type AgentWSEvent = | {_: 'connected'; connectedAt: number} | {_: 'subscribed'; key: string; accountId: string} | {_: 'append'; key: `sessions/${string}`; event: SessionEvent} | { _: 'appendPartial' key: `sessions/${string}` partialId: string patch: {textDelta?: string; done?: boolean; usage?: AgentRunUsage; activity?: AgentRunActivity} } | {_: 'change'; key: `sessions/${string}`; value: SessionInfo} | {_: 'change'; key: `agents/${string}`; value: AgentInfo} | { _: 'change' key: `account/${string}` value: {reason: string; agentId?: string; sessionId?: string; activity?: AgentActivity; session?: SessionInfo} } | {_: 'change'; key: `runs/${string}`; value: RunInfo} | {_: 'append'; key: `runs/${string}`; runId: string; seq: number; entry: Record<string, unknown>; createdAt: number} | { _: 'appendPartial' key: `runs/${string}` runId: string partialId: string patch: {progress?: {fraction?: number; label?: string}; activity?: AgentRunActivity; usage?: AgentRunUsage} } | {_: 'error'; message: string; code?: ProtocolErrorCode}

Subscription keys

account/<accountId>

This key is for news about the whole account. The key is the Seed account id. Every open window of the Seed app and every signed-in web tab holds one, because it feeds the unread mark. So the server keeps it light. It sends only small frames: the account/<id> change hints, agent changes (change frames keyed agents/<id>) and run changes. It never sends the text of a conversation. New session events, streaming text and session snapshots go only to those who subscribe to sessions/<id> or agents/<id>. The sidebar and the lists take the session snapshot and the agent's activity summary from the hints.

Two reasons carry the agent's latest activity summary (AgentActivity: the time and kind of the latest event, the time and sender of the latest message, that message's session, and whether any run is live):

    session-event: sent about once per session every 1.5 s while a conversation grows.

    session-updated: when a session's status changes, which is what flips busy. The same reason is also sent when a session is renamed or its model changes; those carry session and no activity.

Both also carry the session's latest SessionInfo (session). A client writes the summary into its cached agents and the snapshot into its cached session lists. An unread mark or an open sidebar then needs no new ListAgents, ListSessions, GetSession or GetAgent request. An open conversation already gets its events on its own sessions/<id> subscription. A client may ignore these fields.

agents/<agentId>

Changes to one agent and to its sessions. The agent's detail page uses this key.

sessions/<sessionId>

The events of one session, from its Log. The session page uses this key and receives:

    replay of durable events after afterSeq;

    future durable append events from every actor, including the user. A verb the user ran through InvokeSessionTool arrives on this stream as tool_call and tool_result events stamped actor: 'user';

    session status change events;

    live appendPartial events carrying assistant text deltas, cumulative run usage, and the current AgentRunActivity (phase, toolName, toolCallId, detail, and the outputTail of a long-running tool call).

runs/<rootRunId>

One subscription follows a whole tree of runs: a run and every run it started. The key is the id of the ROOT run, which every run in the tree stores as root_run_id. If you subscribe with a child run's id, you get the first snapshot and then nothing, because live events are sent only under the root's key. When you subscribe, the server sends a snapshot: one change per run in the tree, then the stored journal entries as append events (afterSeq applies to each run). After that it sends live events:

    change with a RunInfo whenever any run in the tree changes status, usage, or plan;

    append with a workflow journal entry, tagged with the originating runId;

    appendPartial with ephemeral workflow progress (ctx.progress) and tool activity, tagged with runId.

A client can always build the tree again from ListRuns and GetRunJournal, and use this subscription only for live updates.

Authorization

Service.verifySubscription() checks:

    signed envelope shape;

    signed action timestamp is within five minutes of server local time;

    Ed25519 signature, the scheme every blob is signed with;

    signer authorization for account;

    the account may read the thing the key points at (see the rules below).

Rules:

    account/<accountId> must equal verified account ID.

    agents/<agentId> requires reader access: owner, accepted reader or writer, or any signed account on a publicRead agent.

    sessions/<sessionId> requires reader access to its agent.

    runs/<rootRunId> requires reader access to its agent.

The server sends an agent's events to its owner and to its collaborators. A public reader gets the owner's events for the key it subscribed to, and accessRole on agents/ change frames is rewritten to reader or chatter for it. A subscriber to agents/<agentId> also receives change frames whose key is sessions/<id> or account/<ownerId>. So a client must not drop a frame because its key differs from the key the client subscribed to.

    An accepted collaborator receives the agent's live events on its own account subscription. A collaborator that has not accepted, or was removed, does not.

    After one successful subscription, a socket cannot change to another account.

Replay

Replay means the server sends you the stored events you missed. Only stored session events are replayed. Live partial text is not stored, so it cannot be replayed. The server reads the replay in the same step that adds your socket to the session's subscribers. So you get each event either in the replay or live, and none is lost. GetSession reads the log last for the same reason: a client adds what its socket delivers to what it fetched.

For sessions/<id>, with or without afterSeq, the server sends:

    subscribed;

    session change;

    durable append events where seq > afterSeq, or the whole transcript when afterSeq is absent. An event that is too large, replayed or live, arrives with a truncated marker; GetSessionEvent {sessionId, seq} returns it whole.

Durable appends vs partial appends

append

append is a stored event. It matches one row in session_events.

A client adds the event to the conversation it shows. It removes the matching user message it had shown ahead of the server, and clears the partial text for that session, because the final data has arrived.

appendPartial

appendPartial is not stored. It carries the agent's text while the agent is still writing it.

Example:

{ "_": "appendPartial", "key": "sessions/abc", "partialId": "partial-uuid", "patch": {"textDelta": "hello"} }

Later the server sends:

{ "_": "appendPartial", "key": "sessions/abc", "partialId": "partial-uuid", "patch": {"done": true} }

A client keeps the partial text visible on done and clears it only when a stored append arrives. The server starts a new partial for each model response. It appends the stored assistant message of that response as soon as the session's durable store has it, before the events of any tool call that follows. So text streamed before a tool call becomes a stored event ahead of the stored tool_call event. It does not wait for the whole run to end.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Comments