Connection

The built-in connection surface (SDK ≥ 0.11.0): override authorize or onAttach (or webSocket itself) and the default webSocket serves the agent socket protocol for you, no AgentSocketServer wiring required — overriding onConnect alone does not activate it. The default authorize admits every connection as a read-only watcher — remote @rpc() calls require an explicit authorize override that validates the credential and grants "rpc" deliberately.

​

authorize()

protected authorize(_token, _req?): readonly Claim[] | Promise<readonly Claim[]>

Policy seam: resolve a connection’s credential into its claims (grants). Called by the default webSocket once per connection — with the token the client attached with (or undefined for a client that never presented one) and the connection’s upgrade request, whose headers carry whatever an authenticating front door stamped on it. Return the claims to grant; throw to reject the connection. Claims are application-defined strings; the SDK itself only interprets "rpc", which a connection needs to invoke @rpc() methods remotely. The default admits every connection as a read-only watcher — it never grants "rpc", and it never validates the token (an unvalidated credential must not confer rights). Remote RPC therefore requires an explicit override that verifies the token and/or the request’s identity headers and grants "rpc" deliberately. Parameters Returns readonly Claim[] | Promise<readonly Claim[]> The claims granted to this connection. Default Value ["read"] — for every connection, token or not.

​

onAttach()

protected onAttach(_att): void | Promise<void>

Hook: a connection has been authorized and is about to be admitted. Runs after authorize resolved the connection’s claims and before anything is sent to it. Inspect att.claims (and att.req, the upgrade request carrying front-door identity headers) and call att.close(code?, reason?) (or throw) to veto: a vetoed socket is closed, receives no frames, and is never counted in attachments. The default implementation admits every authorized connection. Parameters Returns void | Promise<void>

​

attachments

get protected attachments(): AgentAttachments

The agent’s currently connected clients (the attachments admitted by the default webSocket). Sockets a webSocket override handles itself are not included. Returns AgentAttachments

​

AgentSocketsNotEnabledError

Thrown by the default Agent.webSocket when the agent has not enabled its connection surface — neither authorize nor onAttach is overridden, and webSocket itself is not overridden either. Overriding onConnect alone does not enable the surface, so an agent whose only connection code is an onConnect override still throws this. The runtime treats an agent in that state exactly like an actor with no webSocket handler: the socket is rejected and nothing is held. Extends

• Error

​

Attachment

One authorized client connection, as handed to Agent.onAttach (and to the socket server’s onAttach hook) right before the connection is admitted. Inspect claims and call close to veto the connection: a vetoed socket is closed immediately, never admitted as a watcher, and receives no protocol frames. Properties claims

readonly claims: ReadonlySet<Claim>

The claims this connection was granted by the authorization policy.

---

req?

readonly optional req?: Request

The connection’s upgrade request, when the host provided one. Identity headers stamped by an authenticating front door ride here, so a veto can consider the caller’s identity as well as its claims. Methods close()

close(code?, reason?): void

Veto this connection: close the socket now. It is never admitted and receives no frames. Parameters Returns void

​

AgentAttachments

The agent’s view of its currently connected clients — the this.attachments facade on an Agent. Properties count

readonly count: number

The number of currently admitted connections.