agents 0.26.0 → 0.27.0

package/dist/options-pwTNq9z6.d.ts

@@ -0,0 +1,134 @@
+import {
+  S as ConnectionContext,
+  T as WSMessage,
+  x as Connection
+} from "./capability-runner-O5VbQzqg.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. For handlers
+   * added with `WebSockets.use`, returning true claims the message, so
+   * later handlers do not see it.
+   */
+  onMessage?(
+    connection: Connection,
+    message: WebSocketMessage
+  ):
+    | void
+    | boolean
+    | Promise<
+        void | boolean
+      > /** 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
+export {
+  WebSocketsOptions as i,
+  WebSocketHandlers as n,
+  WebSocketMessage as r,
+  SyncedState as t
+};
+//# sourceMappingURL=options-pwTNq9z6.d.ts.map

package/dist/protocol-BEgrJYC5.d.ts

@@ -0,0 +1,331 @@
+//#region src/harness/container/protocol.d.ts
+/**
+ * The wire between `ContainerHarness` (in a Durable Object) and the harness
+ * daemon (in the container). Isomorphic and dependency-free: the daemon
+ * imports it in Node, the harness in Workers.
+ *
+ * One WebSocket per session, dialled by the object through
+ * `ctx.container.getTcpPort(port)` at `/sessions/<id>`. The daemon speaks
+ * first with `hello`; the object answers with `open` (when the daemon does
+ * not hold the session yet) and `replay`, then delivers `prompt`s.
+ *
+ * Everything the daemon produces for a session is a numbered `frame`. The
+ * numbers start at 1 for each session in each container, so a frame is
+ * addressed by `(runtimeId, seq)`. The daemon keeps frames until they are
+ * acknowledged, so an object that lost its socket (evicted, redeployed)
+ * replays what it missed from its cursor. A different `runtimeId` in
+ * `hello` means a different container: its numbering starts again, and
+ * whatever the old container was doing is gone.
+ *
+ * @experimental The wire may change before it stabilizes. The object and the image are
+ * a matched pair; a version mismatch is reported in `hello`.
+ */
+/** Bumped on any incompatible change. */
+declare const CONTAINER_PROTOCOL_VERSION = 1;
+/** The daemon answers `200` here once it accepts connections. */
+declare const CONTAINER_HEALTH_PATH = "/healthz";
+/** The session socket: `/sessions/<encoded session id>`. */
+declare const CONTAINER_SESSION_PATH = "/sessions/";
+/** The shared secret the object passes on every request. */
+declare const CONTAINER_TOKEN_HEADER = "x-cf-harness-token";
+/** The environment variables the object starts the container with. */
+declare const CONTAINER_ENV: {
+  /** Shared secret for `CONTAINER_TOKEN_HEADER`. */ readonly token: "CF_HARNESS_TOKEN" /** This container's id. Echoed in `hello`. */;
+  readonly runtimeId: "CF_HARNESS_RUNTIME_ID" /** The port the daemon listens on. */;
+  readonly port: "CF_HARNESS_PORT";
+};
+/** WebSocket close code: a newer connection for the session replaced this one. */
+declare const CLOSE_REPLACED = 4001;
+/** WebSocket close code: the request was not authorized. */
+declare const CLOSE_UNAUTHORIZED = 4003;
+/** A JSON value on the wire. */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | {
+      readonly [key: string]: JsonValue;
+    };
+/** One part of a prompt. */
+type ContainerInputPart =
+  | {
+      readonly type: "text";
+      readonly text: string;
+    }
+  | {
+      readonly type: "image" /** IANA media type, such as `image/png`. */;
+      readonly mediaType: string /** Base64 bytes. */;
+      readonly data: string;
+    };
+/** What a prompt carries: plain text, or parts. */
+type ContainerInput = string | readonly ContainerInputPart[];
+/** What a submission does when the session is already running. */
+type ContainerWhenBusy = "followUp" | "steer";
+/**
+ * Per-session settings the object sends the adapter. `model` is the
+ * adapter's own model name; `options` is opaque to everything but the
+ * adapter.
+ */
+type ContainerSettings = {
+  readonly model?: string;
+  readonly options?: JsonValue;
+};
+/** One part of a transcript message. */
+type ContainerPart =
+  | {
+      readonly type: "text";
+      readonly text: string;
+    }
+  | {
+      readonly type: "reasoning";
+      readonly text: string;
+    }
+  | {
+      readonly type: "image";
+      readonly mediaType: string;
+      readonly data: string;
+    }
+  | {
+      readonly type: "tool";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly input: JsonValue;
+      readonly state: "running" | "done" | "error";
+      readonly output?: JsonValue;
+    };
+/**
+ * A transcript message, in the one format every container adapter
+ * produces. An adapter emits a message again, under the same id, to update
+ * it (a tool result arriving, for example).
+ */
+type ContainerMessage = {
+  readonly id: string;
+  readonly role: "user" | "assistant";
+  readonly parts: readonly ContainerPart[] /** The operation the message belongs to. */;
+  readonly operationId?: string;
+  readonly createdAt: number;
+};
+/** What an adapter reports while it runs. */
+type ContainerEvent =
+  /** Live text for an assistant message that is still being written. */ | {
+        readonly type: "text-delta";
+        readonly messageId: string;
+        readonly delta: string;
+      } /** Live reasoning for an assistant message that is still being written. */
+    | {
+        readonly type: "reasoning-delta";
+        readonly messageId: string;
+        readonly delta: string;
+      } /** A finished or updated transcript message. Stored. */
+    | {
+        readonly type: "message";
+        readonly message: ContainerMessage;
+      } /** Token and cost figures the adapter reports, as the adapter counts them. */
+    | {
+        readonly type: "usage";
+        readonly inputTokens?: number;
+        readonly outputTokens?: number;
+        readonly costUsd?: number;
+      } /** A diagnostic line. */
+    | {
+        readonly type: "log";
+        readonly level: "info" | "warn" | "error";
+        readonly message: string;
+      } /** Anything adapter-specific, passed through untouched. */
+    | {
+        readonly type: "raw";
+        readonly value: JsonValue;
+      };
+/** How an operation ended, as the daemon reports it. */
+type ContainerOutcome =
+  | {
+      readonly status: "done";
+      readonly text: string;
+    }
+  | {
+      readonly status: "unanswered";
+      readonly reason: string;
+    };
+/** What the daemon knows about one operation it was given. */
+type DaemonOperation =
+  | {
+      readonly operationId: string;
+      readonly status: "queued" | "running";
+    }
+  | {
+      readonly operationId: string;
+      readonly status: "settled";
+      readonly outcome: ContainerOutcome;
+    };
+/** One numbered thing the daemon produced for a session. */
+type DaemonFrame =
+  | {
+      readonly kind: "start";
+      readonly operationId: string;
+    }
+  | {
+      readonly kind: "event";
+      readonly operationId: string | null;
+      readonly event: ContainerEvent;
+    }
+  /**
+   * Adapter resume state to keep. The object stores these entries in order
+   * and hands all of them back in `open` on a new container.
+   */
+  | {
+      readonly kind: "persist";
+      readonly entries: readonly JsonValue[];
+    }
+  | {
+      readonly kind: "settle";
+      readonly operationId: string;
+      readonly outcome: ContainerOutcome;
+    };
+/** The adapter running in the container. */
+type AdapterInfo = {
+  readonly id: string;
+  readonly version: string;
+  readonly capabilities: readonly string[];
+};
+/** Daemon → object. */
+type DaemonMessage =
+  | {
+      readonly type: "hello";
+      readonly protocol: number;
+      readonly runtimeId: string;
+      readonly session: string;
+      readonly adapter: AdapterInfo /** The generation of the open adapter session, or null if none is open. */;
+      readonly open:
+        | number
+        | null /** The newest frame number for this session in this container. */;
+      readonly lastSeq: number /** Every operation this container was given for the session. */;
+      readonly operations: readonly DaemonOperation[];
+    }
+  | {
+      readonly type: "frame";
+      readonly seq: number;
+      readonly frame: DaemonFrame;
+    } /** Every kept frame after the `replay` cursor has been sent. */
+  | {
+      readonly type: "caught-up";
+      readonly lastSeq: number;
+    }
+  | {
+      readonly type: "error";
+      readonly message: string;
+    };
+/**
+ * Most JSON characters the object puts in one `restore` message, and the
+ * daemon in one `persist` frame (a single larger entry travels alone).
+ * Keeps every message well inside WebSocket message limits.
+ */
+declare const MAX_CHUNK_CHARS: number;
+/** Object → daemon. */
+type HostMessage =
+  /**
+   * Part of the resume state for the next `open` of `generation`. Sent
+   * before that `open`, in order, so no single message grows with the
+   * session's history.
+   */
+  | {
+      readonly type: "restore";
+      readonly generation: number;
+      readonly entries: readonly JsonValue[];
+    }
+  /**
+   * Open the adapter session. Ignored when the same generation is already
+   * open; a different generation closes the open one first.
+   */
+  | {
+      readonly type: "open";
+      readonly generation: number;
+      readonly settings: ContainerSettings;
+      /**
+       * The last of the entries the adapter persisted for this session,
+       * after any sent in `restore` messages for this generation.
+       */
+      readonly restore: readonly JsonValue[];
+    } /** Send every kept frame after `after`, then live frames. */
+  | {
+      readonly type: "replay";
+      readonly after: number;
+    } /** Queue an operation. Idempotent on `operationId`. */
+  | {
+      readonly type: "prompt";
+      readonly operationId: string;
+      readonly input: ContainerInput;
+      readonly whenBusy: ContainerWhenBusy;
+    } /** Stop one operation, or every operation of the session. */
+  | {
+      readonly type: "abort";
+      readonly operationId?: string;
+    }
+  | {
+      readonly type: "configure";
+      readonly settings: ContainerSettings;
+    } /** Frames up to `seq` are stored; the daemon may forget them. */
+  | {
+      readonly type: "ack";
+      readonly seq: number;
+    };
+/**
+ * Parse one message from the daemon.
+ *
+ * @param text - The raw WebSocket message.
+ * @returns The message, or `undefined` when it is not one.
+ */
+declare function parseDaemonMessage(text: string): DaemonMessage | undefined;
+/**
+ * Parse one message from the object.
+ *
+ * @param text - The raw WebSocket message.
+ * @returns The message, or `undefined` when it is not one.
+ */
+declare function parseHostMessage(text: string): HostMessage | undefined;
+/**
+ * The text of an input, with image parts left out.
+ *
+ * @param input - A prompt's input.
+ * @returns Its text.
+ */
+declare function inputText(input: ContainerInput): string;
+/**
+ * Split entries into groups whose JSON stays under `MAX_CHUNK_CHARS`. An
+ * entry larger than that is a group of its own.
+ *
+ * @param entries - The entries, in order.
+ * @returns The groups, in order. Empty for no entries.
+ */
+declare function chunkEntries(entries: readonly JsonValue[]): JsonValue[][];
+//#endregion
+export {
+  chunkEntries as C,
+  parseHostMessage as E,
+  MAX_CHUNK_CHARS as S,
+  parseDaemonMessage as T,
+  DaemonFrame as _,
+  CONTAINER_HEALTH_PATH as a,
+  HostMessage as b,
+  CONTAINER_TOKEN_HEADER as c,
+  ContainerInputPart as d,
+  ContainerMessage as f,
+  ContainerWhenBusy as g,
+  ContainerSettings as h,
+  CONTAINER_ENV as i,
+  ContainerEvent as l,
+  ContainerPart as m,
+  CLOSE_REPLACED as n,
+  CONTAINER_PROTOCOL_VERSION as o,
+  ContainerOutcome as p,
+  CLOSE_UNAUTHORIZED as r,
+  CONTAINER_SESSION_PATH as s,
+  AdapterInfo as t,
+  ContainerInput as u,
+  DaemonMessage as v,
+  inputText as w,
+  JsonValue as x,
+  DaemonOperation as y
+};
+//# sourceMappingURL=protocol-BEgrJYC5.d.ts.map