agents 0.14.5 → 0.16.0

package/dist/{agent-tool-types-V25Z_HcX.d.ts → agent-tool-types-NofdbL9X.d.ts}

@@ -1,10 +1,10 @@
 import { n as AgentEmail } from "./internal_context-Dg4Cgjcu.js";
-import { t as RetryOptions } from "./retries-CF_HKSlJ.js";
+import { t as RetryOptions } from "./retries-CwlpAGet.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-CPe1OtI0.js";
+} from "./index-B7IbEeze.js";
 import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-D4ZwyBDu.js";
 import {
   _ as WorkflowPage,
@@ -60,6 +60,12 @@ import {
   Tool as Tool$1
 } from "@modelcontextprotocol/sdk/types.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  EventStore as EventStore$1,
+  StreamId as StreamId$1,
+  WebStandardStreamableHTTPServerTransport,
+  WebStandardStreamableHTTPServerTransportOptions
+} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
   Transport,
@@ -72,10 +78,7 @@ import {
   EventStore,
   StreamId
 } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import {
-  EventStore as EventStore$1,
-  StreamId as StreamId$1
-} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 
 //#region src/sub-routing.d.ts
 /**
@@ -240,136 +243,150 @@ declare class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTran
 }
 //#endregion
 //#region src/mcp/worker-transport.d.ts
+/**
+ * Pluggable storage adapter for persisting `WorkerTransport` state across
+ * Durable Object hibernation / restart cycles.
+ *
+ * A typical implementation reads/writes a single key on `this.ctx.storage`
+ * inside a Durable Object or Agent.
+ */
 interface MCPStorageApi {
   get(): Promise<TransportState | undefined> | TransportState | undefined;
   set(state: TransportState): Promise<void> | void;
 }
+/** Shape of the persisted transport state. */
 interface TransportState {
   sessionId?: string;
   initialized: boolean;
   initializeParams?: InitializeRequestParams;
 }
-interface WorkerTransportOptions {
-  /**
-   * Function that generates a session ID for the transport.
-   * The session ID SHOULD be globally unique and cryptographically secure.
-   * Return undefined to disable session management (stateless mode).
-   */
-  sessionIdGenerator?: () => string;
+interface WorkerTransportOptions extends WebStandardStreamableHTTPServerTransportOptions {
   /**
-   * Enable traditional Request/Response mode, this will disable streaming.
+   * CORS options applied to every response and to OPTIONS preflight.
+   * Defaults: `origin: *`, expose `mcp-session-id`, allow the standard MCP
+   * methods/headers, max-age 86400.
    */
-  enableJsonResponse?: boolean;
-  /**
-   * Callback fired when a new session is initialized.
-   */
-  onsessioninitialized?: (sessionId: string) => void;
-  /**
-   * Callback fired when a session is closed via DELETE request.
-   */
-  onsessionclosed?: (sessionId: string) => void;
   corsOptions?: CORSOptions;
   /**
-   * Optional storage api for persisting transport state.
-   * Use this to store session state in Durable Object/Agent storage
-   * so it survives hibernation/restart.
+   * Optional storage adapter for persisting transport state across DO
+   * hibernation / restart. Use this to keep an MCP session alive across
+   * Durable Object wake-ups.
    */
   storage?: MCPStorageApi;
-  /**
-   * Event store for SSE resumability.
-   *
-   * When set, the transport assigns a globally-unique `id:` to each SSE
-   * event and replays missed events when a client reconnects with the
-   * `Last-Event-ID` header. Both GET (standalone listen stream) and POST
-   * (tool response stream) events are stored and replayable per the
-   * MCP 2025-03-26 spec.
-   *
-   * Configuring an event store **disables the server-side keepalive**
-   * on the standalone GET stream — idle drops are recovered by
-   * reconnect rather than prevented by writing bytes. Without an event
-   * store, the GET stream still gets the 25s comment-frame keepalive
-   * so long-lived idle listeners aren't closed by the Cloudflare edge
-   * ~5min watchdog.
-   *
-   * POST response streams always get the keepalive regardless of this
-   * setting: in-progress tool calls have no way to recover
-   * mid-execution without staying connected, so we don't let the
-   * stream drop in the first place.
-   *
-   * Bring your own {@link EventStore} implementation — e.g.
-   * `new DurableObjectEventStore(this.ctx.storage)` when embedding
-   * `WorkerTransport` inside a Durable Object / Agent. See
-   * cloudflare/agents#1583.
-   */
-  eventStore?: EventStore;
-  /**
-   * Retry interval in milliseconds to suggest to clients in SSE retry field.
-   * Controls client reconnection timing for polling behavior.
-   */
-  retryInterval?: number;
 }
-declare class WorkerTransport implements Transport {
-  started: boolean;
-  private initialized;
-  private sessionIdGenerator?;
-  private enableJsonResponse;
-  private onsessioninitialized?;
-  private onsessionclosed?;
-  private standaloneSseStreamId;
-  private streamMapping;
-  private requestToStreamMapping;
-  private requestResponseMap;
-  private corsOptions?;
-  private storage?;
-  private stateRestored;
-  private eventStore?;
-  private retryInterval?;
-  private initializeParams?;
-  sessionId?: string;
-  onclose?: () => void;
-  onerror?: (error: Error) => void;
-  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
+declare class WorkerTransport extends WebStandardStreamableHTTPServerTransport {
+  private readonly _corsOptions?;
+  private readonly _storage?;
+  private _stateRestored;
+  private _capturedInitializeParams?;
+  private _userOnSessionInitialized?;
+  private _bridgeInstalled;
+  /**
+   * Tracks keepalive interval cleanups so we can fire them eagerly when the
+   * SDK closes the underlying SSE stream via `closeSSEStream(requestId)` or
+   * `closeStandaloneSSEStream()`. Keyed by the JSON-RPC request id that
+   * triggered the stream, or the sentinel for the standalone GET stream.
+   */
+  private readonly _keepaliveCleanups;
+  /**
+   * Most recent JSON-RPC request id seen on an incoming POST. Used to key
+   * keepalive cleanups when the response is an SSE stream tied to that
+   * request (so `closeSSEStream(id)` can find and clear the interval).
+   */
+  private _pendingRequestId?;
+  /**
+   * Request ids whose SSE stream was deliberately torn down via
+   * `closeSSEStream`. The SDK's `send()` throws "No connection established"
+   * when a request id has no stream — a race that surfaces whenever the
+   * server's tool handler resolves *after* the caller closed the stream
+   * (e.g. polling-style early-close, or test fixtures closing mid-flight).
+   * We swallow `send()` for these ids so the rejection doesn't bubble out
+   * of the protocol layer as an unhandled rejection. Mirrors the
+   * silent-noop behaviour of the pre-refactor `WorkerTransport`.
+   */
+  private readonly _closedRequestIds;
   constructor(options?: WorkerTransportOptions);
   /**
-   * Restore transport state from persistent storage.
-   * This is automatically called on start.
+   * Backwards-compatible alias for the SDK's internal `_started` flag.
+   * Several callers and tests check `transport.started` directly.
    */
-  private restoreState;
+  get started(): boolean;
   /**
-   * Persist current transport state to storage.
+   * Top-level request entry point. Handles CORS preflight, restores any
+   * persisted state on first invocation, then delegates to the SDK transport
+   * and finally appends CORS headers + keepalive to whatever response comes
+   * back.
    */
-  private saveState;
-  start(): Promise<void>;
+  handleRequest(
+    request: Request,
+    options?: {
+      parsedBody?: unknown;
+      authInfo?: AuthInfo;
+    }
+  ): Promise<Response>;
   /**
-   * Validates the MCP-Protocol-Version header on incoming requests.
-   *
-   * This performs a simple check: if a version header is present, it must be
-   * in the SUPPORTED_PROTOCOL_VERSIONS list. We do not track the negotiated
-   * version or enforce version consistency across requests - the SDK handles
-   * version negotiation during initialization, and we simply reject any
-   * explicitly unsupported versions.
-   *
-   * - Header present and supported: Accept
-   * - Header present and unsupported: 400 Bad Request
-   * - Header missing: Accept (version validation is optional)
-   */
-  private validateProtocolVersion;
-  private getHeaders;
-  handleRequest(request: Request, parsedBody?: unknown): Promise<Response>;
-  private handleGetRequest;
-  private handlePostRequest;
-  private handleDeleteRequest;
-  private handleOptionsRequest;
-  private handleUnsupportedRequest;
-  private validateSession;
+   * The SDK's 405 responses advertise `Allow: GET, POST, DELETE` because
+   * OPTIONS is handled outside the SDK. Since our wrapper *does* handle
+   * OPTIONS, advertise it in `Allow` so clients can probe accurately.
+   */
+  private normalizeAllowHeader;
+  closeSSEStream(requestId: RequestId): void;
+  closeStandaloneSSEStream(): void;
   close(): Promise<void>;
   /**
-   * Close an SSE stream for a specific request, triggering client reconnection.
-   * Use this to implement polling behavior during long-running operations -
-   * client will reconnect after the retry interval specified in the priming event.
+   * Swallow two classes of message that would otherwise surface as
+   * unhandled rejections from the SDK transport's `send()`:
+   *
+   *   1. Replayed initialize responses (the `RESTORE_REQUEST_ID` sentinel)
+   *      — we synthesise these in `restoreState()` to rebuild server
+   *      capabilities; there's no real client waiting for the response.
+   *   2. Sends for a request id whose SSE stream has been deliberately
+   *      closed via `closeSSEStream`. The protocol layer's tool-handler
+   *      promise may settle after the close, and the SDK's `send()` throws
+   *      "No connection established" — a race the pre-refactor transport
+   *      silently swallowed.
+   *
+   * Everything else is delegated. We use `await super.send(...)` rather
+   * than `return super.send(...)` so any rejection is observed inside this
+   * async frame; without the await, the test runner's
+   * unhandled-rejection tracker can fire before the caller's own `await`
+   * observes it.
    */
-  closeSSEStream(requestId: RequestId): void;
   send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+  /**
+   * If the response is an SSE stream, tee the body through a TransformStream
+   * that injects a `: keepalive\n\n` comment frame every 25s. The interval
+   * is cleared when the wrapped stream closes — which happens both when the
+   * SDK ends the underlying stream naturally and when `closeSSEStream` is
+   * called.
+   *
+   * Keepalive policy:
+   *   - POST response streams (`key` is a request id): always keepalive.
+   *     In-progress tool calls have no recovery path — if the stream drops
+   *     mid-execution the result is lost — so we keep it under the
+   *     Cloudflare edge ~5min idle watchdog.
+   *   - Standalone GET stream (`key === "_standalone"`): keepalive only
+   *     when no `eventStore` is configured. When resumability is enabled,
+   *     clients reconnect with `Last-Event-ID` after an idle drop, so we
+   *     skip the keepalive and let the DO hibernate.
+   *
+   * Uses the shared `sse-keepalive` constants so both this wrapper and
+   * `McpAgent.serve()` write identical frames at the same cadence.
+   * See cloudflare/agents#1583.
+   */
+  private withKeepalive;
+  /**
+   * Does the SDK transport have an `eventStore`? Reaches into the SDK's
+   * private field because the option isn't surfaced on the public API —
+   * we only need a yes/no for keepalive policy.
+   */
+  private eventStoreConfigured;
+  private getCorsHeaders;
+  private withCorsHeaders;
+  private installOnSessionInitializedBridge;
+  private captureInitializeParams;
+  private restoreState;
+  private saveState;
 }
 //#endregion
 //#region src/mcp/auth-context.d.ts
@@ -2326,7 +2343,15 @@ interface AgentStaticOptions {
   /**
    * Maximum age in milliseconds of an unmanaged interrupted-fiber row before
    * recovery stops retrying a repeatedly-throwing `onFiberRecovered()` hook
-   * and discards the row. Set to `0` to retain rows indefinitely.
+   * and discards the row (emitting `fiber:recovery:skipped` with reason
+   * `max_age_exceeded`). Defaults to 24h.
+   *
+   * Set to `0` to retain rows indefinitely. NOTE: with `0`, a hook that keeps
+   * throwing is retried forever — the recovery alarm backs off exponentially
+   * (capped at 5 minutes) so it is not a busy-loop, but the Durable Object
+   * stays warm (never idle-evicts) for as long as the un-recoverable row
+   * exists. Prefer a finite age unless you intend to inspect/clear such rows
+   * yourself.
    */
   fiberRecoveryMaxAgeMs?: number;
   /**
@@ -2450,6 +2475,13 @@ declare class Agent<
   private _managedFiberTerminalWaiters;
   /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
   private _runFiberRecoveryInProgress;
+  /**
+   * @internal Consecutive runFiber-recovery scans that made NO forward progress
+   * while work was still pending. Drives the exponential backoff of the
+   * recovery follow-up alarm so a repeatedly-throwing recovery hook does not
+   * busy-loop the DO. Reset to 0 whenever a scan recovers anything.
+   */
+  private _recoveryNoProgressScans;
   /** @internal Single-flight background recovery for parent agent-tool rows. */
   private _agentToolRunRecoveryPromise;
   private _ParentClass;
@@ -3279,6 +3311,18 @@ declare class Agent<
     targetPath: ReadonlyArray<AgentPathStep>
   ): Promise<void>;
   private _executeScheduleCallback;
+  /**
+   * Whether any runFiber recovery work is still outstanding: orphaned
+   * `cf_agents_runs` rows left by a dead process (excluding fibers currently
+   * executing in memory, which already hold a keepAlive ref) or managed
+   * ledger fibers stuck in a non-terminal state with no live run row.
+   *
+   * Used by `_scheduleNextAlarm` to arm a follow-up alarm so multi-pass
+   * recovery (e.g. after a scan-deadline yield, or while retrying a throwing
+   * recovery hook) resumes instead of starving.
+   * @internal
+   */
+  private _hasPendingFiberRecovery;
   private _scheduleNextAlarm;
   /**
    * Override PartyServer's onAlarm hook as a no-op.
@@ -3844,6 +3888,32 @@ declare class Agent<
    * callers should treat it as fire-and-forget.
    */
   destroy(): Promise<void>;
+  /**
+   * @internal Defer this agent's destruction to its own alarm invocation
+   * instead of running it inline (#1625).
+   *
+   * `destroy()` is a multi-step I/O sequence (drop tables, delete alarm,
+   * delete all storage, dispose connections). Running it on the `waitUntil`
+   * of a request whose client has already disconnected — the MCP
+   * Streamable-HTTP session-DELETE path — gives it little to no
+   * post-invocation grace, so the runtime routinely cancels it mid-flight.
+   * This method instead performs two fast storage writes (a durable
+   * "condemned" marker and an immediate alarm) that the caller can await
+   * before responding; the alarm then fires as a fresh invocation with its
+   * own full execution budget and runs `destroy()` there. If even that
+   * invocation is interrupted, the marker survives and the next wake
+   * finishes teardown — see the `alarm()` preamble.
+   *
+   * Unlike `destroy()`, this method does not abort the isolate, so RPC
+   * callers don't need to swallow an abort error.
+   */
+  _cf_scheduleDestroy(): Promise<void>;
+  /**
+   * Whether a (deferred or interrupted) destroy is pending. Reads the
+   * durable marker directly — the in-memory `_isFacet` flag may not be
+   * hydrated yet at the call sites, but facets never write the marker.
+   */
+  private _hasPendingDestroy;
   /** @internal Drop every internal Agents SDK table during top-level destroy. */
   protected _dropInternalTablesForDestroy(): void;
   /**
@@ -4777,4 +4847,4 @@ export {
   MCPServer as z,
   WorkerTransport as zt
 };
-//# sourceMappingURL=agent-tool-types-V25Z_HcX.d.ts.map
+//# sourceMappingURL=agent-tool-types-NofdbL9X.d.ts.map

package/dist/agent-tool-types.d.ts

@@ -16,7 +16,7 @@ import {
   s as AgentToolInterruptedReason,
   t as AgentToolChildAdapter,
   u as AgentToolRunInspection
-} from "./agent-tool-types-V25Z_HcX.js";
+} from "./agent-tool-types-NofdbL9X.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,

package/dist/{agent-tools-C-9s151X.d.ts → agent-tools-DLquv-dp.d.ts}

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-V25Z_HcX.js";
+} from "./agent-tool-types-NofdbL9X.js";
 
 //#region src/chat/agent-tools.d.ts
 declare function createAgentToolEventState(): AgentToolEventState;
@@ -11,4 +11,4 @@ declare function applyAgentToolEvent(
 ): AgentToolEventState;
 //#endregion
 export { createAgentToolEventState as n, applyAgentToolEvent as t };
-//# sourceMappingURL=agent-tools-C-9s151X.d.ts.map
+//# sourceMappingURL=agent-tools-DLquv-dp.d.ts.map

package/dist/agent-tools.d.ts

@@ -16,7 +16,7 @@ import {
   s as AgentToolInterruptedReason,
   t as AgentToolChildAdapter,
   u as AgentToolRunInspection
-} from "./agent-tool-types-V25Z_HcX.js";
+} from "./agent-tool-types-NofdbL9X.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/browser/ai.d.ts

@@ -1,21 +1,133 @@
-import { t as BrowserToolsOptions } from "../shared-4CAYLCTO.js";
+import {
+  c as BrowserSessionStore,
+  f as BrowserBinding,
+  r as BrowserConnectorSessionOptions,
+  t as BrowserConnector
+} from "../connector-DXursxV5.js";
 import { ToolSet } from "ai";
+import { CodemodeRuntimeHandle } from "@cloudflare/codemode";
 
 //#region src/browser/ai.d.ts
+interface CreateBrowserToolsOptions {
+  /**
+   * Durable Object state. The codemode runtime that backs the browser tool
+   * lives in a facet of this DO, and browser session ids are stored in its
+   * storage — so the tool must be created from inside a Durable Object
+   * (e.g. an Agent).
+   *
+   * The worker must export the `CodemodeRuntime` class (the
+   * `@cloudflare/codemode/vite` plugin does this automatically, or add
+   * `export { CodemodeRuntime } from "@cloudflare/codemode"` to your entry).
+   */
+  ctx: DurableObjectState;
+  /**
+   * WorkerLoader binding for sandboxed code execution.
+   *
+   * Requires `"worker_loaders": [{ "binding": "LOADER" }]` in wrangler.jsonc.
+   */
+  loader: WorkerLoader;
+  /**
+   * Browser Rendering binding (Fetcher).
+   *
+   * This is the primary way to connect — works both locally in
+   * `wrangler dev` and when deployed to Cloudflare Workers.
+   *
+   * Requires `"browser": { "binding": "BROWSER" }` in wrangler.jsonc.
+   */
+  browser?: BrowserBinding;
+  /**
+   * Optional CDP base URL override (e.g. `http://localhost:9222`).
+   *
+   * Use when connecting to a manually managed Chrome instance or
+   * a remote CDP endpoint behind a tunnel.
+   */
+  cdpUrl?: string;
+  /**
+   * Headers to send with CDP URL discovery requests.
+   * Useful when the CDP endpoint requires authentication
+   * (e.g. Cloudflare Access headers).
+   */
+  cdpHeaders?: Record<string, string>;
+  /**
+   * Browser session lifecycle (binding-backed only). Defaults to one fresh
+   * session per codemode execution (`one-shot`).
+   */
+  session?: BrowserConnectorSessionOptions;
+  /**
+   * Durable store for Browser Run session ids. Defaults to a
+   * {@link DurableBrowserSessionStore} over `ctx.storage`.
+   */
+  store?: BrowserSessionStore;
+  /**
+   * Sandbox execution timeout in milliseconds. Defaults to 30000 (30s).
+   * Also used as the per-CDP-command timeout.
+   */
+  timeout?: number;
+  /**
+   * Codemode runtime name — the durable identity of the tool's executions
+   * and snippets. Defaults to `"browser"`.
+   */
+  name?: string;
+}
+/**
+ * The browser tool's moving parts, for hosts that need more than the tools:
+ *
+ * - `runtime` — the codemode runtime handle (approve/reject paused runs,
+ *   `expirePaused`, audit via `executions()`, snippets).
+ * - `connector` — host-side session helpers: `sessionInfo()`,
+ *   `closeSession()`, and `sweep()` for a recurring cleanup task.
+ * - `tools` — what `createBrowserTools` returns.
+ */
+interface BrowserRuntime {
+  runtime: CodemodeRuntimeHandle;
+  connector: BrowserConnector;
+  tools: ToolSet;
+}
+/**
+ * Create the browser codemode runtime: the `browser_execute` tool plus the
+ * runtime handle and connector for host-side wiring (approvals, session info,
+ * sweeps).
+ *
+ * @example
+ * ```ts
+ * export class MyAgent extends Agent<Env> {
+ *   get browser() {
+ *     return createBrowserRuntime({
+ *       ctx: this.ctx,
+ *       browser: this.env.BROWSER,
+ *       loader: this.env.LOADER,
+ *       session: { mode: "dynamic" }
+ *     });
+ *   }
+ *
+ *   @callable()
+ *   async closeBrowserSession() {
+ *     await this.browser.connector.closeSession();
+ *   }
+ * }
+ * ```
+ */
+declare function createBrowserRuntime(
+  options: CreateBrowserToolsOptions
+): BrowserRuntime;
 /**
  * Create AI SDK tools for browser automation via CDP code mode.
  *
- * Returns a `ToolSet` with `search` (query the CDP spec) and
- * `execute` (run CDP commands against a live browser).
+ * Returns a `ToolSet` with a single durable `browser_execute` tool backed by
+ * a codemode runtime: the model writes TypeScript against the `cdp` connector
+ * (`cdp.send`, `cdp.attachToTarget`, `cdp.spec`, …), executions are recorded
+ * for abort-and-replay, and browser sessions survive pauses.
  *
  * @example
  * ```ts
  * import { createBrowserTools } from "agents/browser/ai";
  * import { generateText } from "ai";
  *
+ * // inside a Durable Object / Agent:
  * const browserTools = createBrowserTools({
- *   browser: env.BROWSER,
- *   loader: env.LOADER,
+ *   ctx: this.ctx,
+ *   browser: this.env.BROWSER,
+ *   loader: this.env.LOADER,
  * });
  *
  * const result = await generateText({
@@ -25,7 +137,14 @@ import { ToolSet } from "ai";
  * });
  * ```
  */
-declare function createBrowserTools(options: BrowserToolsOptions): ToolSet;
+declare function createBrowserTools(
+  options: CreateBrowserToolsOptions
+): ToolSet;
 //#endregion
-export { type BrowserToolsOptions, createBrowserTools };
+export {
+  BrowserRuntime,
+  CreateBrowserToolsOptions,
+  createBrowserRuntime,
+  createBrowserTools
+};
 //# sourceMappingURL=ai.d.ts.map