agents 0.23.0 → 0.25.0

package/dist/websockets/index.d.ts

@@ -1,13 +1,29 @@
 import {
-  b as Connection,
+  S as ConnectionContext,
+  T as WSMessage,
   r as CapabilityWebSocketUpgradeContext,
   s as LifecycleCapability,
-  w as WSMessage,
-  x as ConnectionContext
-} from "../capability-runner-Be_-PLR1.js";
+  x as Connection
+} from "../capability-runner-DBAnGr6L.js";
+import {
+  a as capnWebTransportUrl,
+  n as CAPNWEB_TRANSPORT_QUERY,
+  o as isCapnWebTransportUpgrade,
+  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;
 /**
@@ -41,19 +57,63 @@ type WebSocketHandlers = {
  */
 interface WebSocketsOptions {
   /**
-   * Connection handlers for WebSocket clients. When present, the
-   * capability claims WebSocket upgrades and owns those connections end
-   * to end. When absent, upgrades are declined.
+   * 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 methods are exposed to remote callers over a
-   * Cap'n Web session (`?__agents_rpc=capnweb`). The target's prototype
-   * methods are the complete remote interface. Methods run through the
-   * host invocation boundary and may return a `ReadableStream` to
-   * stream results.
+   * 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.
@@ -70,18 +130,16 @@ interface WebSocketsOptions {
  *
  * Lifecycle itself does not model WebSockets — hosts that want them
  * install this capability, which owns the connection subsystem end to
- * end: it claims upgrades, accepts hibernating sockets, dispatches
- * `onConnect`/`onMessage`/`onClose` inside the host invocation
- * boundary, reciprocates close handshakes, and answers
- * `getConnections()`/`getConnection()`.
+ * 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) => { ... },
- *       onClose: (connection, code) => { ... }
+ *       onMessage: (connection, message) => { ... }
  *     },
  *     callables: new RoomCallables()
  *   });
@@ -89,31 +147,44 @@ interface WebSocketsOptions {
  * }
  * ```
  *
- * `callables` exposes an `RpcTarget`'s prototype methods to remote
- * callers over a Cap'n Web session claimed from `?__agents_rpc=capnweb`
- * upgrades. Methods run through the host invocation boundary, may
- * return a `ReadableStream` to stream results, and emit
- * `rpc`/`rpc:error` capability events. Callable sessions are
- * non-hibernating: while a client holds one open, the Durable Object
- * stays pinned in memory.
+ * Connections arrive on one of two wires, chosen by the client:
  *
- * There is no separate browser client: against an `Agent`, the
- * `useAgent` hook's `stub`/`call` reach the same interface over the
- * protocol socket. A plain host's endpoint is reached with capnweb
- * directly — `newWebSocketRpcSession(new WebSocket(callablesRpcUrl(url)))`.
+ * - **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 callables RPC upgrades and, with handlers, plain upgrades. */
+  /**
+   * 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>
-    | Response
-    | undefined;
+  }: CapabilityWebSocketUpgradeContext): Promise<Response>;
   /** Dispatch a platform message wake for a capability-owned socket. */
   onWebSocketMessage(
     ws: WebSocket,
@@ -134,59 +205,114 @@ declare class WebSockets extends LifecycleCapability {
    * them down.
    */
   dispose(): void;
-  /** Open connections accepted by this capability, optionally by tag. */
+  /** Open connections on either wire, optionally by tag. */
   getConnections<TState = unknown>(
     tag?: string
   ): IterableIterator<Connection<TState>>;
-  /** One connection accepted by this capability, by id. */
+  /** 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/callables-target.d.ts
+//#region src/websockets/connection-flags.d.ts
 /**
- * Build a callables target from a host's `@callable()`-decorated
- * methods — the fallback interface source when no `RpcTarget` is
- * configured (an explicit target is preferred and wins).
+ * 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.
  *
- * Methods are resolved on the host at call time, so framework wrapping
- * applied after construction (e.g. Agent's context auto-wrapping) is
- * honored. Methods registered with `streaming: true` expect the legacy
- * Agent RPC protocol's injected `StreamingResponse` and are not exposed
- * here — return a `ReadableStream` from an `RpcTarget` method instead.
- *
- * @param host - The object whose decorated methods form the interface.
- * @returns A target exposing the decorated methods, or `undefined`
- * when the host has none.
+ * Owned by the WebSockets capability; `Agent` and framework mixins reach it
+ * through the capability or, for their own keys, through
+ * {@link registerInternalConnectionKeys}.
  */
-declare function callablesFromDecorated(host: object): RpcTarget | undefined;
-//#endregion
-//#region src/websockets/protocol.d.ts
+/** A readonly connection may not update host state. */
+declare const CF_READONLY_KEY = "_cf_readonly";
 /**
- * Isomorphic pieces of the callables RPC wire contract.
- *
- * Imported from browser bundles (via the client) and from the Worker
- * runtime, so it must not import `cloudflare:workers`.
+ * A no-protocol connection receives no protocol text frames (identity,
+ * state sync, MCP servers) — neither on connect nor via broadcasts.
  */
-/** Query parameter selecting the callables Cap'n Web RPC endpoint. */
-declare const CALLABLES_RPC_QUERY = "__agents_rpc";
-declare const CALLABLES_RPC_VALUE = "capnweb";
-/** Whether a request is a WebSocket upgrade addressed to callables RPC. */
-declare function isCallablesRpcUpgrade(request: Request): boolean;
+declare const CF_NO_PROTOCOL_KEY = "_cf_no_protocol";
 /**
- * Derive the callables RPC socket URL from a host route. Accepts http(s)
- * or ws(s) URLs and returns a ws(s) URL with the RPC query parameter set.
+ * 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 callablesRpcUrl(url: string | URL): string;
+declare function registerInternalConnectionKeys(...keys: string[]): void;
 //#endregion
 export {
-  CALLABLES_RPC_QUERY,
-  CALLABLES_RPC_VALUE,
+  type AgentTransport,
+  CAPNWEB_TRANSPORT_QUERY,
+  CAPNWEB_TRANSPORT_VALUE,
+  CF_NO_PROTOCOL_KEY,
+  CF_READONLY_KEY,
+  type SyncedState,
   type WebSocketHandlers,
   type WebSocketMessage,
   WebSockets,
   type WebSocketsOptions,
-  callablesFromDecorated,
-  callablesRpcUrl,
-  isCallablesRpcUpgrade
+  capnWebTransportUrl,
+  isCapnWebTransportUpgrade,
+  registerInternalConnectionKeys
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/websockets/index.js

@@ -1,2 +1,3 @@
-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";
-export { CALLABLES_RPC_QUERY, CALLABLES_RPC_VALUE, WebSockets, callablesFromDecorated, callablesRpcUrl, isCallablesRpcUpgrade };
+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";
+export { CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE, CF_NO_PROTOCOL_KEY, CF_READONLY_KEY, WebSockets, capnWebTransportUrl, isCapnWebTransportUpgrade, registerInternalConnectionKeys };