agents 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/dist/{agent-routing-DE5zmCQ8.d.ts → agent-routing-B2XLNMxq.d.ts} +196 -189
  2. package/dist/agent-routing.d.ts +1 -1
  3. package/dist/agent-tool-types.d.ts +26 -26
  4. package/dist/{agent-tools-DtXMTDGM.d.ts → agent-tools-Dj5Mzlw7.d.ts} +7 -7
  5. package/dist/agent-tools.d.ts +21 -21
  6. package/dist/{capability-BjSKYpzg.js → capability-B4WbF81e.js} +2 -1
  7. package/dist/capability-B4WbF81e.js.map +1 -0
  8. package/dist/{capability-runner-Be_-PLR1.d.ts → capability-runner-BUBa6Ake.d.ts} +40 -15
  9. package/dist/chat/index.d.ts +14 -11
  10. package/dist/chat/index.js +11 -7
  11. package/dist/chat/index.js.map +1 -1
  12. package/dist/chat-sdk/index.d.ts +3 -3
  13. package/dist/chat-sdk/index.js +1 -1
  14. package/dist/client-BxdkCuVy.d.ts +411 -0
  15. package/dist/client-C9DAjZIY.js +518 -0
  16. package/dist/client-C9DAjZIY.js.map +1 -0
  17. package/dist/{client-jagG8a9_.js → client-fyQrLGkD.js} +2 -2
  18. package/dist/{client-jagG8a9_.js.map → client-fyQrLGkD.js.map} +1 -1
  19. package/dist/client.d.ts +27 -283
  20. package/dist/client.js +2 -274
  21. package/dist/current-agent-C4w86kcN.d.ts +93 -0
  22. package/dist/{current-agent-Da_C9a3b.d.ts → durable-object-lifecycle-ei7M7lqB.d.ts} +13 -122
  23. package/dist/index-Dlgtd3Mj.d.ts +78 -0
  24. package/dist/index.d.ts +59 -59
  25. package/dist/index.js +2 -2
  26. package/dist/internal_context.d.ts +1 -1
  27. package/dist/lifecycle/index.d.ts +19 -17
  28. package/dist/lifecycle/index.js +2 -2
  29. package/dist/{lifecycle-CMRGjZdw.js → lifecycle-Mm_jQh7r.js} +36 -21
  30. package/dist/lifecycle-Mm_jQh7r.js.map +1 -0
  31. package/dist/mcp/client/index.d.ts +20 -20
  32. package/dist/mcp/client/index.js +1 -1
  33. package/dist/mcp/index.d.ts +35 -35
  34. package/dist/mcp/index.js +2 -2
  35. package/dist/queue/index.d.ts +123 -0
  36. package/dist/queue/index.js +2 -0
  37. package/dist/queue-BC9F5cUo.js +406 -0
  38. package/dist/queue-BC9F5cUo.js.map +1 -0
  39. package/dist/react.d.ts +33 -15
  40. package/dist/react.js +31 -8
  41. package/dist/react.js.map +1 -1
  42. package/dist/{retries-D9Ds-1lz.d.ts → retries-D9B2UCq3.d.ts} +9 -3
  43. package/dist/retries.d.ts +5 -3
  44. package/dist/retries.js +9 -1
  45. package/dist/retries.js.map +1 -1
  46. package/dist/routing/index.d.ts +2 -2
  47. package/dist/routing/index.js +1 -1
  48. package/dist/{scheduler-Dwh85ZGl.d.ts → scheduler-BGq6M5Kd.d.ts} +6 -6
  49. package/dist/{scheduler-DD9NdYbF.js → scheduler-D_KHqxBa.js} +4 -11
  50. package/dist/scheduler-D_KHqxBa.js.map +1 -0
  51. package/dist/schedules/index.d.ts +1 -1
  52. package/dist/schedules/index.js +1 -1
  53. package/dist/serializable.d.ts +1 -1
  54. package/dist/sessions/index.d.ts +1 -1
  55. package/dist/sessions/index.js +1 -1
  56. package/dist/{src-DlSHshb2.js → src-BNU3ZiJM.js} +126 -393
  57. package/dist/src-BNU3ZiJM.js.map +1 -0
  58. package/dist/state/index.d.ts +6 -0
  59. package/dist/state/index.js +137 -0
  60. package/dist/state/index.js.map +1 -0
  61. package/dist/streams/index.d.ts +1 -1
  62. package/dist/streams/index.js +1 -1
  63. package/dist/{streams-D6tJ0NN9.d.ts → streams-BcE8JP2X.d.ts} +2 -2
  64. package/dist/{streams-DZKgAj9b.js → streams-CCPRV6dt.js} +2 -2
  65. package/dist/{streams-DZKgAj9b.js.map → streams-CCPRV6dt.js.map} +1 -1
  66. package/dist/sub-routing.d.ts +12 -12
  67. package/dist/tasks/index.d.ts +1 -1
  68. package/dist/tasks/index.js +1 -1
  69. package/dist/{tasks-ylZgBjhj.js → tasks-D4nLqVSI.js} +3 -3
  70. package/dist/{tasks-ylZgBjhj.js.map → tasks-D4nLqVSI.js.map} +1 -1
  71. package/dist/{tasks-BRJ5zgya.d.ts → tasks-V2lCT8ZV.d.ts} +5 -5
  72. package/dist/transport-protocol-BxyngQ_R.js +25 -0
  73. package/dist/transport-protocol-BxyngQ_R.js.map +1 -0
  74. package/dist/transport-protocol-ZTew5Wso.d.ts +27 -0
  75. package/dist/types-DCD6BNZH.d.ts +70 -0
  76. package/dist/voice/index.d.ts +2 -2
  77. package/dist/websockets/index.d.ts +178 -69
  78. package/dist/websockets/index.js +3 -2
  79. package/dist/websockets-D7IzWbZb.js +1005 -0
  80. package/dist/websockets-D7IzWbZb.js.map +1 -0
  81. package/dist/workflow-types.d.ts +25 -25
  82. package/dist/workflows.d.ts +21 -21
  83. package/dist/workflows.js +1 -1
  84. package/docs/agent-class.md +2 -2
  85. package/docs/client-sdk.md +30 -0
  86. package/docs/index.md +1 -1
  87. package/docs/lifecycle.md +97 -22
  88. package/docs/queue.md +135 -241
  89. package/docs/retries.md +1 -1
  90. package/docs/sub-agents.md +3 -3
  91. package/package.json +12 -2
  92. package/dist/capability-BjSKYpzg.js.map +0 -1
  93. package/dist/client.js.map +0 -1
  94. package/dist/lifecycle-CMRGjZdw.js.map +0 -1
  95. package/dist/scheduler-DD9NdYbF.js.map +0 -1
  96. package/dist/src-DlSHshb2.js.map +0 -1
  97. package/dist/websockets-DUfRHPRq.js +0 -502
  98. package/dist/websockets-DUfRHPRq.js.map +0 -1
@@ -1,10 +1,10 @@
1
1
  import {
2
- _ as LifecycleJobOutcome,
2
+ _ as LifecycleJobContext,
3
3
  d as LifecycleRouteContext,
4
- g as LifecycleJobContext,
5
4
  o as MemoryLimitContext,
6
- s as LifecycleCapability
7
- } from "./capability-runner-Be_-PLR1.js";
5
+ s as LifecycleCapability,
6
+ v as LifecycleJobOutcome
7
+ } from "./capability-runner-BUBa6Ake.js";
8
8
 
9
9
  //#region src/tasks/duration.d.ts
10
10
  /**
@@ -514,4 +514,4 @@ export {
514
514
  TaskWaitReason as x,
515
515
  TaskStepConfig as y
516
516
  };
517
- //# sourceMappingURL=tasks-BRJ5zgya.d.ts.map
517
+ //# sourceMappingURL=tasks-V2lCT8ZV.d.ts.map
@@ -0,0 +1,25 @@
1
+ //#region src/websockets/transport-protocol.ts
2
+ /** Query parameter selecting the Cap'n Web connection transport. */
3
+ const CAPNWEB_TRANSPORT_QUERY = "__agents_transport";
4
+ const CAPNWEB_TRANSPORT_VALUE = "capnweb";
5
+ /**
6
+ * The single method on the host's session root: the frame pipe from the
7
+ * client to the host. Every Agent protocol frame travels through it.
8
+ */
9
+ const CAPNWEB_TRANSPORT_SEND = "__cf_agent_send";
10
+ /** Rewrite a host URL to select the Cap'n Web transport over `ws(s)`. */
11
+ function capnWebTransportUrl(url) {
12
+ const resolved = new URL(url);
13
+ if (resolved.protocol === "http:") resolved.protocol = "ws:";
14
+ if (resolved.protocol === "https:") resolved.protocol = "wss:";
15
+ resolved.searchParams.set(CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE);
16
+ return resolved.toString();
17
+ }
18
+ /** Whether a request is a WebSocket upgrade selecting the transport. */
19
+ function isCapnWebTransportUpgrade(request) {
20
+ return request.headers.get("Upgrade")?.toLowerCase() === "websocket" && new URL(request.url).searchParams.get("__agents_transport") === "capnweb";
21
+ }
22
+ //#endregion
23
+ export { isCapnWebTransportUpgrade as a, capnWebTransportUrl as i, CAPNWEB_TRANSPORT_SEND as n, CAPNWEB_TRANSPORT_VALUE as r, CAPNWEB_TRANSPORT_QUERY as t };
24
+
25
+ //# sourceMappingURL=transport-protocol-BxyngQ_R.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transport-protocol-BxyngQ_R.js","names":[],"sources":["../src/websockets/transport-protocol.ts"],"sourcesContent":["/**\n * Isomorphic wire contract for the Cap'n Web connection transport.\n *\n * Imported by browser bundles and by the Worker runtime, so it must not\n * import `cloudflare:workers`.\n */\n\n/** Wire a `useAgent` / `AgentClient` connection travels on. */\nexport type AgentTransport = \"cf-websocket\" | \"capnweb\";\n\n/** Query parameter selecting the Cap'n Web connection transport. */\nexport const CAPNWEB_TRANSPORT_QUERY = \"__agents_transport\";\nexport const CAPNWEB_TRANSPORT_VALUE = \"capnweb\";\n\n/**\n * The single method on the host's session root: the frame pipe from the\n * client to the host. Every Agent protocol frame travels through it.\n */\nexport const CAPNWEB_TRANSPORT_SEND = \"__cf_agent_send\";\n\nexport type TransportMessage = string | ArrayBuffer | ArrayBufferView;\n\n/** Root the client exposes; the host delivers frames through it. */\nexport type TransportClientEvents = {\n message(value: TransportMessage): void | Promise<void>;\n};\n\n/** Root the host exposes; the client sends frames through it. */\nexport type TransportHostPipe = {\n [CAPNWEB_TRANSPORT_SEND](message: TransportMessage): Promise<void>;\n};\n\n/** Rewrite a host URL to select the Cap'n Web transport over `ws(s)`. */\nexport function capnWebTransportUrl(url: string | URL): string {\n const resolved = new URL(url);\n if (resolved.protocol === \"http:\") resolved.protocol = \"ws:\";\n if (resolved.protocol === \"https:\") resolved.protocol = \"wss:\";\n resolved.searchParams.set(CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE);\n return resolved.toString();\n}\n\n/** Whether a request is a WebSocket upgrade selecting the transport. */\nexport function isCapnWebTransportUpgrade(request: Request): boolean {\n return (\n request.headers.get(\"Upgrade\")?.toLowerCase() === \"websocket\" &&\n new URL(request.url).searchParams.get(CAPNWEB_TRANSPORT_QUERY) ===\n CAPNWEB_TRANSPORT_VALUE\n );\n}\n"],"mappings":";;AAWA,MAAa,0BAA0B;AACvC,MAAa,0BAA0B;;;;;AAMvC,MAAa,yBAAyB;;AAetC,SAAgB,oBAAoB,KAA2B;CAC7D,MAAM,WAAW,IAAI,IAAI,GAAG;CAC5B,IAAI,SAAS,aAAa,SAAS,SAAS,WAAW;CACvD,IAAI,SAAS,aAAa,UAAU,SAAS,WAAW;CACxD,SAAS,aAAa,IAAI,yBAAyB,uBAAuB;CAC1E,OAAO,SAAS,SAAS;AAC3B;;AAGA,SAAgB,0BAA0B,SAA2B;CACnE,OACE,QAAQ,QAAQ,IAAI,SAAS,CAAC,EAAE,YAAY,MAAM,eAClD,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC,aAAa,IAAA,oBAA2B,MAAA;AAGjE"}
@@ -0,0 +1,27 @@
1
+ //#region src/websockets/transport-protocol.d.ts
2
+ /**
3
+ * Isomorphic wire contract for the Cap'n Web connection transport.
4
+ *
5
+ * Imported by browser bundles and by the Worker runtime, so it must not
6
+ * import `cloudflare:workers`.
7
+ */
8
+ /** Wire a `useAgent` / `AgentClient` connection travels on. */
9
+ type AgentTransport = "cf-websocket" | "capnweb";
10
+ /** Query parameter selecting the Cap'n Web connection transport. */
11
+ declare const CAPNWEB_TRANSPORT_QUERY = "__agents_transport";
12
+ declare const CAPNWEB_TRANSPORT_VALUE = "capnweb";
13
+ type TransportMessage = string | ArrayBuffer | ArrayBufferView;
14
+ /** Rewrite a host URL to select the Cap'n Web transport over `ws(s)`. */
15
+ declare function capnWebTransportUrl(url: string | URL): string;
16
+ /** Whether a request is a WebSocket upgrade selecting the transport. */
17
+ declare function isCapnWebTransportUpgrade(request: Request): boolean;
18
+ //#endregion
19
+ export {
20
+ capnWebTransportUrl as a,
21
+ TransportMessage as i,
22
+ CAPNWEB_TRANSPORT_QUERY as n,
23
+ isCapnWebTransportUpgrade as o,
24
+ CAPNWEB_TRANSPORT_VALUE as r,
25
+ AgentTransport as t
26
+ };
27
+ //# sourceMappingURL=transport-protocol-ZTew5Wso.d.ts.map
@@ -0,0 +1,70 @@
1
+ import { t as RetryOptions } from "./retries-D9B2UCq3.js";
2
+
3
+ //#region src/queue/types.d.ts
4
+ /**
5
+ * One durable background task waiting in a Queue.
6
+ *
7
+ * @template T Type of the callback payload.
8
+ */
9
+ type QueueItem<T = unknown> = {
10
+ /** Unique item identifier. */ id: string /** Name of the callback invoked with the payload. */;
11
+ callback: string /** Data passed to the callback. */;
12
+ payload: T /** Creation time as a Unix timestamp in seconds. */;
13
+ createdAt: number /** Retry policy applied when the callback throws. */;
14
+ retry?: RetryOptions;
15
+ };
16
+ /**
17
+ * Constraint for a Queue's registered callback map: named handlers receiving
18
+ * the parsed payload and the item being processed.
19
+ *
20
+ * @experimental The API surface may change before stabilizing.
21
+ */
22
+ type QueueHandlers = Record<string, (payload: never, item: never) => unknown>;
23
+ /**
24
+ * Default callback surface for a Queue constructed without registered
25
+ * callbacks: any name compiles with an untyped payload. At runtime a name
26
+ * must be registered or supplied by a composition-root resolver (the
27
+ * aperture behind Agent's name-based queue API); a bare Queue rejects it
28
+ * otherwise.
29
+ *
30
+ * @experimental The API surface may change before stabilizing.
31
+ */
32
+ type QueueCallbacks = Record<
33
+ string,
34
+ (payload: unknown, item: QueueItem<unknown>) => unknown
35
+ >;
36
+ /**
37
+ * The payload type a registered queue callback accepts.
38
+ *
39
+ * @experimental The API surface may change before stabilizing.
40
+ */
41
+ type QueuePayload<Handler> = Handler extends (
42
+ payload: infer Payload,
43
+ ...rest: never[]
44
+ ) => unknown
45
+ ? Payload
46
+ : never;
47
+ /** Options accepted when pushing one item. */
48
+ type QueuePushOptions = {
49
+ /**
50
+ * Stable item id. A push with an existing id replaces that item in place
51
+ * (and supersedes a dispatch of it that is still in flight). Omitted ids
52
+ * are generated.
53
+ */
54
+ id?: string /** Retry policy for callback execution, overriding the Queue default. */;
55
+ retry?: RetryOptions;
56
+ };
57
+ /** Filters accepted by `list()`. */
58
+ type QueueCriteria = {
59
+ /** Only items addressed to this callback. */ callback?: string;
60
+ };
61
+ //#endregion
62
+ export {
63
+ QueuePayload as a,
64
+ QueueItem as i,
65
+ QueueCriteria as n,
66
+ QueuePushOptions as o,
67
+ QueueHandlers as r,
68
+ QueueCallbacks as t
69
+ };
70
+ //# sourceMappingURL=types-DCD6BNZH.d.ts.map
@@ -1,5 +1,5 @@
1
- import { b as Connection } from "../capability-runner-Be_-PLR1.js";
2
- import { c as Agent } from "../agent-routing-DE5zmCQ8.js";
1
+ import { x as Connection } from "../capability-runner-BUBa6Ake.js";
2
+ import { c as Agent } from "../agent-routing-B2XLNMxq.js";
3
3
  import {
4
4
  C as VoiceTransport,
5
5
  D as VoiceTurnSource,
@@ -1,13 +1,29 @@
1
1
  import {
2
- b as Connection,
2
+ S as ConnectionContext,
3
+ T as WSMessage,
3
4
  r as CapabilityWebSocketUpgradeContext,
4
5
  s as LifecycleCapability,
5
- w as WSMessage,
6
- x as ConnectionContext
7
- } from "../capability-runner-Be_-PLR1.js";
6
+ x as Connection
7
+ } from "../capability-runner-BUBa6Ake.js";
8
+ import {
9
+ a as capnWebTransportUrl,
10
+ n as CAPNWEB_TRANSPORT_QUERY,
11
+ o as isCapnWebTransportUpgrade,
12
+ r as CAPNWEB_TRANSPORT_VALUE,
13
+ t as AgentTransport
14
+ } from "../transport-protocol-ZTew5Wso.js";
8
15
  import { RpcTarget } from "cloudflare:workers";
9
16
 
10
17
  //#region src/websockets/options.d.ts
18
+ /**
19
+ * The part of a `State` capability the WebSockets capability uses. A
20
+ * structural port, so any `State<T>` fits without a cast and the
21
+ * capability never depends on the class itself.
22
+ */
23
+ type SyncedState = {
24
+ /** Current state, or `undefined` when nothing is stored. */ get(): unknown /** Validate and persist a change; throws when the host rejects it. */;
25
+ set(nextState: never, source: Connection): void;
26
+ };
11
27
  /** A frame delivered on a capability-owned WebSocket connection. */
12
28
  type WebSocketMessage = WSMessage;
13
29
  /**
@@ -41,19 +57,62 @@ type WebSocketHandlers = {
41
57
  */
42
58
  interface WebSocketsOptions {
43
59
  /**
44
- * Connection handlers for WebSocket clients. When present, the
45
- * capability claims WebSocket upgrades and owns those connections end
46
- * to end. When absent, upgrades are declined.
60
+ * Connection handlers for WebSocket clients. The capability accepts and
61
+ * tracks every WebSocket upgrade either way; handlers add behavior on
62
+ * connect, message, close and error.
47
63
  */
48
64
  readonly handlers?: WebSocketHandlers;
49
65
  /**
50
- * An `RpcTarget` whose methods are exposed to remote callers over a
51
- * Cap'n Web session (`?__agents_rpc=capnweb`). The target's prototype
52
- * methods are the complete remote interface. Methods run through the
53
- * host invocation boundary and may return a `ReadableStream` to
54
- * stream results.
66
+ * An `RpcTarget` whose prototype methods are the host's complete remote
67
+ * interface, reached through `useAgent().call` and `.stub`. On the
68
+ * `cf-websocket` wire they are answered as JSON `rpc` frames. On the
69
+ * `capnweb` wire they are native Cap'n Web methods on the session root:
70
+ * an `RpcTarget` result becomes a live stub, a `ReadableStream` streams,
71
+ * and calls pipeline. Methods run through the host invocation boundary
72
+ * with the calling connection in scope. `Agent` answers its own
73
+ * decorated methods on the JSON wire and does not set this.
55
74
  */
56
75
  readonly callables?: RpcTarget;
76
+ /**
77
+ * Whether a new connection gets the connect-time protocol frames —
78
+ * identity (`cf_agent_identity`), then the current state when `state`
79
+ * is set — and whether protocol frames reach it at all.
80
+ *
81
+ * - `true` (default): every connection.
82
+ * - a function: decided per connection at accept time. `false` marks
83
+ * the connection no-protocol: it gets no protocol text frames, on
84
+ * connect or via `broadcastState()`, but can still send and receive
85
+ * ordinary messages and use callables. For binary-only clients.
86
+ * - `false`: the host drives the connect sequence itself with
87
+ * `sendIdentity()` and `sendState()`, and applies client state frames
88
+ * with `applyStateFrame()` — `Agent` does this, since it must decide
89
+ * whether a connection belongs to a facet before any frame is sent.
90
+ */
91
+ readonly protocol?:
92
+ | boolean
93
+ | ((connection: Connection, ctx: ConnectionContext) => boolean);
94
+ /**
95
+ * Decide at accept time whether a connection is readonly. A readonly
96
+ * connection's `cf_agent_state` frames are refused with
97
+ * `cf_agent_state_error`; everything else works. Also settable later
98
+ * with `setReadonly()`.
99
+ */
100
+ readonly readonly?: (
101
+ connection: Connection,
102
+ ctx: ConnectionContext
103
+ ) => boolean;
104
+ /**
105
+ * A {@link SyncedState} — normally a `State` capability — to sync over
106
+ * connections. The capability pushes the current value to each new
107
+ * connection after identity and applies `cf_agent_state` frames a
108
+ * client sends: a readonly connection is refused, and a change the
109
+ * host's validator rejects is answered with `cf_agent_state_error`.
110
+ * Broadcasting a change is the state owner's call — wire the `State`'s
111
+ * `onChanged` to `broadcastState(source)`. Install the same instance on
112
+ * the lifecycle so it owns storage and validation; without this option
113
+ * state is never sent or accepted over connections.
114
+ */
115
+ readonly state?: SyncedState;
57
116
  /**
58
117
  * Tags attached to each accepted connection, queryable through
59
118
  * `getConnections(tag)`. The connection id is always the first tag.
@@ -70,18 +129,16 @@ interface WebSocketsOptions {
70
129
  *
71
130
  * Lifecycle itself does not model WebSockets — hosts that want them
72
131
  * install this capability, which owns the connection subsystem end to
73
- * end: it claims upgrades, accepts hibernating sockets, dispatches
74
- * `onConnect`/`onMessage`/`onClose` inside the host invocation
75
- * boundary, reciprocates close handshakes, and answers
76
- * `getConnections()`/`getConnection()`.
132
+ * end: it claims upgrades, dispatches `onConnect`/`onMessage`/`onClose`
133
+ * inside the host invocation boundary, reciprocates close handshakes,
134
+ * and answers `getConnections()`/`getConnection()`.
77
135
  *
78
136
  * ```ts
79
137
  * class Room extends DurableObject<Env> {
80
138
  * readonly webSockets = new WebSockets({
81
139
  * handlers: {
82
140
  * onConnect: (connection) => connection.send("welcome"),
83
- * onMessage: (connection, message) => { ... },
84
- * onClose: (connection, code) => { ... }
141
+ * onMessage: (connection, message) => { ... }
85
142
  * },
86
143
  * callables: new RoomCallables()
87
144
  * });
@@ -89,31 +146,44 @@ interface WebSocketsOptions {
89
146
  * }
90
147
  * ```
91
148
  *
92
- * `callables` exposes an `RpcTarget`'s prototype methods to remote
93
- * callers over a Cap'n Web session claimed from `?__agents_rpc=capnweb`
94
- * upgrades. Methods run through the host invocation boundary, may
95
- * return a `ReadableStream` to stream results, and emit
96
- * `rpc`/`rpc:error` capability events. Callable sessions are
97
- * non-hibernating: while a client holds one open, the Durable Object
98
- * stays pinned in memory.
149
+ * Connections arrive on one of two wires, chosen by the client:
150
+ *
151
+ * - **cf-websocket** (default): accepted with the Hibernation API. Idle
152
+ * clients stay connected while the Durable Object leaves memory.
153
+ * - **capnweb** (`?__agents_transport=capnweb`): protocol frames through
154
+ * one pipe method on a Cap'n Web session whose root also carries the
155
+ * host's callables natively. Non-hibernating — the object stays pinned
156
+ * while the connection is open.
99
157
  *
100
- * There is no separate browser client: against an `Agent`, the
101
- * `useAgent` hook's `stub`/`call` reach the same interface over the
102
- * protocol socket. A plain host's endpoint is reached with capnweb
103
- * directly — `newWebSocketRpcSession(new WebSocket(callablesRpcUrl(url)))`.
158
+ * Both wires dispatch the same handlers and appear in `getConnections()`.
159
+ * On both, the capability speaks the Agent protocol a plain host needs
160
+ * for `useAgent` and `AgentClient`: it sends the identity frame on
161
+ * connect, and it serves `callables` — as `rpc` JSON frames on the
162
+ * WebSocket wire, and natively on the Cap'n Web session root, where an
163
+ * `RpcTarget` result becomes a live stub and calls pipeline. `call()`
164
+ * and `stub` work against a plain Durable Object exactly as against an
165
+ * `Agent`. Pass a `State` capability as `state` and the hook's
166
+ * `state`/`setState` work too: the current value is pushed on connect
167
+ * and client updates are validated and applied; the state owner
168
+ * broadcasts changes with `broadcastState()`. Per-connection readonly
169
+ * and no-protocol flags live here as well, for every host.
104
170
  *
105
171
  * @experimental The API surface may change before stabilizing.
106
172
  */
107
173
  declare class WebSockets extends LifecycleCapability {
108
174
  #private;
175
+ /** Claims every upgrade, so Lifecycle dispatches it after all others. */
176
+ readonly claims = "catch-all";
109
177
  constructor(options?: WebSocketsOptions);
110
- /** Claim callables RPC upgrades and, with handlers, plain upgrades. */
178
+ /**
179
+ * Claim every upgrade, never declining: a Cap'n Web transport upgrade
180
+ * becomes a session, everything else a tracked hibernating connection,
181
+ * whether or not handlers or callables are configured. Handlers only add
182
+ * behavior on connect, message, close, and error.
183
+ */
111
184
  onWebSocketUpgrade({
112
185
  request
113
- }: CapabilityWebSocketUpgradeContext):
114
- | Promise<Response>
115
- | Response
116
- | undefined;
186
+ }: CapabilityWebSocketUpgradeContext): Promise<Response>;
117
187
  /** Dispatch a platform message wake for a capability-owned socket. */
118
188
  onWebSocketMessage(
119
189
  ws: WebSocket,
@@ -134,59 +204,98 @@ declare class WebSockets extends LifecycleCapability {
134
204
  * them down.
135
205
  */
136
206
  dispose(): void;
137
- /** Open connections accepted by this capability, optionally by tag. */
207
+ /** Open connections on either wire, optionally by tag. */
138
208
  getConnections<TState = unknown>(
139
209
  tag?: string
140
210
  ): IterableIterator<Connection<TState>>;
141
- /** One connection accepted by this capability, by id. */
211
+ /** One connection on either wire, by id. */
142
212
  getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
213
+ /**
214
+ * Send the identity frame, unless the connection is no-protocol. The
215
+ * defaults are the Durable Object's routed name and host class; a host
216
+ * whose public identity differs — an `Agent` facet, whose routed name
217
+ * is an internal encoding of its logical name — passes its own.
218
+ */
219
+ sendIdentity(
220
+ connection: Connection,
221
+ identity?: {
222
+ name: string;
223
+ agent: string;
224
+ }
225
+ ): void;
226
+ /**
227
+ * Send the current state to one connection, unless nothing is stored
228
+ * or the connection is no-protocol. Reading the state may seed the
229
+ * initial value; see `#connecting`.
230
+ */
231
+ sendState(connection: Connection): void;
232
+ /**
233
+ * Apply a parsed `cf_agent_state` frame from a client. A readonly
234
+ * connection is refused; a change the host's validator rejects is
235
+ * logged in full server-side and answered with a generic
236
+ * `cf_agent_state_error`. Broadcasting the accepted change is the state
237
+ * owner's call, through its `onChanged` hook. Callers that drive the
238
+ * protocol themselves call this inside their own invocation context;
239
+ * the capability's automatic path does so via `runInHostContext`.
240
+ *
241
+ * @returns Whether the frame was a state frame (handled either way).
242
+ */
243
+ applyStateFrame(connection: Connection, frame: unknown): boolean;
244
+ /**
245
+ * Push the current state to every protocol-enabled connection except
246
+ * the one a change came from, which already has the value it sent.
247
+ * Wire a `State`'s `onChanged` to this.
248
+ */
249
+ broadcastState(except?: Connection | "server"): void;
250
+ /** Whether the connection may update host state over the wire. */
251
+ isReadonly(connection: Connection): boolean;
252
+ /** Mark a connection readonly, or writable again. */
253
+ setReadonly(connection: Connection, readonly?: boolean): void;
254
+ /** Whether protocol text frames reach the connection. */
255
+ isProtocolEnabled(connection: Connection): boolean;
256
+ /** Enable or suppress protocol text frames for a connection. */
257
+ setProtocolEnabled(connection: Connection, enabled: boolean): void;
143
258
  }
144
259
  //#endregion
145
- //#region src/websockets/callables-target.d.ts
260
+ //#region src/websockets/connection-flags.d.ts
146
261
  /**
147
- * Build a callables target from a host's `@callable()`-decorated
148
- * methods — the fallback interface source when no `RpcTarget` is
149
- * configured (an explicit target is preferred and wins).
262
+ * Internal per-connection flags, stored inside the connection's own state
263
+ * under `_cf_`-prefixed keys so they ride the hibernation attachment (or a
264
+ * bridged connection's synced state) and survive a wake. The state wrapper
265
+ * installed by {@link ensureConnectionWrapped} hides them from
266
+ * `connection.state` and preserves them across user `setState` calls.
150
267
  *
151
- * Methods are resolved on the host at call time, so framework wrapping
152
- * applied after construction (e.g. Agent's context auto-wrapping) is
153
- * honored. Methods registered with `streaming: true` expect the legacy
154
- * Agent RPC protocol's injected `StreamingResponse` and are not exposed
155
- * here — return a `ReadableStream` from an `RpcTarget` method instead.
156
- *
157
- * @param host - The object whose decorated methods form the interface.
158
- * @returns A target exposing the decorated methods, or `undefined`
159
- * when the host has none.
268
+ * Owned by the WebSockets capability; `Agent` and framework mixins reach it
269
+ * through the capability or, for their own keys, through
270
+ * {@link registerInternalConnectionKeys}.
160
271
  */
161
- declare function callablesFromDecorated(host: object): RpcTarget | undefined;
162
- //#endregion
163
- //#region src/websockets/protocol.d.ts
272
+ /** A readonly connection may not update host state. */
273
+ declare const CF_READONLY_KEY = "_cf_readonly";
164
274
  /**
165
- * Isomorphic pieces of the callables RPC wire contract.
166
- *
167
- * Imported from browser bundles (via the client) and from the Worker
168
- * runtime, so it must not import `cloudflare:workers`.
275
+ * A no-protocol connection receives no protocol text frames (identity,
276
+ * state sync, MCP servers) — neither on connect nor via broadcasts.
169
277
  */
170
- /** Query parameter selecting the callables Cap'n Web RPC endpoint. */
171
- declare const CALLABLES_RPC_QUERY = "__agents_rpc";
172
- declare const CALLABLES_RPC_VALUE = "capnweb";
173
- /** Whether a request is a WebSocket upgrade addressed to callables RPC. */
174
- declare function isCallablesRpcUpgrade(request: Request): boolean;
278
+ declare const CF_NO_PROTOCOL_KEY = "_cf_no_protocol";
175
279
  /**
176
- * Derive the callables RPC socket URL from a host route. Accepts http(s)
177
- * or ws(s) URLs and returns a ws(s) URL with the RPC query parameter set.
280
+ * Register additional `_cf_`-prefixed keys a host or mixin stores in
281
+ * connection state, so they are hidden from `connection.state` and kept
282
+ * across user `setState` calls like the capability's own flags.
178
283
  */
179
- declare function callablesRpcUrl(url: string | URL): string;
284
+ declare function registerInternalConnectionKeys(...keys: string[]): void;
180
285
  //#endregion
181
286
  export {
182
- CALLABLES_RPC_QUERY,
183
- CALLABLES_RPC_VALUE,
287
+ type AgentTransport,
288
+ CAPNWEB_TRANSPORT_QUERY,
289
+ CAPNWEB_TRANSPORT_VALUE,
290
+ CF_NO_PROTOCOL_KEY,
291
+ CF_READONLY_KEY,
292
+ type SyncedState,
184
293
  type WebSocketHandlers,
185
294
  type WebSocketMessage,
186
295
  WebSockets,
187
296
  type WebSocketsOptions,
188
- callablesFromDecorated,
189
- callablesRpcUrl,
190
- isCallablesRpcUpgrade
297
+ capnWebTransportUrl,
298
+ isCapnWebTransportUpgrade,
299
+ registerInternalConnectionKeys
191
300
  };
192
301
  //# sourceMappingURL=index.d.ts.map
@@ -1,2 +1,3 @@
1
- import { a as isCallablesRpcUpgrade, i as callablesRpcUrl, n as CALLABLES_RPC_QUERY, o as callablesFromDecorated, r as CALLABLES_RPC_VALUE, t as WebSockets } from "../websockets-DUfRHPRq.js";
2
- export { CALLABLES_RPC_QUERY, CALLABLES_RPC_VALUE, WebSockets, callablesFromDecorated, callablesRpcUrl, isCallablesRpcUpgrade };
1
+ import { a as isCapnWebTransportUpgrade, i as capnWebTransportUrl, r as CAPNWEB_TRANSPORT_VALUE, t as CAPNWEB_TRANSPORT_QUERY } from "../transport-protocol-BxyngQ_R.js";
2
+ import { l as registerInternalConnectionKeys, n as CF_NO_PROTOCOL_KEY, r as CF_READONLY_KEY, t as WebSockets } from "../websockets-D7IzWbZb.js";
3
+ export { CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE, CF_NO_PROTOCOL_KEY, CF_READONLY_KEY, WebSockets, capnWebTransportUrl, isCapnWebTransportUpgrade, registerInternalConnectionKeys };