Skip to main content
new AgentClient<TStub, TState>(url, opts?): AgentClient<TStub, TState>
Create a client and start connecting immediately. Parameters Returns AgentClient<TStub, TState> Throws If no global WebSocket exists and none was injected via opts.WebSocketCtor.

​
Type Parameters

​
The Address

The url is the address of one instance. mountAgents serves every instance it mounts at an address of this shape.
  • /agents is the mount’s default base path.
  • <mount> is a key of the mount map.
  • <name> is the instance’s routing name.
Behind a hand-written front door, the address is the one that front door serves.

​
Attach Mode

Attach mode opens every connection, reconnects included, with an attach frame. The frame carries the token, the requested streams and, with resume, the cursors. The server answers with the granted claims and the accepted streams. claims holds the claims. Without token, subscribe or resume, the client speaks the plain protocol. Each connection opens with snapshots of the state and the messages, followed by hello. The plain protocol works with servers that speak nothing else.

​
Reconnects

The client reconnects on its own whenever the link drops. Only close stops it. A heartbeat detects a link that died without closing. The client replaces such a link as it does a dropped one. The backoff and heartbeat options in AgentClientOptions set the timing.

​
AgentClientOptions

Options for AgentClient. Setting any of token / subscribe / resume switches the client into attach mode (see the AgentClient class docs); the connection and heartbeat options apply in both modes. Properties pingIntervalMs?
optional pingIntervalMs?: number
Heartbeat: send a ping every pingIntervalMs (default 30_000).
pingTimeoutMs?
optional pingTimeoutMs?: number
Reconnect if a ping goes unanswered for pingTimeoutMs (default 10_000).
reconnectBackoffMs?
optional reconnectBackoffMs?: number
Base reconnect backoff in ms. Delays grow exponentially (factor 2, ±20% jitter) from this base up to reconnectMaxBackoffMs. Default Value
reconnectMaxBackoffMs?
optional reconnectMaxBackoffMs?: number
Upper bound on the reconnect backoff delay, in ms. Default Value
resume?
optional resume?: boolean
Resume across reconnects: re-attach with the last-seen messages/events cursors so the server replays exactly what was missed — no full re-snapshot, no duplicates. The first connection carries no cursors (a normal snapshot bootstrap is expected).
subscribe?
optional subscribe?: readonly Stream[]
Streams to subscribe to. Omitted = the server’s default set.
token?
optional token?: string
Opaque credential presented in the attach frame; the server derives this connection’s grants from it.
WebSocketCtor?
optional WebSocketCtor?: AgentWebSocketCtor
WebSocket constructor (defaults to the platform globalThis.WebSocket). Inject one for environments without a global, or for tests.

​
Stream

Stream = "state" | "messages" | "events"
The pushable streams a v2 client can subscribe to.