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.
- package/dist/{agent-routing-DE5zmCQ8.d.ts → agent-routing-B2XLNMxq.d.ts} +196 -189
- package/dist/agent-routing.d.ts +1 -1
- package/dist/agent-tool-types.d.ts +26 -26
- package/dist/{agent-tools-DtXMTDGM.d.ts → agent-tools-Dj5Mzlw7.d.ts} +7 -7
- package/dist/agent-tools.d.ts +21 -21
- package/dist/{capability-BjSKYpzg.js → capability-B4WbF81e.js} +2 -1
- package/dist/capability-B4WbF81e.js.map +1 -0
- package/dist/{capability-runner-Be_-PLR1.d.ts → capability-runner-BUBa6Ake.d.ts} +40 -15
- package/dist/chat/index.d.ts +14 -11
- package/dist/chat/index.js +11 -7
- package/dist/chat/index.js.map +1 -1
- package/dist/chat-sdk/index.d.ts +3 -3
- package/dist/chat-sdk/index.js +1 -1
- package/dist/client-BxdkCuVy.d.ts +411 -0
- package/dist/client-C9DAjZIY.js +518 -0
- package/dist/client-C9DAjZIY.js.map +1 -0
- package/dist/{client-jagG8a9_.js → client-fyQrLGkD.js} +2 -2
- package/dist/{client-jagG8a9_.js.map → client-fyQrLGkD.js.map} +1 -1
- package/dist/client.d.ts +27 -283
- package/dist/client.js +2 -274
- package/dist/current-agent-C4w86kcN.d.ts +93 -0
- package/dist/{current-agent-Da_C9a3b.d.ts → durable-object-lifecycle-ei7M7lqB.d.ts} +13 -122
- package/dist/index-Dlgtd3Mj.d.ts +78 -0
- package/dist/index.d.ts +59 -59
- package/dist/index.js +2 -2
- package/dist/internal_context.d.ts +1 -1
- package/dist/lifecycle/index.d.ts +19 -17
- package/dist/lifecycle/index.js +2 -2
- package/dist/{lifecycle-CMRGjZdw.js → lifecycle-Mm_jQh7r.js} +36 -21
- package/dist/lifecycle-Mm_jQh7r.js.map +1 -0
- package/dist/mcp/client/index.d.ts +20 -20
- package/dist/mcp/client/index.js +1 -1
- package/dist/mcp/index.d.ts +35 -35
- package/dist/mcp/index.js +2 -2
- package/dist/queue/index.d.ts +123 -0
- package/dist/queue/index.js +2 -0
- package/dist/queue-BC9F5cUo.js +406 -0
- package/dist/queue-BC9F5cUo.js.map +1 -0
- package/dist/react.d.ts +33 -15
- package/dist/react.js +31 -8
- package/dist/react.js.map +1 -1
- package/dist/{retries-D9Ds-1lz.d.ts → retries-D9B2UCq3.d.ts} +9 -3
- package/dist/retries.d.ts +5 -3
- package/dist/retries.js +9 -1
- package/dist/retries.js.map +1 -1
- package/dist/routing/index.d.ts +2 -2
- package/dist/routing/index.js +1 -1
- package/dist/{scheduler-Dwh85ZGl.d.ts → scheduler-BGq6M5Kd.d.ts} +6 -6
- package/dist/{scheduler-DD9NdYbF.js → scheduler-D_KHqxBa.js} +4 -11
- package/dist/scheduler-D_KHqxBa.js.map +1 -0
- package/dist/schedules/index.d.ts +1 -1
- package/dist/schedules/index.js +1 -1
- package/dist/serializable.d.ts +1 -1
- package/dist/sessions/index.d.ts +1 -1
- package/dist/sessions/index.js +1 -1
- package/dist/{src-DlSHshb2.js → src-BNU3ZiJM.js} +126 -393
- package/dist/src-BNU3ZiJM.js.map +1 -0
- package/dist/state/index.d.ts +6 -0
- package/dist/state/index.js +137 -0
- package/dist/state/index.js.map +1 -0
- package/dist/streams/index.d.ts +1 -1
- package/dist/streams/index.js +1 -1
- package/dist/{streams-D6tJ0NN9.d.ts → streams-BcE8JP2X.d.ts} +2 -2
- package/dist/{streams-DZKgAj9b.js → streams-CCPRV6dt.js} +2 -2
- package/dist/{streams-DZKgAj9b.js.map → streams-CCPRV6dt.js.map} +1 -1
- package/dist/sub-routing.d.ts +12 -12
- package/dist/tasks/index.d.ts +1 -1
- package/dist/tasks/index.js +1 -1
- package/dist/{tasks-ylZgBjhj.js → tasks-D4nLqVSI.js} +3 -3
- package/dist/{tasks-ylZgBjhj.js.map → tasks-D4nLqVSI.js.map} +1 -1
- package/dist/{tasks-BRJ5zgya.d.ts → tasks-V2lCT8ZV.d.ts} +5 -5
- package/dist/transport-protocol-BxyngQ_R.js +25 -0
- package/dist/transport-protocol-BxyngQ_R.js.map +1 -0
- package/dist/transport-protocol-ZTew5Wso.d.ts +27 -0
- package/dist/types-DCD6BNZH.d.ts +70 -0
- package/dist/voice/index.d.ts +2 -2
- package/dist/websockets/index.d.ts +178 -69
- package/dist/websockets/index.js +3 -2
- package/dist/websockets-D7IzWbZb.js +1005 -0
- package/dist/websockets-D7IzWbZb.js.map +1 -0
- package/dist/workflow-types.d.ts +25 -25
- package/dist/workflows.d.ts +21 -21
- package/dist/workflows.js +1 -1
- package/docs/agent-class.md +2 -2
- package/docs/client-sdk.md +30 -0
- package/docs/index.md +1 -1
- package/docs/lifecycle.md +97 -22
- package/docs/queue.md +135 -241
- package/docs/retries.md +1 -1
- package/docs/sub-agents.md +3 -3
- package/package.json +12 -2
- package/dist/capability-BjSKYpzg.js.map +0 -1
- package/dist/client.js.map +0 -1
- package/dist/lifecycle-CMRGjZdw.js.map +0 -1
- package/dist/scheduler-DD9NdYbF.js.map +0 -1
- package/dist/src-DlSHshb2.js.map +0 -1
- package/dist/websockets-DUfRHPRq.js +0 -502
- package/dist/websockets-DUfRHPRq.js.map +0 -1
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import {
|
|
2
|
-
_ as
|
|
2
|
+
_ as LifecycleJobContext,
|
|
3
3
|
d as LifecycleRouteContext,
|
|
4
|
-
g as LifecycleJobContext,
|
|
5
4
|
o as MemoryLimitContext,
|
|
6
|
-
s as LifecycleCapability
|
|
7
|
-
|
|
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-
|
|
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
|
package/dist/voice/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { c as Agent } from "../agent-routing-
|
|
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
|
-
|
|
2
|
+
S as ConnectionContext,
|
|
3
|
+
T as WSMessage,
|
|
3
4
|
r as CapabilityWebSocketUpgradeContext,
|
|
4
5
|
s as LifecycleCapability,
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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.
|
|
45
|
-
*
|
|
46
|
-
*
|
|
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
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
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,
|
|
74
|
-
*
|
|
75
|
-
*
|
|
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
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
* `
|
|
97
|
-
*
|
|
98
|
-
* stays pinned
|
|
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
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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/
|
|
260
|
+
//#region src/websockets/connection-flags.d.ts
|
|
146
261
|
/**
|
|
147
|
-
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
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
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
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
|
-
|
|
162
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
177
|
-
*
|
|
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
|
|
284
|
+
declare function registerInternalConnectionKeys(...keys: string[]): void;
|
|
180
285
|
//#endregion
|
|
181
286
|
export {
|
|
182
|
-
|
|
183
|
-
|
|
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
|
-
|
|
189
|
-
|
|
190
|
-
|
|
297
|
+
capnWebTransportUrl,
|
|
298
|
+
isCapnWebTransportUpgrade,
|
|
299
|
+
registerInternalConnectionKeys
|
|
191
300
|
};
|
|
192
301
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/websockets/index.js
CHANGED
|
@@ -1,2 +1,3 @@
|
|
|
1
|
-
import { a as
|
|
2
|
-
|
|
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 };
|