agents 0.25.0 → 0.27.0

package/dist/websearch/tools/pi.js

@@ -0,0 +1,89 @@
+import { i as WebSearchError, n as createWebSearchToolCore, u as MAX_WEB_SEARCH_QUERY_LENGTH } from "../../tool-3PA8xjB_.js";
+import { Type } from "@earendil-works/pi-ai";
+//#region src/websearch/tools/pi.ts
+/**
+* `agents/websearch/pi` — the `web_search` tool for the pi harness.
+*
+* @beta
+*/
+/**
+* The model's input schema. The description tells the model the host's
+* `limit`; a larger value is not rejected (which would cost a validation
+* round trip) but capped by the core. pi already coerces `"5"` to `5`.
+*/
+function webSearchParameters(maxLimit) {
+	return Type.Object({
+		query: Type.String({
+			minLength: 1,
+			maxLength: MAX_WEB_SEARCH_QUERY_LENGTH,
+			description: "What to search for."
+		}),
+		limit: Type.Optional(Type.Integer({
+			minimum: 1,
+			description: `How many results to return (at most ${maxLimit}).`
+		}))
+	});
+}
+/**
+* Create a pi tool that searches the web through Cloudflare's Web Search
+* API. Install it on a registry like any other pi tool.
+*
+* The model chooses the query and (within the host's `limit`) how many
+* results; the host chooses the gateway, provider, and billing. The tool is
+* `replay: "safe"`: a search interrupted mid-call (say, by an eviction) runs
+* again when the session recovers, which is a second billed search.
+* Completed results are stored and not searched again.
+*
+* @example
+* ```ts
+* import { createRegistry } from "@earendil-works/pi-durable";
+* import { webSearchTool } from "agents/websearch/pi";
+*
+* const registry = createRegistry();
+* registry.install({
+*   name: "tools",
+*   tools: [webSearchTool({ binding: env.AI, provider: "exa" })]
+* });
+* ```
+*/
+function webSearchTool(options) {
+	const core = createWebSearchToolCore(options);
+	return {
+		name: core.name,
+		description: core.description,
+		parameters: webSearchParameters(core.limit),
+		replay: "safe",
+		async execute(input, _api, context) {
+			const run = await core.run(input, { signal: context.abortSignal });
+			if (run.ok) return {
+				content: [{
+					type: "text",
+					text: run.text
+				}],
+				details: {
+					ok: true,
+					output: run.output
+				}
+			};
+			return {
+				content: [{
+					type: "text",
+					text: run.text
+				}],
+				isError: true,
+				details: {
+					ok: false,
+					message: run.error.message,
+					status: run.error.status,
+					code: run.error.code,
+					retryable: run.error.retryable,
+					requestId: run.error.requestId
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { WebSearchError, webSearchTool };
+
+//# sourceMappingURL=pi.js.map

package/dist/websearch/tools/pi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi.js","names":[],"sources":["../../../src/websearch/tools/pi.ts"],"sourcesContent":["/**\n * `agents/websearch/pi` — the `web_search` tool for the pi harness.\n *\n * @beta\n */\nimport { Type } from \"@earendil-works/pi-ai\";\nimport type { ToolRegistration } from \"@earendil-works/pi-durable\";\nimport {\n  MAX_WEB_SEARCH_QUERY_LENGTH,\n  type WebSearchToolOutput\n} from \"../contract\";\nimport type { WebSearchErrorCode } from \"../source\";\nimport { createWebSearchToolCore, type WebSearchToolOptions } from \"../tool\";\n\nexport type {\n  WebSearchResponse,\n  WebSearchResult,\n  WebSearchToolInput,\n  WebSearchToolOutput\n} from \"../contract\";\nexport {\n  WebSearchError,\n  type WebSearchErrorCode,\n  type WebSearchProvider,\n  type WebSearchSource\n} from \"../source\";\nexport type { WebSearchToolOptions } from \"../tool\";\n\n/**\n * The model's input schema. The description tells the model the host's\n * `limit`; a larger value is not rejected (which would cost a validation\n * round trip) but capped by the core. pi already coerces `\"5\"` to `5`.\n */\nfunction webSearchParameters(maxLimit: number) {\n  return Type.Object({\n    query: Type.String({\n      minLength: 1,\n      maxLength: MAX_WEB_SEARCH_QUERY_LENGTH,\n      description: \"What to search for.\"\n    }),\n    limit: Type.Optional(\n      Type.Integer({\n        minimum: 1,\n        description: `How many results to return (at most ${maxLimit}).`\n      })\n    )\n  });\n}\n\ntype WebSearchParameters = ReturnType<typeof webSearchParameters>;\n\n/**\n * Host-side details pi stores with each `web_search` result: the full API\n * response (untrimmed descriptions, provider metadata) or the failure.\n */\nexport type WebSearchToolDetails =\n  | { ok: true; output: WebSearchToolOutput }\n  | {\n      ok: false;\n      /** The source's error message, with the API's detail. */\n      message: string;\n      status: number;\n      code: WebSearchErrorCode;\n      retryable: boolean;\n      requestId?: string;\n    };\n\n/**\n * Create a pi tool that searches the web through Cloudflare's Web Search\n * API. Install it on a registry like any other pi tool.\n *\n * The model chooses the query and (within the host's `limit`) how many\n * results; the host chooses the gateway, provider, and billing. The tool is\n * `replay: \"safe\"`: a search interrupted mid-call (say, by an eviction) runs\n * again when the session recovers, which is a second billed search.\n * Completed results are stored and not searched again.\n *\n * @example\n * ```ts\n * import { createRegistry } from \"@earendil-works/pi-durable\";\n * import { webSearchTool } from \"agents/websearch/pi\";\n *\n * const registry = createRegistry();\n * registry.install({\n *   name: \"tools\",\n *   tools: [webSearchTool({ binding: env.AI, provider: \"exa\" })]\n * });\n * ```\n */\nexport function webSearchTool(\n  options: WebSearchToolOptions\n): ToolRegistration<WebSearchParameters, WebSearchToolDetails> {\n  const core = createWebSearchToolCore(options);\n  return {\n    name: core.name,\n    description: core.description,\n    parameters: webSearchParameters(core.limit),\n    replay: \"safe\",\n    async execute(input, _api, context) {\n      const run = await core.run(input, { signal: context.abortSignal });\n      if (run.ok) {\n        return {\n          content: [{ type: \"text\", text: run.text }],\n          details: { ok: true, output: run.output }\n        };\n      }\n      return {\n        content: [{ type: \"text\", text: run.text }],\n        isError: true,\n        details: {\n          ok: false,\n          message: run.error.message,\n          status: run.error.status,\n          code: run.error.code,\n          retryable: run.error.retryable,\n          requestId: run.error.requestId\n        }\n      };\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAiCA,SAAS,oBAAoB,UAAkB;CAC7C,OAAO,KAAK,OAAO;EACjB,OAAO,KAAK,OAAO;GACjB,WAAW;GACX,WAAW;GACX,aAAa;EACf,CAAC;EACD,OAAO,KAAK,SACV,KAAK,QAAQ;GACX,SAAS;GACT,aAAa,uCAAuC,SAAS;EAC/D,CAAC,CACH;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,cACd,SAC6D;CAC7D,MAAM,OAAO,wBAAwB,OAAO;CAC5C,OAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK;EAClB,YAAY,oBAAoB,KAAK,KAAK;EAC1C,QAAQ;EACR,MAAM,QAAQ,OAAO,MAAM,SAAS;GAClC,MAAM,MAAM,MAAM,KAAK,IAAI,OAAO,EAAE,QAAQ,QAAQ,YAAY,CAAC;GACjE,IAAI,IAAI,IACN,OAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,IAAI;IAAK,CAAC;IAC1C,SAAS;KAAE,IAAI;KAAM,QAAQ,IAAI;IAAO;GAC1C;GAEF,OAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,IAAI;IAAK,CAAC;IAC1C,SAAS;IACT,SAAS;KACP,IAAI;KACJ,SAAS,IAAI,MAAM;KACnB,QAAQ,IAAI,MAAM;KAClB,MAAM,IAAI,MAAM;KAChB,WAAW,IAAI,MAAM;KACrB,WAAW,IAAI,MAAM;IACvB;GACF;EACF;CACF;AACF"}

package/dist/websearch/tools/tanstack-ai.d.ts

@@ -0,0 +1,71 @@
+import {
+  C as WebSearchResponse,
+  E as WebSearchToolOutput,
+  S as WEB_SEARCH_TOOL_NAME,
+  T as WebSearchToolInput,
+  c as WebSearchError,
+  d as WebSearchProvider,
+  l as WebSearchErrorCode,
+  p as WebSearchSource,
+  r as WebSearchToolOptions,
+  w as WebSearchResult
+} from "../../tool-BPJEbwaX.js";
+
+//#region src/websearch/tools/tanstack-ai.d.ts
+type TanStackWebSearchToolOptions<
+  TName extends string = typeof WEB_SEARCH_TOOL_NAME
+> = WebSearchToolOptions & {
+  /** The tool's name. TanStack AI tools carry it in the definition. */ name?: TName;
+};
+/**
+ * Create a TanStack AI tool that searches the web through Cloudflare's Web
+ * Search API. TanStack AI has one return channel, so the model and the host
+ * both get the trimmed text rendering. A failed search throws a
+ * `WebSearchError`, which TanStack AI reports as an error result: its
+ * `message` is written for the model, and its `cause` is the source's error
+ * with the API's detail. The tool is named `web_search` unless you pass
+ * `name`.
+ *
+ * @example
+ * ```ts
+ * import { webSearchTool } from "agents/websearch/tanstack-ai";
+ * import { chat } from "@tanstack/ai";
+ *
+ * const stream = chat({
+ *   adapter,
+ *   tools: [webSearchTool({ binding: env.AI })],
+ *   messages
+ * });
+ * ```
+ */
+declare function webSearchTool<
+  TName extends string = typeof WEB_SEARCH_TOOL_NAME
+>(
+  options: TanStackWebSearchToolOptions<TName>
+): import("@tanstack/ai").ServerTool<
+  import("zod").ZodObject<
+    {
+      query: import("zod").ZodString;
+      limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    },
+    import("zod/v4/core").$strip
+  >,
+  import("@tanstack/ai").SchemaInput,
+  TName,
+  unknown
+>;
+//#endregion
+export {
+  TanStackWebSearchToolOptions,
+  WebSearchError,
+  type WebSearchErrorCode,
+  type WebSearchProvider,
+  type WebSearchResponse,
+  type WebSearchResult,
+  type WebSearchSource,
+  type WebSearchToolInput,
+  type WebSearchToolOptions,
+  type WebSearchToolOutput,
+  webSearchTool
+};
+//# sourceMappingURL=tanstack-ai.d.ts.map

package/dist/websearch/tools/tanstack-ai.js

@@ -0,0 +1,46 @@
+import { i as WebSearchError, n as createWebSearchToolCore, r as toolFailure } from "../../tool-3PA8xjB_.js";
+import { t as webSearchInputSchema } from "../../input-schema-DNrpTu49.js";
+import { toolDefinition } from "@tanstack/ai";
+//#region src/websearch/tools/tanstack-ai.ts
+/**
+* `agents/websearch/tanstack-ai` — the `web_search` tool for TanStack AI.
+*
+* @beta
+*/
+/**
+* Create a TanStack AI tool that searches the web through Cloudflare's Web
+* Search API. TanStack AI has one return channel, so the model and the host
+* both get the trimmed text rendering. A failed search throws a
+* `WebSearchError`, which TanStack AI reports as an error result: its
+* `message` is written for the model, and its `cause` is the source's error
+* with the API's detail. The tool is named `web_search` unless you pass
+* `name`.
+*
+* @example
+* ```ts
+* import { webSearchTool } from "agents/websearch/tanstack-ai";
+* import { chat } from "@tanstack/ai";
+*
+* const stream = chat({
+*   adapter,
+*   tools: [webSearchTool({ binding: env.AI })],
+*   messages
+* });
+* ```
+*/
+function webSearchTool(options) {
+	const core = createWebSearchToolCore(options);
+	return toolDefinition({
+		name: options.name ?? core.name,
+		description: core.description,
+		inputSchema: webSearchInputSchema(core.limit)
+	}).server(async (input, context) => {
+		const run = await core.run(input, { signal: context?.abortSignal });
+		if (!run.ok) throw toolFailure(run);
+		return run.text;
+	});
+}
+//#endregion
+export { WebSearchError, webSearchTool };
+
+//# sourceMappingURL=tanstack-ai.js.map

package/dist/websearch/tools/tanstack-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../../src/websearch/tools/tanstack-ai.ts"],"sourcesContent":["/**\n * `agents/websearch/tanstack-ai` — the `web_search` tool for TanStack AI.\n *\n * @beta\n */\nimport { toolDefinition } from \"@tanstack/ai\";\nimport type { WEB_SEARCH_TOOL_NAME } from \"../contract\";\nimport {\n  createWebSearchToolCore,\n  toolFailure,\n  type WebSearchToolOptions\n} from \"../tool\";\nimport { webSearchInputSchema } from \"./input-schema\";\n\nexport type {\n  WebSearchResponse,\n  WebSearchResult,\n  WebSearchToolInput,\n  WebSearchToolOutput\n} from \"../contract\";\nexport {\n  WebSearchError,\n  type WebSearchErrorCode,\n  type WebSearchProvider,\n  type WebSearchSource\n} from \"../source\";\nexport type { WebSearchToolOptions } from \"../tool\";\n\nexport type TanStackWebSearchToolOptions<\n  TName extends string = typeof WEB_SEARCH_TOOL_NAME\n> = WebSearchToolOptions & {\n  /** The tool's name. TanStack AI tools carry it in the definition. */\n  name?: TName;\n};\n\n/**\n * Create a TanStack AI tool that searches the web through Cloudflare's Web\n * Search API. TanStack AI has one return channel, so the model and the host\n * both get the trimmed text rendering. A failed search throws a\n * `WebSearchError`, which TanStack AI reports as an error result: its\n * `message` is written for the model, and its `cause` is the source's error\n * with the API's detail. The tool is named `web_search` unless you pass\n * `name`.\n *\n * @example\n * ```ts\n * import { webSearchTool } from \"agents/websearch/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * const stream = chat({\n *   adapter,\n *   tools: [webSearchTool({ binding: env.AI })],\n *   messages\n * });\n * ```\n */\nexport function webSearchTool<\n  TName extends string = typeof WEB_SEARCH_TOOL_NAME\n>(options: TanStackWebSearchToolOptions<TName>) {\n  const core = createWebSearchToolCore(options);\n  return toolDefinition({\n    name: options.name ?? (core.name as TName),\n    description: core.description,\n    inputSchema: webSearchInputSchema(core.limit)\n  }).server(async (input, context) => {\n    const run = await core.run(input, { signal: context?.abortSignal });\n    if (!run.ok) throw toolFailure(run);\n    return run.text;\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,SAAgB,cAEd,SAA8C;CAC9C,MAAM,OAAO,wBAAwB,OAAO;CAC5C,OAAO,eAAe;EACpB,MAAM,QAAQ,QAAS,KAAK;EAC5B,aAAa,KAAK;EAClB,aAAa,qBAAqB,KAAK,KAAK;CAC9C,CAAC,CAAC,CAAC,OAAO,OAAO,OAAO,YAAY;EAClC,MAAM,MAAM,MAAM,KAAK,IAAI,OAAO,EAAE,QAAQ,SAAS,YAAY,CAAC;EAClE,IAAI,CAAC,IAAI,IAAI,MAAM,YAAY,GAAG;EAClC,OAAO,IAAI;CACb,CAAC;AACH"}

package/dist/websockets/index.d.ts

@@ -1,10 +1,3 @@
-import {
-  S as ConnectionContext,
-  T as WSMessage,
-  r as CapabilityWebSocketUpgradeContext,
-  s as LifecycleCapability,
-  x as Connection
-} from "../capability-runner-DBAnGr6L.js";
 import {
   a as capnWebTransportUrl,
   n as CAPNWEB_TRANSPORT_QUERY,
@@ -12,294 +5,18 @@ import {
   r as CAPNWEB_TRANSPORT_VALUE,
   t as AgentTransport
 } from "../transport-protocol-ZTew5Wso.js";
-import { RpcTarget } from "cloudflare:workers";
-
-//#region src/websockets/options.d.ts
-/**
- * The part of a `State` capability the WebSockets capability uses. A
- * structural port, so any `State<T>` fits without a cast and the
- * capability never depends on the class itself.
- */
-type SyncedState = {
-  /** Current state, or `undefined` when nothing is stored. */ get(): unknown /** Validate and persist a change; throws when the host rejects it. */;
-  set(nextState: never, source: Connection): void;
-};
-/** A frame delivered on a capability-owned WebSocket connection. */
-type WebSocketMessage = WSMessage;
-/**
- * Connection handlers for the WebSockets capability. Handlers run inside
- * the host invocation boundary with the live connection in ambient
- * context (`getCurrentAgent().connection`).
- *
- * @experimental The API surface may change before stabilizing.
- */
-type WebSocketHandlers = {
-  /** Handle a newly accepted hibernating WebSocket connection. */ onConnect?(
-    connection: Connection,
-    ctx: ConnectionContext
-  ): void | Promise<void> /** Handle a message from a hibernating WebSocket connection. */;
-  onMessage?(
-    connection: Connection,
-    message: WebSocketMessage
-  ): void | Promise<void> /** Handle a closing hibernating WebSocket connection. */;
-  onClose?(
-    connection: Connection,
-    code: number,
-    reason: string,
-    wasClean: boolean
-  ): void | Promise<void> /** Handle a mid-connection WebSocket error. */;
-  onError?(connection: Connection, error: unknown): void | Promise<void>;
-};
-/**
- * Configuration for the WebSockets capability.
- *
- * @experimental The API surface may change before stabilizing.
- */
-interface WebSocketsOptions {
-  /**
-   * Connection handlers for WebSocket clients. The capability accepts and
-   * tracks every WebSocket upgrade either way; handlers add behavior on
-   * connect, message, close and error.
-   */
-  readonly handlers?: WebSocketHandlers;
-  /**
-   * An `RpcTarget` whose prototype methods are the host's complete remote
-   * interface, reached through `useAgent().call` and `.stub`. On the
-   * `cf-websocket` wire they are answered as JSON `rpc` frames. On the
-   * `capnweb` wire they are native Cap'n Web methods on the session root:
-   * an `RpcTarget` result becomes a live stub, a `ReadableStream` streams,
-   * and calls pipeline. Methods run through the host invocation boundary
-   * with the calling connection in scope. `Agent` answers its own
-   * decorated methods on the JSON wire and does not set this.
-   */
-  readonly callables?: RpcTarget;
-  /**
-   * Whether a new connection gets the connect-time protocol frames —
-   * identity (`cf_agent_identity`), then the current state when `state`
-   * is set — and whether protocol frames reach it at all.
-   *
-   * - `true` (default): every connection.
-   * - a function: decided per connection at accept time. `false` marks
-   *   the connection no-protocol: it gets no protocol text frames, on
-   *   connect or via `broadcastState()`, but can still send and receive
-   *   ordinary messages and use callables. For binary-only clients.
-   * - `false`: the host drives the connect sequence itself with
-   *   `sendConnectFrames()` (or `sendIdentity()` and `sendState()`
-   *   separately), and applies client state frames
-   *   with `applyStateFrame()` — `Agent` does this, since it must decide
-   *   whether a connection belongs to a facet before any frame is sent.
-   */
-  readonly protocol?:
-    | boolean
-    | ((connection: Connection, ctx: ConnectionContext) => boolean);
-  /**
-   * Decide at accept time whether a connection is readonly. A readonly
-   * connection's `cf_agent_state` frames are refused with
-   * `cf_agent_state_error`; everything else works. Also settable later
-   * with `setReadonly()`.
-   */
-  readonly readonly?: (
-    connection: Connection,
-    ctx: ConnectionContext
-  ) => boolean;
-  /**
-   * A {@link SyncedState} — normally a `State` capability — to sync over
-   * connections. The capability pushes the current value to each new
-   * connection after identity and applies `cf_agent_state` frames a
-   * client sends: a readonly connection is refused, and a change the
-   * host's validator rejects is answered with `cf_agent_state_error`.
-   * Broadcasting a change is the state owner's call — wire the `State`'s
-   * `onChanged` to `broadcastState(source)`. Install the same instance on
-   * the lifecycle so it owns storage and validation; without this option
-   * state is never sent or accepted over connections.
-   */
-  readonly state?: SyncedState;
-  /**
-   * Tags attached to each accepted connection, queryable through
-   * `getConnections(tag)`. The connection id is always the first tag.
-   */
-  readonly getConnectionTags?: (
-    connection: Connection,
-    ctx: ConnectionContext
-  ) => string[] | Promise<string[]>;
-}
-//#endregion
-//#region src/websockets/websockets.d.ts
-/**
- * Opt-in WebSocket support for Lifecycle Objects.
- *
- * Lifecycle itself does not model WebSockets — hosts that want them
- * install this capability, which owns the connection subsystem end to
- * end: it claims upgrades, dispatches `onConnect`/`onMessage`/`onClose`
- * inside the host invocation boundary, reciprocates close handshakes,
- * and answers `getConnections()`/`getConnection()`.
- *
- * ```ts
- * class Room extends DurableObject<Env> {
- *   readonly webSockets = new WebSockets({
- *     handlers: {
- *       onConnect: (connection) => connection.send("welcome"),
- *       onMessage: (connection, message) => { ... }
- *     },
- *     callables: new RoomCallables()
- *   });
- *   readonly lifecycle = Lifecycle.install(this).use(this.webSockets);
- * }
- * ```
- *
- * Connections arrive on one of two wires, chosen by the client:
- *
- * - **cf-websocket** (default): accepted with the Hibernation API. Idle
- *   clients stay connected while the Durable Object leaves memory.
- * - **capnweb** (`?__agents_transport=capnweb`): protocol frames through
- *   one pipe method on a Cap'n Web session whose root also carries the
- *   host's callables natively. Non-hibernating — the object stays pinned
- *   while the connection is open.
- *
- * Both wires dispatch the same handlers and appear in `getConnections()`.
- * On both, the capability speaks the Agent protocol a plain host needs
- * for `useAgent` and `AgentClient`: it sends the identity frame on
- * connect, and it serves `callables` — as `rpc` JSON frames on the
- * WebSocket wire, and natively on the Cap'n Web session root, where an
- * `RpcTarget` result becomes a live stub and calls pipeline. `call()`
- * and `stub` work against a plain Durable Object exactly as against an
- * `Agent`. Pass a `State` capability as `state` and the hook's
- * `state`/`setState` work too: the current value is pushed on connect
- * and client updates are validated and applied; the state owner
- * broadcasts changes with `broadcastState()`. Per-connection readonly
- * and no-protocol flags live here as well, for every host.
- *
- * @experimental The API surface may change before stabilizing.
- */
-declare class WebSockets extends LifecycleCapability {
-  #private;
-  /** Claims every upgrade, so Lifecycle dispatches it after all others. */
-  readonly claims = "catch-all";
-  constructor(options?: WebSocketsOptions);
-  /**
-   * Claim every upgrade, never declining: a Cap'n Web transport upgrade
-   * becomes a session, everything else a tracked hibernating connection,
-   * whether or not handlers or callables are configured. Handlers only add
-   * behavior on connect, message, close, and error.
-   */
-  onWebSocketUpgrade({
-    request
-  }: CapabilityWebSocketUpgradeContext): Promise<Response>;
-  /** Dispatch a platform message wake for a capability-owned socket. */
-  onWebSocketMessage(
-    ws: WebSocket,
-    message: WebSocketMessage
-  ): Promise<boolean>;
-  /** Dispatch and reciprocate a close wake for an owned socket. */
-  onWebSocketClose(
-    ws: WebSocket,
-    code: number,
-    reason: string,
-    wasClean: boolean
-  ): Promise<boolean>;
-  /** Dispatch an error wake for an owned socket. */
-  onWebSocketError(ws: WebSocket, error: unknown): Promise<boolean>;
-  /**
-   * Close every owned connection during explicit host destruction. The
-   * capability owns its sockets' lifetimes, so it also owns tearing
-   * them down.
-   */
-  dispose(): void;
-  /** Open connections on either wire, optionally by tag. */
-  getConnections<TState = unknown>(
-    tag?: string
-  ): IterableIterator<Connection<TState>>;
-  /** One connection on either wire, by id. */
-  getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
-  /**
-   * Send the connect sequence: the identity frame, then the current state
-   * when one is stored. The identity carries `stateFollows` in that case,
-   * so clients resolve `ready` only once the state has landed. Nothing is
-   * sent to a no-protocol connection. Identity defaults as for
-   * `sendIdentity()`.
-   */
-  sendConnectFrames(
-    connection: Connection,
-    identity?: {
-      name: string;
-      agent: string;
-    }
-  ): void;
-  /**
-   * Send the identity frame alone, unless the connection is no-protocol.
-   * Clients resolve `ready` on it, so a host that also pushes state on
-   * connect should use `sendConnectFrames()`. The defaults are the Durable
-   * Object's routed name and host class; a host whose public identity
-   * differs — an `Agent` facet, whose routed name is an internal encoding
-   * of its logical name — passes its own.
-   */
-  sendIdentity(
-    connection: Connection,
-    identity?: {
-      name: string;
-      agent: string;
-    }
-  ): void;
-  /**
-   * Send the current state to one connection, unless nothing is stored
-   * or the connection is no-protocol. Reading the state may seed the
-   * initial value; see `#connecting`.
-   */
-  sendState(connection: Connection): void;
-  /**
-   * Apply a parsed `cf_agent_state` frame from a client. A readonly
-   * connection is refused; a change the host's validator rejects is
-   * logged in full server-side and answered with a generic
-   * `cf_agent_state_error`. Broadcasting the accepted change is the state
-   * owner's call, through its `onChanged` hook. Callers that drive the
-   * protocol themselves call this inside their own invocation context;
-   * the capability's automatic path does so via `runInHostContext`.
-   *
-   * @returns Whether the frame was a state frame (handled either way).
-   */
-  applyStateFrame(connection: Connection, frame: unknown): boolean;
-  /**
-   * Push the current state to every protocol-enabled connection except
-   * the one a change came from, which already has the value it sent.
-   * Wire a `State`'s `onChanged` to this.
-   */
-  broadcastState(except?: Connection | "server"): void;
-  /** Whether the connection may update host state over the wire. */
-  isReadonly(connection: Connection): boolean;
-  /** Mark a connection readonly, or writable again. */
-  setReadonly(connection: Connection, readonly?: boolean): void;
-  /** Whether protocol text frames reach the connection. */
-  isProtocolEnabled(connection: Connection): boolean;
-  /** Enable or suppress protocol text frames for a connection. */
-  setProtocolEnabled(connection: Connection, enabled: boolean): void;
-}
-//#endregion
-//#region src/websockets/connection-flags.d.ts
-/**
- * Internal per-connection flags, stored inside the connection's own state
- * under `_cf_`-prefixed keys so they ride the hibernation attachment (or a
- * bridged connection's synced state) and survive a wake. The state wrapper
- * installed by {@link ensureConnectionWrapped} hides them from
- * `connection.state` and preserves them across user `setState` calls.
- *
- * Owned by the WebSockets capability; `Agent` and framework mixins reach it
- * through the capability or, for their own keys, through
- * {@link registerInternalConnectionKeys}.
- */
-/** A readonly connection may not update host state. */
-declare const CF_READONLY_KEY = "_cf_readonly";
-/**
- * A no-protocol connection receives no protocol text frames (identity,
- * state sync, MCP servers) — neither on connect nor via broadcasts.
- */
-declare const CF_NO_PROTOCOL_KEY = "_cf_no_protocol";
-/**
- * Register additional `_cf_`-prefixed keys a host or mixin stores in
- * connection state, so they are hidden from `connection.state` and kept
- * across user `setState` calls like the capability's own flags.
- */
-declare function registerInternalConnectionKeys(...keys: string[]): void;
-//#endregion
+import {
+  i as WebSocketsOptions,
+  n as WebSocketHandlers,
+  r as WebSocketMessage,
+  t as SyncedState
+} from "../options-pwTNq9z6.js";
+import {
+  i as WebSockets,
+  n as CF_READONLY_KEY,
+  r as registerInternalConnectionKeys,
+  t as CF_NO_PROTOCOL_KEY
+} from "../index-Ib_4dwOo.js";
 export {
   type AgentTransport,
   CAPNWEB_TRANSPORT_QUERY,
@@ -315,4 +32,3 @@ export {
   isCapnWebTransportUpgrade,
   registerInternalConnectionKeys
 };
-//# sourceMappingURL=index.d.ts.map

package/dist/websockets/index.js

@@ -1,3 +1,3 @@
 import { a as isCapnWebTransportUpgrade, i as capnWebTransportUrl, r as CAPNWEB_TRANSPORT_VALUE, t as CAPNWEB_TRANSPORT_QUERY } from "../transport-protocol-BxyngQ_R.js";
-import { l as registerInternalConnectionKeys, n as CF_NO_PROTOCOL_KEY, r as CF_READONLY_KEY, t as WebSockets } from "../websockets-Ci-LZFHH.js";
+import { l as registerInternalConnectionKeys, n as CF_NO_PROTOCOL_KEY, r as CF_READONLY_KEY, t as WebSockets } from "../websockets-CmENGb-Z.js";
 export { CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE, CF_NO_PROTOCOL_KEY, CF_READONLY_KEY, WebSockets, capnWebTransportUrl, isCapnWebTransportUpgrade, registerInternalConnectionKeys };

package/dist/{websockets-Ci-LZFHH.js → websockets-CmENGb-Z.js}

@@ -571,6 +571,7 @@ function isRpcRequest(value) {
 	return frame.type === "rpc" && typeof frame.id === "string" && typeof frame.method === "string" && Array.isArray(frame.args);
 }
 var _handlers = /* @__PURE__ */ new WeakMap();
+var _added = /* @__PURE__ */ new WeakMap();
 var _getConnectionTags = /* @__PURE__ */ new WeakMap();
 var _protocol = /* @__PURE__ */ new WeakMap();
 var _readonly = /* @__PURE__ */ new WeakMap();
@@ -632,6 +633,7 @@ var WebSockets = class extends LifecycleCapability {
 		_classPrivateMethodInitSpec(this, _WebSockets_brand);
 		this.claims = "catch-all";
 		_classPrivateFieldInitSpec(this, _handlers, void 0);
+		_classPrivateFieldInitSpec(this, _added, []);
 		_classPrivateFieldInitSpec(this, _getConnectionTags, void 0);
 		_classPrivateFieldInitSpec(this, _protocol, void 0);
 		_classPrivateFieldInitSpec(this, _readonly, void 0);
@@ -688,6 +690,14 @@ var WebSockets = class extends LifecycleCapability {
 			connection.close(1001, "Durable Object destroyed");
 		} catch {}
 	}
+	/**
+	* Add handlers for another component sharing these connections, such as
+	* a protocol of its own. They run before the configured handlers, and
+	* their `onMessage` can claim a message by returning true.
+	*/
+	use(handlers) {
+		_classPrivateFieldGet2(_added, this).push(handlers);
+	}
 	/** Open connections on either wire, optionally by tag. */
 	*getConnections(tag) {
 		for (const { connection } of _classPrivateFieldGet2(_sessions, this).values()) {
@@ -836,7 +846,7 @@ async function _connect(connection, ctx) {
 	if (_classPrivateFieldGet2(_readonly, this)?.call(this, connection, ctx)) setConnectionReadonly(connection, true);
 	if (_classPrivateFieldGet2(_protocol, this) !== false) if (typeof _classPrivateFieldGet2(_protocol, this) === "function" ? _classPrivateFieldGet2(_protocol, this).call(this, connection, ctx) : true) this.sendConnectFrames(connection);
 	else setConnectionProtocolEnabled(connection, false);
-	await this.lifecycle.runInHostContext(() => _classPrivateFieldGet2(_handlers, this)?.onConnect?.(connection, ctx), {
+	for (const handlers of [..._classPrivateFieldGet2(_added, this), _classPrivateFieldGet2(_handlers, this)]) await this.lifecycle.runInHostContext(() => handlers?.onConnect?.(connection, ctx), {
 		connection,
 		request: ctx.request
 	});
@@ -850,13 +860,17 @@ async function _message(connection, message) {
 		}
 	}
 	if (_classPrivateFieldGet2(_callables, this).size > 0 && await _assertClassBrand(_WebSockets_brand, this, _answerRpc).call(this, connection, message)) return;
+	for (const handlers of _classPrivateFieldGet2(_added, this)) if (await this.lifecycle.runInHostContext(() => handlers.onMessage?.(connection, message), { connection }) === true) return;
 	await this.lifecycle.runInHostContext(() => _classPrivateFieldGet2(_handlers, this)?.onMessage?.(connection, message), { connection });
 }
 function _close(connection, code, reason, wasClean) {
-	return this.lifecycle.runInHostContext(() => _classPrivateFieldGet2(_handlers, this)?.onClose?.(connection, code, reason, wasClean), { connection });
+	return _assertClassBrand(_WebSockets_brand, this, _each).call(this, (handlers) => this.lifecycle.runInHostContext(() => handlers?.onClose?.(connection, code, reason, wasClean), { connection }));
 }
 function _error(connection, error) {
-	return this.lifecycle.runInHostContext(() => _classPrivateFieldGet2(_handlers, this)?.onError?.(connection, error), { connection });
+	return _assertClassBrand(_WebSockets_brand, this, _each).call(this, (handlers) => this.lifecycle.runInHostContext(() => handlers?.onError?.(connection, error), { connection }));
+}
+async function _each(run) {
+	for (const handlers of [..._classPrivateFieldGet2(_added, this), _classPrivateFieldGet2(_handlers, this)]) await run(handlers);
 }
 async function _acceptConnection(request) {
 	const { 0: clientWebSocket, 1: serverWebSocket } = new WebSocketPair();
@@ -1027,4 +1041,4 @@ async function _dispatchCallable(name, invoke, connection) {
 //#endregion
 export { getConnectionFlag as a, isConnectionReadonly as c, setConnectionProtocolEnabled as d, setConnectionReadonly as f, ensureConnectionWrapped as i, registerInternalConnectionKeys as l, CF_NO_PROTOCOL_KEY as n, getConnectionRawState as o, CF_READONLY_KEY as r, isConnectionProtocolEnabled as s, WebSockets as t, setConnectionFlag as u };
 
-//# sourceMappingURL=websockets-Ci-LZFHH.js.map
+//# sourceMappingURL=websockets-CmENGb-Z.js.map