@workerdeck/core 0.6.0

package/build/index.d.mts

@@ -0,0 +1,848 @@
+import { Options, Query, SDKMessage, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import { LanguageModel, ModelMessage, Tool, ToolSet } from "ai";
+import { SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
+import { ApiMessage, CreateSessionRequest, McpServerConfigWire, PermissionMode, PermissionRequest, ProfileEngine, ProfileInfo, SessionEvent, SessionEventBody, SessionInfo, SessionStatus, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput } from "@workerdeck/protocol";
+
+//#region src/tool-executor.d.ts
+/**
+ * Result of one tool execution, whenever it arrives. `failed` is a normal
+ * outcome the agent loop adapts to — not an exception.
+ */
+type ToolExecutionResult = {
+  status: 'ok';
+  output: unknown;
+  logs?: string[];
+} | {
+  status: 'failed';
+  reason: string;
+  error: string;
+  logs?: string[];
+};
+type ToolExecutionCall = {
+  /** Stable, persisted correlation id. Results are matched and applied by it. */executionId: string;
+  sessionId: string; /** Tool name, e.g. 'eval_script'. */
+  tool: string; /** Validated tool input. */
+  input: unknown; /** Scoped scratch filesystem for this execution's thread. */
+  vfs?: SandboxVfs;
+  limits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  };
+  signal?: AbortSignal;
+};
+/**
+ * Dispatch outcome. `settled` carries the result inline; `pending` means it
+ * arrives out-of-band later, keyed by executionId — the shape that lets a
+ * deferred or remote executor drop in without touching the runner or protocol.
+ */
+type ToolExecutionDispatch = {
+  executionId: string;
+  status: 'settled';
+  result: ToolExecutionResult;
+} | {
+  executionId: string;
+  status: 'pending';
+};
+/**
+ * The seam between the agent loop and wherever code actually runs — in-process
+ * QuickJS, a browser tab over the WS bridge, or a managed sandbox. Backends are
+ * interchangeable and selected by context.
+ */
+/**
+ * How an executor will handle one specific call, asked before dispatch so the
+ * runner can announce it on `execution_dispatched` (which is emitted before the
+ * call goes out, so a bridged request never precedes its own record).
+ *
+ * Per **call**, not per executor: an executor that routes by tool name can send
+ * `eval_script` to the in-process sandbox and a long-running tool to a remote
+ * worker, and only the latter should park the session.
+ */
+type ToolExecutionProfile = {
+  /** Reported on `execution_dispatched`; falls back to the runner's configured default. */backend?: ToolExecutionBackend;
+  /**
+   * True when this execution may outlive not just the turn but the live runner:
+   * the session parks (state persisted, runner torn down) and the result arrives
+   * out of band, keyed by `executionId`.
+   */
+  deferred?: boolean;
+  /** Advisory deadline, published as `expiresAt`. For a deferred execution the
+   * timer itself belongs to the host — the runner may be gone when it fires. */
+  timeoutMs?: number;
+};
+interface ToolExecutor {
+  /** Describe what this call will be: backend, deferredness, deadline. Omitted =
+   * an in-band execution on the runner's configured backend. */
+  describe?(call: ToolExecutionCall): ToolExecutionProfile;
+  dispatch(call: ToolExecutionCall): Promise<ToolExecutionDispatch>;
+}
+//#endregion
+//#region src/runner-interface.d.ts
+type SessionEventListener = (event: SessionEvent) => void;
+/** One deferred execution a parked session is waiting on. */
+type ParkedExecution = {
+  executionId: string;
+  toolName: string; /** Epoch ms the host's execution watchdog should fire at, when the backend set one. */
+  expiresAt?: number;
+};
+/**
+ * Everything needed to rebuild a torn-down session under the same id — the durable
+ * half of deferred execution. The engine-neutral fields are what the host persists,
+ * indexes, and replays; `state` is the engine's own continuation state (for the
+ * provider engine, its ModelMessage history) and is **opaque** outside it. Keeping
+ * it opaque is what lets `packages/server` persist a provider session without ever
+ * importing a model SDK.
+ *
+ * Must stay JSON-serializable end to end: a durable store round-trips it verbatim.
+ * "Serializable" here means round-trips *unchanged* — a Date, a Map, or a typed
+ * array inside `state` survives `JSON.stringify` as something else and rehydrates
+ * wrong. Only the in-memory store hides that, by never serializing at all.
+ */
+type RunnerSnapshot = {
+  /** Engine that produced it. Rehydrating into a different one is refused. */engine: ProfileEngine; /** Session id the rebuilt runner must adopt. */
+  id: string;
+  createdAt: number;
+  /** Last emitted seq — the rebuilt runner continues numbering from here, so a
+   * client reattaching with `afterSeq` sees one unbroken stream. */
+  seq: number; /** The seq-numbered event log, replayed to clients on rehydration. */
+  events: SessionEvent[]; /** Scratch filesystem contents, for engines that have one. */
+  vfs?: Record<string, string>; /** The deferred executions this session parked on. */
+  parked: ParkedExecution[]; /** Engine-private continuation state. Never inspected by the host. */
+  state: unknown;
+};
+type PermissionDecision = {
+  behavior: 'allow';
+  updatedInput?: Record<string, unknown>;
+} | {
+  behavior: 'deny';
+  message?: string;
+  interrupt?: boolean;
+};
+/**
+ * Engine-independent runner surface — exactly what the server and queue consume.
+ * `SessionRunner` (Claude / Agent SDK) implements it today; additional engines
+ * implement the same contract and are selected behind it. Engine-specific
+ * machinery (SDK options, approval callbacks, input-queue shapes) stays inside
+ * the implementations.
+ */
+interface Runner {
+  readonly id: string;
+  readonly pendingApprovals: PermissionRequest[];
+  /** The session's scratch filesystem, when its engine has one. The server's
+   * file routes (GET /sessions/:id/files[...]) read it to serve deliverables;
+   * engines without a VFS (the Claude CLI engine) simply don't expose it. */
+  readonly vfs?: SandboxVfs;
+  /** Begin the session. Idempotent; returns the run promise (resolves when the run ends). */
+  start(): Promise<void>;
+  info(): SessionInfo;
+  /** Replay buffered events with seq > afterSeq, then deliver live events. Returns unsubscribe. */
+  subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+  /** Queue a user message for the session (starts the next turn when idle). */
+  sendMessage(text: string): void;
+  /** Resolve a pending permission request. Returns false if the id is unknown (e.g. timed out). */
+  resolvePermission(requestId: string, decision: PermissionDecision): boolean;
+  interrupt(): Promise<void>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  /** Switch the model for subsequent responses; undefined = back to the default. */
+  setModel(model?: string): Promise<void>;
+  /** Deliver the terminal result of an out-of-band tool execution (e.g. a bridged
+   * call answered by a browser client). Optional: engines that never execute
+   * out-of-band simply don't expose it. Idempotent by executionId — unknown or
+   * already-settled ids return false. */
+  settleExecution?(executionId: string, result: ToolExecutionResult): boolean;
+  /**
+   * Park: capture durable state, release engine resources, and go inert — without
+   * ending the session (no `session_closed`; the status becomes `parked`). The host
+   * persists the snapshot, drops the runner, and rebuilds it under the same id when
+   * a deferred execution's result arrives.
+   *
+   * Returns undefined when parking is not possible right now — a turn is in flight,
+   * nothing is actually parked, or the engine doesn't support it (the Claude engine
+   * doesn't: the CLI owns its own process state).
+   */
+  park?(): RunnerSnapshot | undefined;
+  /** Emit a session_error and terminate. For host-enforced policy (e.g. requireApiKey). */
+  fail(message: string): void;
+  /** Terminate the session and any underlying engine process. */
+  close(reason?: 'client' | 'server' | 'error'): void;
+}
+//#endregion
+//#region src/runner.d.ts
+type QueryFn = (params: {
+  prompt: AsyncIterable<SDKUserMessage>;
+  options?: Options;
+}) => Query;
+type HistoryFn = (sdkSessionId: string, options: {
+  dir?: string;
+}) => Promise<SessionMessage[]>;
+type SessionRunnerConfig = CreateSessionRequest & {
+  /** Injectable query implementation (tests, instrumentation). Defaults to the SDK's query(). */queryFn?: QueryFn; /** Environment for the spawned Claude Code process. Defaults to process.env. */
+  env?: Record<string, string | undefined>;
+  pathToClaudeCodeExecutable?: string; /** Escape hatch merged last into the SDK Options. */
+  extraOptions?: Partial<Options>; /** Timeout for pending approvals when the request itself doesn't set one. Default 300000. */
+  defaultApprovalTimeoutMs?: number;
+  /** With `resume`: emit the resumed session's history as replay events before the query
+   * starts, so late-attaching clients get a full transcript. Default true. */
+  backfillHistory?: boolean; /** Injectable history reader (tests). Defaults to the SDK's getSessionMessages. */
+  historyFn?: HistoryFn;
+};
+/**
+ * One live Agent SDK session: owns the query() call, the streaming input queue, the
+ * pending-approval table, and a seq-numbered event log that subscribers can replay.
+ * No transport — the server (or any host) subscribes and bridges to the wire.
+ */
+declare class SessionRunner implements Runner {
+  #private;
+  readonly id: string;
+  readonly createdAt: number;
+  constructor(config: SessionRunnerConfig, id?: string);
+  get status(): SessionStatus;
+  get sdkSessionId(): string | undefined;
+  get lastSeq(): number;
+  /** 'oauth' = claude.ai subscription credentials; other values are API-key provenance. */
+  get apiKeySource(): string | undefined;
+  get pendingApprovals(): PermissionRequest[];
+  info(): SessionInfo;
+  /** Begin the session. Idempotent; returns the run promise (resolves when the query ends). */
+  start(): Promise<void>;
+  /** Queue a user message for the session (starts the next turn when idle). */
+  sendMessage(text: string): void;
+  /** Resolve a pending permission request. Returns false if the id is unknown (e.g. timed out). */
+  resolvePermission(requestId: string, decision: PermissionDecision): boolean;
+  interrupt(): Promise<void>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  /** Switch the model for subsequent responses; undefined = back to the default. */
+  setModel(model?: string): Promise<void>;
+  /** Emit a session_error and terminate. For host-enforced policy (e.g. requireApiKey). */
+  fail(message: string): void;
+  /** Terminate the session and the underlying CLI subprocess. */
+  close(reason?: 'client' | 'server' | 'error'): void;
+  /**
+   * Replay buffered events with seq > afterSeq, then deliver live events.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+}
+//#endregion
+//#region src/ai-sdk-runner.d.ts
+/** `cwd` is optional for this engine: the loop has no host-filesystem coupling
+ * (tools get scoped VFS handles instead). Defaults to process.cwd() for display. */
+type AiSdkRunnerConfig = Omit<CreateSessionRequest, 'cwd'> & {
+  cwd?: string;
+  /** AI SDK language model instance (or gateway model id string). Provider
+   * resolution from profiles happens host-side; core takes the resolved model. */
+  languageModel: LanguageModel;
+  /** Tools available to the loop. Tools WITHOUT `execute` halt the loop when
+   * called; their calls surface via `pendingToolCalls` and are answered with
+   * `resolveToolCall()`, which re-enters the loop by message-state replay. */
+  tools?: ToolSet; /** System prompt (AI SDK v7 `instructions`). */
+  instructions?: string; /** Max loop steps per turn. Default 20. */
+  maxSteps?: number;
+  /**
+   * Executes tool calls the loop cannot run inline (tools declared without
+   * `execute`). With one set, the runner drives the whole cycle itself:
+   * dispatch on park, apply the result, re-enter. Without one, parked calls
+   * stay on {@link pendingToolCalls} for the host to answer via
+   * {@link resolveToolCall}.
+   */
+  executor?: ToolExecutor; /** Names the executor handles. Others stay pending for the host. */
+  executableTools?: string[]; /** Scratch filesystem handed to sandboxed executions. */
+  vfs?: SandboxVfs; /** Per-execution limits passed to the executor. */
+  executionLimits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  }; /** Which backend the executor represents, for `execution_dispatched` events. */
+  executionBackend?: ToolExecutionBackend; /** Swap models mid-session (`set_model`). Unset = setModel() is rejected. */
+  resolveModel?: (modelId: string | undefined) => LanguageModel;
+  /** Called once when the session closes — release per-session resources the
+   * host attached (an MCP connection, a watcher). Errors are swallowed. Also
+   * runs when the session parks: parking releases the same resources. */
+  onClose?: () => void | Promise<void>;
+  /**
+   * Rebuild a parked session from {@link AiSdkRunner.park}'s snapshot instead of
+   * starting a fresh one: the id, event log, seq counter, message history, and
+   * the executions it parked on are all adopted. The rest of the config is the
+   * live wiring (model, tools, executor, VFS) and is taken as given — a
+   * rehydrated session may legitimately come up against a re-created tool set.
+   */
+  restore?: RunnerSnapshot;
+};
+/** An external (execute-less) tool call the loop is parked on. */
+type PendingToolCall = {
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  /** True when the executor declared the execution deferred — the session may
+   * park on it, and only a host-delivered result can settle it. */
+  deferred?: boolean; /** Epoch ms the host's execution watchdog should fire at. */
+  expiresAt?: number;
+};
+/** The provider engine's half of a {@link RunnerSnapshot} — its continuation
+ * state. Opaque to the host; only this class reads it. */
+type AiSdkSessionState = {
+  messages: ModelMessage[];
+  pendingToolCalls: PendingToolCall[]; /** Calls already handed to an executor, so rehydration never re-dispatches them. */
+  dispatched: string[];
+  numTurns: number;
+  totalUsage: {
+    input: number;
+    output: number;
+    cacheWrite: number;
+    cacheRead: number;
+  };
+  /** The in-progress turn's accumulator: a parked turn's earlier legs still owe
+   * their tokens and elapsed time to the turn_result that eventually lands. */
+  turnAccum?: {
+    startedAt: number;
+    input: number;
+    output: number;
+    cacheWrite: number;
+    cacheRead: number;
+  };
+  permissionMode: PermissionMode;
+  /** Model alias last requested (config.model or a set_model), NOT the resolved
+   * provider model id — re-resolution goes back through `resolveModel`. */
+  model?: string;
+  lastActivityAt?: number;
+  /** When the snapshot was taken, so a rehydrated turn can discount the time it
+   * spent parked instead of billing it as elapsed turn duration. */
+  parkedAt?: number;
+};
+type ToolCallOutput = {
+  type: 'text';
+  value: string;
+} | {
+  type: 'json';
+  value: unknown;
+};
+/**
+ * Model-agnostic runner over the AI SDK v7 ToolLoopAgent. The session's durable
+ * state is its ModelMessage history: every turn — including continuation after an
+ * externally-executed tool call — is a fresh streamed call over that history
+ * (message-state replay; the loop cannot be suspended). Output is emitted as it
+ * happens: `stream_delta` per token (unless includePartialMessages is false) and
+ * assistant/tool messages per step. Emits the same seq-numbered SessionEvent log
+ * as SessionRunner; engine-specific CLI telemetry (system_init, capabilities,
+ * rate_limit, ...) is simply never emitted.
+ */
+declare class AiSdkRunner implements Runner {
+  #private;
+  readonly id: string;
+  readonly createdAt: number;
+  constructor(config: AiSdkRunnerConfig, id?: string);
+  get status(): SessionStatus;
+  get lastSeq(): number;
+  /** The session's durable state — persist to park, replay to rehydrate. */
+  get messages(): ModelMessage[];
+  /** External tool calls the loop is currently parked on. */
+  get pendingToolCalls(): PendingToolCall[];
+  get pendingApprovals(): PermissionRequest[];
+  /** The session's scratch filesystem (see Runner.vfs) — the server's file
+   * routes serve deliverables straight from it. */
+  get vfs(): SandboxVfs | undefined;
+  info(): SessionInfo;
+  start(): Promise<void>;
+  /**
+   * Snapshot durable state, release engine resources, and go inert — the session
+   * continues in the snapshot, not in this object. Returns undefined when parking
+   * would lose work or has nothing to wait for: a turn in flight, no parked call,
+   * or an already-closed/parked runner.
+   */
+  park(): RunnerSnapshot | undefined;
+  sendMessage(text: string): void;
+  /**
+   * Deliver the result of an external (execute-less) tool call. Appends the
+   * tool-result message and, once no calls remain pending, re-enters the loop.
+   * Idempotent per toolCallId: unknown/already-settled ids return false.
+   */
+  resolveToolCall(toolCallId: string, output: ToolCallOutput, options?: {
+    isError?: boolean;
+  }): boolean;
+  resolvePermission(_requestId: string, _decision: PermissionDecision): boolean;
+  /** Emit `file_delivered` — the deliver_file tool's hand-over event (wired by
+   * createEngineSession via ToolContextOptions.onFileDelivered). */
+  emitFileDelivered(file: {
+    path: string;
+    bytes: number;
+    description?: string;
+  }): void;
+  /**
+   * One plain generateText over the session's current model, billed into the
+   * running turn's usage accumulator — the web_fetch digest pass uses this so
+   * its tokens are never lost from the turn's accounting.
+   */
+  generateDigest(prompt: string): Promise<string>;
+  interrupt(): Promise<void>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  setModel(model?: string): Promise<void>;
+  fail(message: string): void;
+  close(reason?: 'client' | 'server' | 'error'): void;
+  subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+  /**
+   * Deliver the result of an execution this runner dispatched. Used by the host
+   * when a backend settled out-of-band (a browser bridge answering later, a
+   * deferred executor). Idempotent by executionId.
+   */
+  settleExecution(executionId: string, result: ToolExecutionResult): boolean;
+}
+//#endregion
+//#region src/claude-auth.d.ts
+/**
+ * Credential presence for one Claude Code environment, as the CLI itself reports
+ * it. 'unknown' means the check could not run at all (no binary, a CLI too old
+ * for `auth status`, unparseable output) — which is NOT evidence of a missing
+ * login and must never be surfaced as one.
+ */
+type ClaudeAuthStatus = 'logged_in' | 'logged_out' | 'unknown';
+/** Injectable form of {@link checkClaudeAuth} (tests, custom probes). */
+type ClaudeAuthProbe = (env: Record<string, string | undefined>) => Promise<ClaudeAuthStatus>;
+/**
+ * The native Claude Code binary the Agent SDK itself spawns, resolved the way
+ * the SDK resolves it: the platform-specific optional dependency installed next
+ * to the SDK package (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude`).
+ * Probing this binary rather than whatever `claude` is on PATH means an auth
+ * check answers for the executable sessions will actually run — the two can be
+ * different versions logged into different places. Returns undefined when it
+ * can't be found (optional dep skipped, unsupported platform); callers degrade
+ * to 'unknown', and the SDK surfaces its own error if a session is created.
+ */
+declare function resolveBundledClaudeExecutable(): string | undefined;
+/**
+ * Ask the CLI whether `env` holds usable credentials: `claude auth status`
+ * prints a JSON verdict covering every source the CLI itself consults for that
+ * environment — `<CLAUDE_CONFIG_DIR>/.credentials.json`, the macOS login
+ * Keychain, ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, Bedrock/Vertex
+ * (verified against 2.1.217). Only the `loggedIn` boolean is ever read; the
+ * identity fields in the payload (email, org, subscription) never leave the
+ * parse. The exit code is deliberately ignored — 2.1.217 exits 1 on a
+ * logged-out verdict where other versions exit 0 — and anything that doesn't
+ * parse to a `loggedIn` boolean is 'unknown', because `auth status` is not a
+ * stable contract. Never rejects.
+ */
+declare function checkClaudeAuth(env: Record<string, string | undefined>, options?: {
+  executable?: string;
+  timeoutMs?: number;
+}): Promise<ClaudeAuthStatus>;
+//#endregion
+//#region src/quickjs-executor.d.ts
+/** Resolve a URL to text for the guest. Runs host-side with host authority —
+ * this is where a credential may be attached, never inside the sandbox. */
+type HostFetch = (url: string, signal: AbortSignal) => Promise<string>;
+type QuickJsExecutorOptions = {
+  engine: SandboxEngine;
+  /**
+   * Hostnames the guest may reach, exact or `*.example.com`. Empty/unset =
+   * no network at all (the guest's fetchText throws). Matched host-side; the
+   * guest is never told the allowlist and never holds a credential.
+   */
+  allowedHosts?: string[]; /** Performs the actual request. Unset = global fetch, text body. */
+  hostFetch?: HostFetch;
+  /** Per-fetch cap. The guest deadline does NOT cover host-function time, so
+   * every capability needs its own bound. Default 10000. */
+  fetchTimeoutMs?: number; /** Default guest wall-clock limit when the call doesn't set one. Default 5000. */
+  defaultTimeoutMs?: number; /** Default guest allocator cap when the call doesn't set one. Default 64 MiB. */
+  defaultMemoryLimitBytes?: number;
+};
+/**
+ * In-process execution backend: runs a tool's untrusted script in the QuickJS
+ * WASM guest. Always settles inline — nothing downstream assumes that, which is
+ * what lets a deferred backend replace it behind the same seam.
+ */
+declare class QuickJsExecutor implements ToolExecutor {
+  #private;
+  constructor(options: QuickJsExecutorOptions);
+  dispatch(call: ToolExecutionCall): Promise<ToolExecutionDispatch>;
+}
+/** Exact hostname match, or a single leading `*.` wildcard covering subdomains
+ * (not the bare parent). Only http(s) — no file:, data:, or other schemes. */
+declare function isHostAllowed(url: string, allowedHosts: string[]): boolean;
+//#endregion
+//#region src/pending-registry.d.ts
+/**
+ * One registry for every request that leaves the runner and must come back:
+ * permission approvals, browser-bridged tool calls, and deferred executions.
+ * They differ only in who answers and how long that takes — the correlation,
+ * timeout, idempotent settle, and provenance tagging are identical, so they
+ * live here once.
+ */
+/** What kind of async request this is. Purely descriptive — the mechanics are shared. */
+type PendingKind = 'approval' | 'tool_call' | 'execution';
+/** Who settled a request. Mirrors the existing approval vocabulary. */
+type SettledBy = 'client' | 'timeout' | 'policy' | 'server';
+type PendingOutcome<T> = {
+  ok: true;
+  value: T;
+  settledBy: SettledBy;
+} | {
+  ok: false;
+  reason: string;
+  error: string;
+  settledBy: SettledBy;
+};
+type PendingEntry = {
+  id: string;
+  kind: PendingKind;
+  createdAt: number; /** Epoch ms the timeout policy fires at, when one was set. */
+  expiresAt?: number; /** Caller-supplied descriptor for display/rehydration (tool name, request, ...). */
+  meta?: Record<string, unknown>;
+};
+type RegisterOptions<T> = {
+  id: string;
+  kind: PendingKind;
+  /** Fail the request automatically after this long. Omit for no deadline
+   * (deferred executions whose watchdog lives elsewhere). */
+  timeoutMs?: number;
+  meta?: Record<string, unknown>; /** Called when the entry settles, however it settled. For emitting events. */
+  onSettle?: (outcome: PendingOutcome<T>, entry: PendingEntry) => void;
+};
+declare class PendingRequestRegistry {
+  #private;
+  get size(): number;
+  /**
+   * Register a request and get a promise for its outcome. The promise **never
+   * rejects**: a timeout or cancellation resolves with `ok: false` so callers
+   * feed the failure back into the agent loop instead of unwinding it.
+   *
+   * Re-registering a live id throws — silently replacing it would strand the
+   * first waiter forever.
+   */
+  register<T>(options: RegisterOptions<T>): Promise<PendingOutcome<T>>;
+  /** Deliver a result. Returns false for unknown or already-settled ids —
+   * duplicate and late deliveries are no-ops, never a second application. */
+  settle<T>(id: string, value: T, settledBy?: SettledBy): boolean;
+  /** Fail a request. Same idempotence guarantee as {@link settle}. */
+  fail(id: string, reason: string, error: string, settledBy?: SettledBy): boolean;
+  has(id: string): boolean;
+  get(id: string): PendingEntry | undefined;
+  list(kind?: PendingKind): PendingEntry[];
+  /** Fail everything (optionally of one kind) — session close, turn interrupt. */
+  cancelAll(reason: string, error: string, kind?: PendingKind): number;
+}
+//#endregion
+//#region src/browser-bridge-executor.d.ts
+/** Answer a bridged call, as delivered by the client over the wire. */
+type BridgeAnswer = {
+  output: ToolExecutionOutput;
+  logs?: string[];
+} | {
+  reason: string;
+  error: string;
+  logs?: string[];
+};
+type BrowserBridgeExecutorOptions = {
+  /**
+   * Put a `tool_call_request` on the wire to the attached client. Returning
+   * false means nobody is attached — the execution fails immediately rather
+   * than hanging until its deadline.
+   */
+  send: (frame: ToolCallRequestFrame) => boolean; /** Tell the client to abandon a call the server gave up on. */
+  cancel?: (executionId: string, reason: string) => void; /** How long to wait for the client before failing the execution. Default 60000. */
+  timeoutMs?: number;
+  /**
+   * Called once per dispatched execution when it reaches a terminal result,
+   * however it got there (client answer, timeout, abort, no client). This is
+   * the wire back into the agent loop — the host feeds it to the runner's
+   * `resolveToolCall`. A timeout arrives here as a failed result, not silence.
+   */
+  onResult?: (executionId: string, result: ToolExecutionResult) => void;
+  /** Share the session's registry so approvals, bridged calls, and deferred
+   * executions live in one table. Omit to get a private one. */
+  registry?: PendingRequestRegistry;
+};
+/**
+ * Executes tool calls in the attached client's own sandbox. The first backend
+ * that genuinely returns `pending`: dispatch puts a request on the wire and
+ * returns, and the result arrives later through {@link resolve}.
+ *
+ * Data locality is the point — documents can stay in the browser and never
+ * reach the server. The tradeoff is trust: whatever comes back is untrusted
+ * input, fine for the user's own data but never a source for authoritative
+ * server state (that is why MCP and secret-bearing tools are never bridged).
+ */
+declare class BrowserBridgeExecutor implements ToolExecutor {
+  #private;
+  readonly registry: PendingRequestRegistry;
+  constructor(options: BrowserBridgeExecutorOptions);
+  dispatch(call: ToolExecutionCall): Promise<ToolExecutionDispatch>;
+  /**
+   * Apply a client's answer. Returns false when the id is unknown or already
+   * settled — a late result after a timeout must not re-open a settled call.
+   */
+  resolve(executionId: string, answer: BridgeAnswer): boolean;
+}
+/** Map a registry outcome onto the executor's result contract. */
+declare function toExecutionResult(outcome: PendingOutcome<BridgeAnswer>): ToolExecutionResult;
+//#endregion
+//#region src/deferred-executor.d.ts
+/** A dispatched execution, as handed to the backend that will run it. */
+type DeferredDispatch = {
+  /** Correlation id. The result is delivered under it — `POST
+   * {basePath}/executions/:executionId/result` — and applied idempotently. */
+  executionId: string;
+  sessionId: string;
+  tool: string;
+  input: unknown; /** The session's scratch filesystem at dispatch time, by value. */
+  vfsSeed?: Record<string, string>;
+  limits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  }; /** Epoch ms the host's execution watchdog fires at, when a timeout was configured. */
+  expiresAt?: number;
+};
+type DeferredExecutorOptions = {
+  /**
+   * Hand the call to whatever actually runs it — enqueue it, POST it to a worker,
+   * page a human. Called synchronously during dispatch; throwing fails the
+   * execution (the failure reaches the agent as ordinary tool output).
+   */
+  onDispatch: (call: DeferredDispatch) => void | Promise<void>;
+  /** How long the result may take before the host's watchdog fails the execution.
+   * Unset = no deadline; the execution then relies on the job's parked cap. */
+  timeoutMs?: number; /** Reported on `execution_dispatched`. Default 'remote'. */
+  backend?: ToolExecutionBackend;
+};
+/**
+ * The executor for work that outlives the session's process residency: dispatch
+ * hands the call off and returns `pending` **without holding a promise**, because
+ * the runner it would resolve into is about to be torn down. The result can only
+ * come back through the host — the execution-result route → `settleExecution` on a
+ * rehydrated runner — which is exactly what makes a park durable rather than a
+ * long in-memory await.
+ *
+ * Contrast {@link BrowserBridgeExecutor}, which is also `pending` but keeps its
+ * answer in memory for the ~60s the tab has to reply.
+ */
+declare class DeferredExecutor implements ToolExecutor {
+  #private;
+  readonly backend: ToolExecutionBackend;
+  readonly timeoutMs: number | undefined;
+  constructor(options: DeferredExecutorOptions);
+  /** Every call this executor takes is deferred — route only the tools that
+   * belong on the remote side to it. */
+  describe(): ToolExecutionProfile;
+  dispatch(call: ToolExecutionCall): Promise<ToolExecutionDispatch>;
+}
+//#endregion
+//#region src/web-fetch.d.ts
+/**
+ * `web_fetch` backend, close to Claude Code's original WebFetch: fetch a URL,
+ * convert HTML to markdown, and (optionally) digest it with a model against the
+ * caller's prompt. Server-side only — this runs with server egress, which is
+ * exactly why it is an authoritative capability the operator grants explicitly.
+ */
+type WebFetchResult = {
+  /** The URL that was fetched (after same-host redirects). */url: string; /** Model digest of the page against the prompt (when a digest fn is wired). */
+  digest?: string; /** Page content as markdown (when no digest fn is wired, or digesting failed). */
+  markdown?: string; /** True when the markdown was cut at the size cap. */
+  truncated?: boolean;
+  /** Redirect-to-a-different-host notice: the redirect is surfaced, not followed
+   * (the agent can decide to fetch `redirectUrl` itself). */
+  notice?: string;
+  redirectUrl?: string;
+  error?: string;
+};
+type WebFetchFn = (url: string, prompt: string) => Promise<WebFetchResult>;
+/** Runs the digest pass over the fetched markdown. Wire the session's own model
+ * here (see createEngineSession) so its tokens land in the turn's usage. */
+type WebFetchDigest = (markdown: string, prompt: string) => Promise<string>;
+type WebFetchOptions = {
+  fetchImpl?: typeof fetch; /** Raw-body cap, enforced while streaming (before any conversion). Default 1 MiB. */
+  maxContentBytes?: number; /** Markdown cap handed to the model. Default 50 KB. */
+  maxMarkdownBytes?: number;
+  /** Fetched-page cache TTL (keyed by URL; the digest is per-prompt and never
+   * cached). Default 15 minutes. */
+  cacheTtlMs?: number;
+  /** Optional hostname allowlist on top of the SSRF guard (exact or `*.example.com`).
+   * Unset = any public host. */
+  allowedHosts?: string[]; /** Per-request timeout. Default 30000. */
+  timeoutMs?: number;
+  digest?: WebFetchDigest;
+};
+declare function createWebFetch(options?: WebFetchOptions): WebFetchFn;
+/** Private / loopback / link-local / unspecified, IPv4 and IPv6 (incl. v4-mapped). */
+declare function isPrivateAddress(address: string): boolean;
+/**
+ * Dependency-free HTML → markdown, tuned for "give the model readable text":
+ * drops non-content subtrees, keeps headings/lists/links/emphasis/code, strips
+ * everything else. Not a spec-grade converter on purpose — a small predictable
+ * transform beats dragging a DOM into core.
+ */
+declare function htmlToMarkdown(html: string): string;
+//#endregion
+//#region src/tools.d.ts
+/**
+ * How much authority a tool carries, which decides where it may run.
+ *
+ * - `sandboxed` — no ambient authority; safe to execute anywhere, including an
+ *   untrusted browser tab. Its results are untrusted input.
+ * - `authoritative` — runs server-side with server credentials (MCP, secret-bearing
+ *   APIs). **Never bridged to a client**: bridging it would hand a browser the
+ *   ability to forge authoritative results.
+ */
+type ToolTrust = 'sandboxed' | 'authoritative';
+type ToolDefinition = {
+  name: string;
+  trust: ToolTrust;
+  /** The AI SDK tool. Sandboxed tools are declared WITHOUT `execute` so the loop
+   * hands them to the ToolExecutor seam rather than running them inline. */
+  tool: Tool;
+};
+type ToolContextOptions = {
+  /** Executor for sandboxed tools. Selected per call by the host (browser bridge
+   * when a client is attached, server QuickJS otherwise). */
+  executor: ToolExecutor;
+  sessionId: string; /** Scratch filesystem shared by this session's sandboxed tools. */
+  vfs?: SandboxVfs; /** Search backend. Omitted = `web_search` is not granted at all. */
+  search?: (query: string, limit: number) => Promise<Array<{
+    title: string;
+    url: string;
+    snippet?: string;
+  }>>; /** Document fetcher for `download`. Omitted = the tool is not granted. */
+  download?: (url: string) => Promise<{
+    contentType?: string;
+    text: string;
+  }>;
+  /** Page digester for `web_fetch` (see {@link createWebFetch}). Omitted = the
+   * tool is not granted. */
+  webFetch?: WebFetchFn;
+  /** Notified when the agent hands over a VFS file via `deliver_file`, so the
+   * host can emit the `file_delivered` session event. The tool is only granted
+   * when this is set — a delivery nobody hears is not a delivery. */
+  onFileDelivered?: (file: {
+    path: string;
+    bytes: number;
+    description?: string;
+  }) => void; /** Per-call sandbox limits. */
+  limits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  };
+  /** Notified when a sandboxed execution is dispatched and when it settles, so
+   * the host can emit execution_* events. */
+  onDispatch?: (executionId: string, toolName: string) => void;
+  onSettle?: (executionId: string, result: ToolExecutionResult) => void;
+};
+/** Everything a session's tools need, plus the tool set to hand the runner. */
+type ToolContext = {
+  vfs: SandboxVfs;
+  tools: ToolSet;
+  definitions: ToolDefinition[]; /** Names the loop must not execute inline (they go through the executor). */
+  sandboxedToolNames: string[];
+};
+/**
+ * Build the capability-scoped tool set for a session.
+ *
+ * The agent's authority is exactly what is granted here — there are no built-in
+ * filesystem or shell tools, and nothing reaches the host filesystem: `fs_*`
+ * operate on an in-memory scratch VFS. Tools whose backend is not supplied are
+ * simply absent rather than present-and-failing, so a model cannot be tempted
+ * by a capability the operator did not grant.
+ */
+declare function createToolContext(options: ToolContextOptions): ToolContext;
+/** Add host-side MCP tools to a context. They are ALWAYS authoritative: they run
+ * server-side with server credentials, and must never be handed to a browser. */
+declare function withMcpTools(context: ToolContext, mcpTools: ToolSet): ToolContext;
+//#endregion
+//#region src/engine.d.ts
+type EngineSessionOptions = {
+  /** Resolved session config (profile defaults already applied). */config: AiSdkRunnerConfig; /** The profile that selected this engine, when there was one. */
+  profile?: ProfileInfo;
+  /**
+   * Resolve the profile's provider config into a model instance. The host owns
+   * this so core never imports a provider SDK and never reads credentials —
+   * they come from the operator's environment, exactly like the Claude chain.
+   */
+  resolveModel: (profile: ProfileInfo | undefined, config: AiSdkRunnerConfig) => LanguageModel;
+  /**
+   * Executor for sandboxed tools. Return the browser bridge when a client is
+   * attached and the server sandbox otherwise; the seam makes them
+   * interchangeable, so this is the only place the choice is made.
+   */
+  selectExecutor: () => ToolExecutor; /** Which backend `selectExecutor` returned, for the execution_* events. */
+  backend?: 'server' | 'browser' | 'managed' | 'remote'; /** Backends for the granted capabilities. Omitted ones are simply not granted. */
+  capabilities?: {
+    search?: ToolContextOptions['search'];
+    download?: ToolContextOptions['download'];
+    /**
+     * Grants `web_fetch`. Pass options (or `{}`) to use the built-in
+     * {@link createWebFetch} backend — its digest pass then runs on the
+     * session's own model, billed into the turn's usage. Pass `digest: false`
+     * to skip the digest (the tool returns page markdown), a custom digest fn
+     * to bring your own model, or a complete {@link WebFetchFn} to replace the
+     * backend outright.
+     */
+    webFetch?: WebFetchFn | (Omit<WebFetchOptions, 'digest'> & {
+      digest?: WebFetchOptions['digest'] | false;
+    });
+    /** Grants `deliver_file`: the agent can hand VFS files over to the user
+     * (emitting `file_delivered`, downloadable via the server's file routes).
+     * Default true — set false to withhold it. */
+    deliverFiles?: boolean;
+  };
+  /** Authoritative tools that run server-side with server credentials (MCP).
+   * Never bridged to a client. Namespaced `<server>__<tool>` by
+   * {@link connectMcpTools}, which is how a profile grants servers by name. */
+  mcpTools?: ToolSet;
+  /** Extra instructions prepended to the session's system prompt. Overridden by
+   * the profile's `session.instructions` when it declares one. */
+  instructions?: string;
+  executionLimits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  };
+};
+/**
+ * Assemble a model-agnostic session: provider model, capability-scoped tools,
+ * a scratch VFS, and the executor that runs the sandboxed ones.
+ *
+ * This is the piece an operator wires into the server's `createEngineRunner`.
+ *
+ * The host wires the *backends*; the profile and the session request decide which
+ * of them are actually granted (`profile.session`, `config.capabilities`). A
+ * backend that isn't granted is simply not built into the tool set, so withholding
+ * a capability costs the host no branching. No declaration anywhere = everything
+ * the host wired, which is what a host that ignores profiles gets.
+ */
+declare function createEngineSession(options: EngineSessionOptions): AiSdkRunner;
+type McpConnection = {
+  tools: ToolSet;
+  close: () => Promise<void>;
+};
+/**
+ * Connect to MCP servers and return their tools, ready for {@link withMcpTools}.
+ *
+ * Server-side only, with server credentials: these tools are authoritative and
+ * must never be bridged to a browser. `@ai-sdk/mcp` is imported lazily and is an
+ * optional dependency — an operator who wires no MCP servers never needs it.
+ */
+declare function connectMcpTools(servers: Record<string, McpServerConfigWire>,
+/** `onError` may fire more than once for a single server: transport-level
+ * failures surface through the client's own uncaught-error channel as well as
+ * the connect failure. Treat it as a report, not a count. */
+
+options?: {
+  onError?: (name: string, error: unknown) => void;
+}): Promise<McpConnection>;
+//#endregion
+//#region src/input-queue.d.ts
+/**
+ * Push-based single-consumer AsyncIterable bridging imperative sendMessage() calls
+ * into the streaming `prompt` the Agent SDK consumes.
+ */
+declare class InputQueue implements AsyncIterable<SDKUserMessage> {
+  #private;
+  push(message: SDKUserMessage): void;
+  end(): void;
+  [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage>;
+}
+//#endregion
+//#region src/normalize.d.ts
+declare function toApiMessage(message: unknown): ApiMessage;
+/**
+ * Map one SDKMessage to a wire-protocol event body, or null for messages the runner
+ * consumes itself (system_init and session-state changes carry runner state and are
+ * emitted by the runner with extra context).
+ */
+declare function normalizeSdkMessage(msg: SDKMessage): SessionEventBody | null;
+//#endregion
+export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, type ClaudeAuthProbe, type ClaudeAuthStatus, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineSessionOptions, type HistoryFn, type HostFetch, InputQueue, type McpConnection, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, checkClaudeAuth, connectMcpTools, createEngineSession, createToolContext, createWebFetch, htmlToMarkdown, isHostAllowed, isPrivateAddress, normalizeSdkMessage, resolveBundledClaudeExecutable, toApiMessage, toExecutionResult, withMcpTools };
+//# sourceMappingURL=index.d.mts.map