> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection

> The agent's built-in connection surface — the authorize policy seam, the onAttach admission hook, the attachments view, and the types they exchange.

The built-in connection surface *(SDK ≥ 0.11.0)*: override `authorize` or
`onAttach` (or [`webSocket`](/docs/agent-sdk/api-reference/agent/lifecycle#websocket)
itself) and the default `webSocket` serves the agent socket protocol for you, no
[AgentSocketServer](/docs/agent-sdk/api-reference/agent-socket-server) wiring
required — overriding
[`onConnect`](/docs/agent-sdk/api-reference/agent/lifecycle#onconnect) alone does
not activate it. The default `authorize` admits every connection as a
**read-only watcher** — remote [`@rpc()`](/docs/agent-sdk/api-reference/agent/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`](/docs/agent-sdk/api-reference/agent/lifecycle#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()`](/docs/agent-sdk/api-reference/agent/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**

| Parameter | Type                    | Description                                                                                           |
| --------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `_token`  | `string` \| `undefined` | The credential presented by the client, or `undefined` for a tokenless (anonymous) connection.        |
| `_req?`   | `Request`               | The connection's upgrade request (front-door identity headers ride here), when the host provided one. |

**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`](/docs/agent-sdk/api-reference/agent/connection#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`](/docs/agent-sdk/api-reference/agent/connection#attachments). The default
implementation admits every authorized connection.

**Parameters**

| Parameter | Type                                                                      | Description                                                    |
| --------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `_att`    | [`Attachment`](/docs/agent-sdk/api-reference/agent/connection#attachment) | The connection's claims, its upgrade request, and its `close`. |

**Returns**

`void` | `Promise`\<`void`>

## attachments

> **get** `protected` **attachments**(): [`AgentAttachments`](/docs/agent-sdk/api-reference/agent/connection#agentattachments)

The agent's currently connected clients (the attachments admitted by the
default [`webSocket`](/docs/agent-sdk/api-reference/agent/lifecycle#websocket)). Sockets a
`webSocket` override handles itself are not included.

**Returns**

[`AgentAttachments`](/docs/agent-sdk/api-reference/agent/connection#agentattachments)

## AgentSocketsNotEnabledError

Thrown by the default [`Agent.webSocket`](/docs/agent-sdk/api-reference/agent/lifecycle#websocket) when the
agent has not enabled its connection surface — neither
[`authorize`](/docs/agent-sdk/api-reference/agent/connection#authorize) nor [`onAttach`](/docs/agent-sdk/api-reference/agent/connection#onattach)
is overridden, and `webSocket` itself is not overridden either. Overriding
[`onConnect`](/docs/agent-sdk/api-reference/agent/lifecycle#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**

| Parameter | Type     | Description                                                                                                  |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `code?`   | `number` | WebSocket close code (application codes 4000-4999 are yours to define). Defaults to 1008 (policy violation). |
| `reason?` | `string` | Optional human-readable close reason.                                                                        |

**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.