@workerdeck/core 0.22.0 → 1.0.0

package/build/index.d.mts

@@ -5,50 +5,17 @@ import { SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 import { Readable, Writable } from "node:stream";
 
 //#region src/lib/attachments.d.ts
-/**
- * An attachment plus its bytes — what the host hands a runner at send time.
- *
- * The split matters: `data` goes into the message the engine sends and nowhere
- * else. What the runner emits into the seq-numbered event log is the
- * {@link MessageAttachment} half, so replay and parking stay cheap (see the
- * protocol's note on why the bytes are not on the wire).
- */
 type AttachmentInput = MessageAttachment & {
-  /** Base64, no data-URL prefix. */data: string;
+  data: string;
 };
-/**
- * How an attachment reaches the model. Not every file can be handed to a model
- * as itself: images and PDFs have native block types, anything textual can be
- * inlined, and the rest has no representation at all — so uploads of it are
- * refused at the door rather than silently dropped from the message.
- */
 type AttachmentKind = 'image' | 'document' | 'text';
-/** Strips any `; charset=…` parameter and lowercases. */
 declare function normalizeMediaType(mediaType: string): string;
-/** How this media type can be sent, or null if it can't be. */
 declare function attachmentKind(mediaType: string): AttachmentKind | null;
-/** Human-readable list for the 415 an unsupported upload gets. */
 declare const SUPPORTED_ATTACHMENT_TYPES: string;
-/**
- * Anthropic content blocks for a set of attachments, in the given order.
- *
- * Blocks lead the message and the user's text follows: the model reads the
- * picture, then the instruction about it. Text files are inlined in a named
- * envelope rather than as a bare block, so "here is my config" doesn't read as
- * something the user typed.
- *
- * Structurally typed — `packages/core` models Anthropic content the way
- * `packages/protocol` does, and the caller casts into the SDK's own param type.
- */
 declare function attachmentContentBlocks(attachments: readonly AttachmentInput[]): Array<Record<string, unknown>>;
-/** Strip the bytes: the log-safe half of an attachment. */
 declare function attachmentRef(attachment: AttachmentInput): MessageAttachment;
 //#endregion
 //#region src/executors/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;
@@ -60,10 +27,10 @@ type ToolExecutionResult = {
   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. */
+  executionId: string;
+  sessionId: string;
+  tool: string;
+  input: unknown;
   vfs?: SandboxVfs;
   limits?: {
     timeoutMs?: number;
@@ -71,11 +38,6 @@ type ToolExecutionCall = {
   };
   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';
@@ -84,70 +46,31 @@ type ToolExecutionDispatch = {
   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`.
-   */
+  backend?: ToolExecutionBackend;
   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. */
+  toolName: string;
   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. */
+  engine: ProfileEngine;
   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. */
+  seq: number;
+  events: SessionEvent[];
+  vfs?: Record<string, string>;
+  parked: ParkedExecution[];
   state: unknown;
 };
 type PermissionDecision = {
@@ -158,156 +81,36 @@ type PermissionDecision = {
   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.
-   *
-   * `coalesceReplay` drops state readings superseded later in the same replay —
-   * the fifty stale context/rate-limit polls a long session accumulates, which
-   * a client otherwise applies one by one and *renders*, counting its usage
-   * meters up through the session's history on every attach. Opt-in, and the
-   * default must stay off: it is only sound for a consumer whose handling of
-   * those events is last-write-wins, and `parking.ts` — which subscribes from
-   * seq 0 — branches on `status_changed` instead. Live events are never
-   * affected; this touches the buffered replay alone.
-   *
-   * `truncateResults` delivers an oversized `tool_result` block as its head plus
-   * the markers that say so (protocol's {@link TOOL_RESULT_HEAD_CHARS}), leaving
-   * the whole thing one fetch away. Measured, that is 68% of a long session's
-   * attach in three frames. Opt-in for the same reason and with one extra
-   * condition: **the opt-in must be issued by the unit that renders**, because
-   * `client` and `react` are separate packages an embedder can skew, and a
-   * client that asked for heads without knowing how to fetch the rest would show
-   * one as though it were the whole result. Live events are untouched — a result
-   * arriving while you watch is already on screen — and so is the stored log,
-   * which parking snapshots and the fetch route both read.
-   *
-   * `imageRefs` replaces a `tool_result`'s base64 image parts with `image_ref`
-   * addresses (protocol's {@link ImageRefPart}), their bytes one REST fetch
-   * away. Opt-in under the same rule — issued by the unit that renders — but
-   * unlike the other two it applies to **live events as well as the replay**,
-   * because the client's one render path is ref-then-fetch and bytes on a live
-   * event would only be discarded or pinned. Measured, this is 91% of all
-   * tool-result payload and 0% of what any client draws. The stored log keeps
-   * every byte, which is what the fetch route serves back. */
   subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
     coalesceReplay?: boolean;
     truncateResults?: boolean;
     imageRefs?: boolean;
   }): () => void;
-  /** One buffered event by seq, or undefined — the read side of the log the
-   * replay already walks.
-   *
-   * Optional, like every member added after `Runner` became public API: an
-   * out-of-tree runner that declines it declines only the on-demand tool result
-   * with it (the route 404s), which is exactly the degradation a runner with no
-   * `truncateResults` support wants anyway.
-   *
-   * Deliberately **not** a "give me the whole log" accessor. The one caller
-   * needs a single event by a seq a client is holding, and a method that handed
-   * out the array would invite a second copy of the bytes this feature exists
-   * to stop shipping. */
   eventAt?(seq: number): SessionEvent | undefined;
-  /** Queue a user message for the session (starts the next turn when idle).
-   * `attachments` carry their bytes to the engine and their reference to the
-   * event log (see {@link AttachmentInput}). */
   sendMessage(text: string, attachments?: readonly AttachmentInput[]): void;
-  /** Live MCP server status. Resolves undefined when the engine cannot answer
-   * (no MCP surface, or a fake query in tests); omitted entirely by engines that
-   * have no MCP at all. */
   mcpServers?(): Promise<McpServerStatusInfo[] | undefined>;
-  /** Reconnect one MCP server by name. Throws if it fails. */
   reconnectMcpServer?(name: string): Promise<void>;
-  /** Enable or disable one MCP server by name. Throws if it fails. */
   setMcpServerEnabled?(name: string, enabled: boolean): Promise<void>;
-  /** Set (or clear, with undefined) the host's display title — `meta.title`, which
-   * `info().title` prefers over the derived one. A host-facing edit only: nothing
-   * is sent to the engine. */
   setTitle(title: string | undefined): 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>;
-  /**
-   * Reset the conversation in place: the session keeps its id, its watermarks
-   * and its place in the list, and the engine starts over with an empty
-   * context. Announced with a `conversation_reset` event, whose replay rules
-   * (see `transcriptContent` in `@workerdeck/protocol`) are what stop an
-   * attaching client from resurrecting the cleared rows.
-   *
-   * Optional, like every member added after `Runner` became public API: an
-   * out-of-tree runner that declines it declines the `clear_context` command
-   * with it, which is exactly what `EngineCapabilities.clearContext: false`
-   * tells clients to expect.
-   *
-   * **Queues behind in-flight work rather than racing it** — resolving when the
-   * clear has actually happened, not when it was accepted. A clear that landed
-   * in the middle of the turn it was clearing would be neither, and the engines
-   * differ in how they wait (claude hands `/clear` to a CLI that queues its own
-   * streamed input; codex and the provider put it on their turn chain), so the
-   * one thing callers may rely on is the resolution, not the mechanism.
-   */
   clearContext?(): 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;
-  /**
-   * The same snapshot, taken **without ending anything** — the runner stays live,
-   * attached and warm.
-   *
-   * Park and snapshot are two operations that happen to produce the same value,
-   * and separating them is what makes restart-survival possible for an engine
-   * that has no on-disk session of its own. A park is for a session with nothing
-   * to do for possibly days; this is for one whose user is mid-conversation and
-   * whose process might be redeployed out from under it. The host writes it
-   * through after each turn — never on a shutdown hook, because a `kill -9` runs
-   * no hook and that is precisely the case worth surviving — and rebuilds from
-   * the last write through the ordinary `restore` path.
-   *
-   * Returns undefined when a snapshot would capture a half-happened turn: one in
-   * flight, or pending in-process executions whose results die with the process.
-   * Optional for the same reason `park()` is — claude and codex run behind a
-   * binary that owns its process state, and have engine-side resume instead.
-   */
   snapshot?(): 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/lib/subscribers.d.ts
-/** What a subscriber asked for. Absent fields mean the untransformed stream. */
 type SubscribeOptions = {
   coalesceReplay?: boolean;
   truncateResults?: boolean;
@@ -326,25 +129,15 @@ type SessionInfoFn = (sdkSessionId: string, options: {
   dir?: string;
 }) => Promise<SDKSessionInfo | undefined>;
 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. */
+  queryFn?: QueryFn;
   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. */
+  pathToClaudeCodeExecutable?: string;
+  extraOptions?: Partial<Options>;
   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. */
+  backfillHistory?: boolean;
   historyFn?: HistoryFn;
-  /** Injectable session-metadata reader (tests). Defaults to the SDK's
-   * getSessionInfo — the only place the CLI's own session title is readable
-   * from, since no message on the stream carries it. */
   sessionInfoFn?: SessionInfoFn;
 };
-/**
- * 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;
@@ -353,116 +146,27 @@ declare class SessionRunner implements Runner {
   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;
-  /** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
-   * it (undefined) restores the derived title. The engine is never told. */
   setTitle(title: string | undefined): void;
-  /** 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).
-   *
-   * `attachments` carry their own bytes; they reach the CLI as content blocks and
-   * are logged as references. A message may be attachments alone — an empty text
-   * block is not valid API input, so the text is only added when there is some. */
   sendMessage(text: string, attachments?: readonly AttachmentInput[]): void;
-  /** Live MCP server status, straight from the CLI. Undefined when the engine
-   * can't answer (an injected fake query in tests) — the caller 501s rather than
-   * pretending the session has no servers. */
   mcpServers(): Promise<McpServerStatusInfo[] | undefined>;
   reconnectMcpServer(name: string): Promise<void>;
   setMcpServerEnabled(name: string, enabled: boolean): Promise<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>;
-  /**
-   * Reset the conversation by sending the `/clear` the CLI already honors.
-   *
-   * Deliberately not a second mechanism: this engine's reset arrives *from the
-   * SDK*, and `normalizeSdkMessage` turns the CLI's report of it into the
-   * `conversation_reset` event (adopting the new conversation id and re-polling
-   * context usage on the way through). Reimplementing the clear here would give
-   * one engine two ways to reach the same state, and only one of them would get
-   * the id adoption right. So the command and the composer's `/clear` are one
-   * behaviour, and this method is the thin end of it.
-   *
-   * The one place it differs from the other two engines: this resolves when the
-   * `/clear` has been **handed to the CLI**, not when the reset has happened —
-   * the CLI queues its own streamed input, so waiting is its job, and there is
-   * no chain here to ride. The observable contract is the same (a clear sent
-   * mid-turn queues rather than cutting the turn short); only the moment the
-   * promise settles is weaker, and no caller depends on it.
-   */
   clearContext(): 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;
-  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
-   * "show everything" on one row, so a per-runner seq index would be a map
-   * maintained on every emit to save a walk nobody makes twice a minute. */
   eventAt(seq: number): SessionEvent | undefined;
-  /**
-   * Replay buffered events with seq > afterSeq, then deliver live events.
-   * Returns an unsubscribe function.
-   *
-   * Replay honours the reset watermark: transcript content below the latest
-   * `conversation_reset` is skipped (the reducer would clear it again anyway,
-   * and a pre-reset client that never learned the reducer's case would render
-   * a conversation the engine has discarded), while state-bearing events —
-   * which are emitted once and never again — always replay. The reset event
-   * itself replays (the skip is strictly-below), which is what clears a
-   * reconnecting client still holding pre-reset rows; superseded resets are
-   * content below the newer one and are skipped with what they cleared.
-   */
   subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => void;
 }
 //#endregion
 //#region src/lib/replay.d.ts
-/**
- * The one replay body, and what a socket receives from it.
- *
- * Every runner had a byte-identical copy of this loop — three spellings of four
- * rules, one of which ("never drop the highest-seq event, whatever the rule
- * says") is load-bearing and was three copies of a comment. Not a base class:
- * the runners share nothing else, and a base class would have to own `#emit`,
- * the most engine-specific method each of them has.
- *
- * The rules, in the order they are applied:
- *
- * 1. `afterSeq` — the caller already holds everything at or below it.
- * 2. `resetSeq` — transcript *content* strictly below the latest
- *    `conversation_reset` is skipped, so a re-attach cannot resurrect a cleared
- *    conversation while state events still replay. **Every engine that can emit
- *    a reset must track it and pass it** — this was Claude's alone only for as
- *    long as Claude's was the only engine that could produce the event, and the
- *    failure when a runner forgets is quiet: the end state is right for a
- *    current reducer, so nothing looks broken while every attach re-sends the
- *    whole cleared conversation for the process's lifetime.
- * 3. `coalesceReplay` — last-write-wins state readings superseded later in the
- *    same replay (`staleReplaySeqs`), plus everything `replayRetains` says the
- *    reducer reads and discards. Opt-in, and only sound for a consumer whose
- *    handling of those events is last-write-wins.
- * 4. `imageRefs` — a base64 image part is delivered as an `image_ref` address
- *    (protocol's {@link imagePartRef}), its bytes one REST fetch away. Applied
- *    **before** rule 5, because it stamps indices from the stored part array
- *    which rule 5 then reshapes. Unlike rule 5 this also applies to the live
- *    path (see `SubscriberSet`), which is the one place these two rules differ.
- * 5. `truncateResults` — a huge `tool_result` block is delivered as its head
- *    plus the markers that say so. **Never mutates the stored event**: the live
- *    path, the parking snapshot and the fetch route all need the whole thing,
- *    so this builds a copy and the log stays the log.
- *
- * The highest-seq event is delivered whatever rules 2 and 3 say — a client's
- * replay hold waits for `state.lastSeq` to reach the attach's and would
- * otherwise hang forever — but it is still *truncated* when rule 4 applies. A
- * session that ends on a `find /` puts its 641 KB frame exactly there.
- */
 declare function replaySlice(events: readonly SessionEvent[], options: {
   afterSeq: number;
   resetSeq?: number;
@@ -470,88 +174,43 @@ declare function replaySlice(events: readonly SessionEvent[], options: {
   truncateResults?: boolean;
   imageRefs?: boolean;
 }): SessionEvent[];
-/**
- * A copy of `event` whose oversized `tool_result` blocks carry their head and
- * say so — or `event` itself, unchanged and un-copied, when nothing is over the
- * budget. That identity matters: an attach is mostly small events, and a fresh
- * object for every one of them would cost more than the feature saves.
- *
- * Blocks are measured and cut **individually**. A message answering three calls
- * where one is a `find /` keeps the two small results whole, which is what makes
- * the per-block marker (rather than a per-event one) honest.
- */
 declare function truncateResultBlocks(event: SessionEvent): SessionEvent;
 //#endregion
 //#region src/engines/provider/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$1;
-  /** 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$1; /** System prompt (AI SDK v7 `instructions`). */
-  instructions?: string; /** Max loop steps per turn. Default 20. */
+  tools?: ToolSet$1;
+  instructions?: string;
   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. */
+  executor?: ToolExecutor;
+  executableTools?: string[];
+  vfs?: SandboxVfs;
   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. */
+  };
+  executionBackend?: ToolExecutionBackend;
+  shouldApprove?: (call: {
+    toolName: string;
+    input: unknown;
+  }) => boolean;
+  approvalTimeoutMs?: number;
   resolveModel?: (modelId: string | undefined) => LanguageModel$1;
-  /**
-   * Live MCP status for this session, when the host wired MCP at all. Unlike
-   * the CLI engines — which ask their binary — this engine's MCP is entirely
-   * host-assembled, so the host is the only party that can answer. Unset means
-   * "no MCP here", which reads as an empty list rather than an error: a session
-   * with no servers is a fact, not a missing feature.
-   *
-   * Named apart from the inherited `mcpServers` request field on purpose —
-   * that one is the *wire configuration* a client asked for, this one is what
-   * the host actually connected.
-   */
   reportMcpServers?: () => Promise<McpServerStatusInfo[] | undefined>;
-  /** 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. */
+  deferred?: boolean;
   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. */
+  pendingToolCalls: PendingToolCall[];
   dispatched: string[];
   numTurns: number;
   totalUsage: {
@@ -560,8 +219,6 @@ type AiSdkSessionState = {
     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;
@@ -570,12 +227,8 @@ type AiSdkSessionState = {
     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 = {
@@ -585,16 +238,6 @@ type ToolCallOutput = {
   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;
@@ -602,200 +245,66 @@ declare class AiSdkRunner implements Runner {
   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;
-  /**
-   * The same snapshot, taken without ending anything.
-   *
-   * `park()` and this are two operations that happen to produce the same value,
-   * and the difference is the whole point: `park()` *ends* the live runner
-   * (inert, listeners dropped, `onClose` called), which is right for deferred
-   * execution — the session has nothing to do for possibly days — and wrong for
-   * restart-survival, where the session is active and someone is mid-
-   * conversation. This one changes nothing at all: no status emit, no listener
-   * clear, no disposer. The host writes the value through to durable storage
-   * after each turn and keeps the runner live and warm, so a restart rebuilds
-   * from the last write through the existing `restore` path and the next message
-   * costs no wake.
-   *
-   * The gate is `park()`'s minus the requirement that there be something parked:
-   *
-   * - `#abort` set is refused for the reason it always was — a `generate()` in
-   *   flight has produced messages that are not in the history yet, so the
-   *   snapshot would be of a turn that half-happened.
-   * - Pending calls that are **not** all deferred are refused, which is
-   *   `park()`'s rule wearing a different hat. An in-process execution's result
-   *   is coming back to *this* runner and dies with the process; a restore would
-   *   wait on it forever, and `state.dispatched` is what would stop the rebuilt
-   *   runner from simply calling it again.
-   * - Idle with nothing pending — the case `park()` exists to refuse — is
-   *   exactly the case this exists to allow.
-   */
   snapshot(): RunnerSnapshot | undefined;
   sendMessage(text: string, attachments?: readonly AttachmentInput[]): 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). */
+  resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   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>;
-  /**
-   * Reset the conversation: drop the message array the next turn would have
-   * been built from. There is no engine round trip — this runner *is* where the
-   * transcript lives, so clearing it is the whole operation.
-   *
-   * Two things ride along, both already written elsewhere and both load-bearing
-   * here. `#emit`'s `conversation_reset` arm retires `#contextUsage` (the
-   * reading described a conversation that no longer exists), and the same arm
-   * in `restore` keeps a parked session that comes back after a clear from
-   * resurrecting it. Pending tool calls are NOT swept: a parked call is work a
-   * backend still owes an answer for, and a clear is not an interrupt — the
-   * refusal below is what keeps the two apart.
-   */
   clearContext(): Promise<void>;
   interrupt(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   setModel(model?: string): Promise<void>;
   fail(message: string): void;
   close(reason?: 'client' | 'server' | 'error'): void;
-  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
-   * "show everything" on one row, so a per-runner seq index would be a map
-   * maintained on every emit to save a walk nobody makes twice a minute. */
   eventAt(seq: number): SessionEvent | undefined;
   subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => 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;
-  /**
-   * This session's MCP servers, as the host assembled them.
-   *
-   * Always answers — an empty list when no MCP was wired — because the
-   * alternative (undefined, which the server turns into a 501) says "this
-   * engine cannot tell you", and this engine can: the host that built the
-   * session is the only party who knows, and it has been asked.
-   */
   mcpServers(): Promise<McpServerStatusInfo[] | undefined>;
-  /** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
-   * it (undefined) restores the derived title. The engine is never told. */
   setTitle(title: string | undefined): void;
 }
 //#endregion
 //#region src/engines/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/executors/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. */
+  allowedHosts?: string[];
   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. */
+  fetchTimeoutMs?: number;
+  defaultTimeoutMs?: number;
   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/lib/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;
@@ -810,45 +319,30 @@ type PendingOutcome<T> = {
 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, ...). */
+  createdAt: number;
+  expiresAt?: number;
   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. */
+  meta?: Record<string, unknown>;
   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/executors/browser-bridge-executor.d.ts
-/** Answer a bridged call, as delivered by the client over the wire. */
 type BridgeAnswer = {
   output: ToolExecutionOutput;
   logs?: string[];
@@ -858,404 +352,163 @@ type BridgeAnswer = {
   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. */
+  send: (frame: ToolCallRequestFrame) => boolean;
+  cancel?: (executionId: string, reason: string) => void;
   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/executors/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. */
+  input: unknown;
   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'. */
+  timeoutMs?: number;
   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/engines/provider/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. */
+  url: string;
+  digest?: string;
+  markdown?: string;
   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. */
+  fetchImpl?: typeof fetch;
+  maxContentBytes?: number;
   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. */
+  allowedHosts?: string[];
   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/engines/provider/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$1;
 };
 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. */
+  sessionId: string;
+  vfs?: SandboxVfs;
   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. */
+  }) => void;
   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$1;
-  definitions: ToolDefinition[]; /** Names the loop must not execute inline (they go through the executor). */
+  definitions: ToolDefinition[];
   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$1): ToolContext;
-/** A tool the host supplies, with the trust level it is to run at. */
 type HostToolDefinition = {
   tool: Tool$1;
-  /**
-   * Where this tool may run. `authoritative` tools execute inline in the
-   * gateway and MUST declare `execute`; `sandboxed` ones must NOT, because the
-   * loop hands them to the {@link ToolExecutor} seam instead — which is what
-   * makes them bridgeable to an untrusted tab.
-   */
   trust: ToolTrust;
 };
-/**
- * Add host-supplied tools to a context at an explicit trust level.
- *
- * The trust level is the whole point of the seam: {@link withMcpTools} can only
- * produce authoritative tools, so a host tool that *should* be sandboxed — and
- * therefore executable in the browser tab that asked for it — had no way to be
- * expressed at all. Here the host says which it is, and the contradictions are
- * refused rather than silently resolved:
- *
- * - a `sandboxed` tool carrying `execute` would run inline in this process with
- *   the gateway's ambient authority, which is exactly what sandboxing it was
- *   meant to prevent;
- * - an `authoritative` tool *without* `execute` would park the turn on a call no
- *   executor claims, and the session would simply stop.
- */
-declare function withHostTools(context: ToolContext, hostTools: Record<string, HostToolDefinition>, /** What to call these in error messages ('MCP tool', 'host tool'). */
-
-kind?: string): ToolContext;
+declare function withHostTools(context: ToolContext, hostTools: Record<string, HostToolDefinition>, kind?: string): ToolContext;
 //#endregion
 //#region src/engines/provider/session.d.ts
 type EngineSessionOptions = {
-  /** Resolved session config (profile defaults already applied). */config: AiSdkRunnerConfig; /** The profile that selected this engine, when there was one. */
+  config: AiSdkRunnerConfig;
   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$1;
-  /**
-   * 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. */
+  selectExecutor: (() => ToolExecutor) | ((call: ToolExecutionCall) => ToolExecutor);
+  backend?: 'server' | 'browser' | 'managed' | 'remote' | ((call: ToolExecutionCall) => 'server' | 'browser' | 'managed' | 'remote');
   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;
   };
-  /**
-   * A live MCP connection from {@link connectMcpTools} — the preferred way to
-   * hand MCP to a session, and the only one that can fail loudly.
-   *
-   * With this set, the session knows *which servers connected*, so two things
-   * that were previously silent become impossible: a profile naming a server
-   * that never connected refuses to build (see {@link mcpTools} for what that
-   * used to look like), and `runner.mcpServers()` answers `GET
-   * /sessions/:id/mcp` with the real per-server status instead of 501.
-   */
   mcp?: McpConnection;
-  /** 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.
-   *
-   * The bare tool set, for a host assembling one itself. Prefer {@link mcp}:
-   * a tool set alone cannot distinguish "this server connected and exposes no
-   * tools" from "this server never connected", so the check here has to be the
-   * cruder one — a declared server contributing no tools is refused. */
   mcpTools?: ToolSet$1;
-  /**
-   * Extra host tools, each at an explicit trust level (see
-   * {@link withHostTools}). This is the seam for a tool that is neither one of
-   * the built-in capabilities nor MCP — including a **sandboxed** one, which
-   * `mcpTools` cannot express because everything in it is authoritative by
-   * construction.
-   *
-   * A sandboxed tool here rides the same {@link ToolExecutor} seam
-   * `eval_script` does, so it executes wherever `selectExecutor` points — an
-   * in-process QuickJS guest, or the browser tab that asked the question.
-   */
   tools?: Record<string, HostToolDefinition>;
-  /** 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;
   };
-  /**
-   * Initial scratch-filesystem contents for a **new** session, and the safe way
-   * to seed one: it is ignored outright when `config.restore` is set, because a
-   * rehydrated session brings back the files its parked turn already wrote and
-   * seeding over them destroys exactly the work that was preserved.
-   *
-   * (Hand-building `config.vfs` still works and still wins — but then the
-   * `restore ? undefined : createVfs(...)` dance is yours to get right.)
-   */
+  shouldApprove?: (call: {
+    toolName: string;
+    input: unknown;
+  }) => boolean;
+  approvalTimeoutMs?: number;
   seedVfs?: Record<string, string>;
-  /**
-   * Build the session under this id rather than minting one.
-   *
-   * Forward the server's `EngineRunnerContext.id` here, always: it is set when
-   * the gateway is rehydrating a session across a restart, and a runner that
-   * ignores it comes back as a *different* session — the rebuild is refused,
-   * and every client's route and unread watermark is stranded. Ignored when
-   * `config.restore` is present, which carries its own id.
-   */
   id?: string;
 };
-/**
- * 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$1;
-  /**
-   * One entry per configured server, connected or not — the truth a session was
-   * assembled against. Handed to {@link createEngineSession} as `mcp`, it is
-   * what `GET /sessions/:id/mcp` answers with and what makes a half-connected
-   * session refuse to build rather than run degraded.
-   */
   servers: McpServerStatusInfo[];
   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.
- *
- * **A stateless MCP server must answer `GET` with 405.** The client opens the
- * SSE stream with a `GET` before it sends anything, and a POST-only server
- * mounted under a framework's default 404 makes the whole connect fail with an
- * error that names neither the method nor the route. This is the single most
- * common way an otherwise-correct MCP mount fails.
- */
 declare function connectMcpTools(servers: Record<string, McpServerConfigWire>, options?: {
-  /** `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. */
   onError?: (name: string, error: unknown) => void;
-  /**
-   * Reject if any server fails to connect, after closing the ones that did.
-   *
-   * Off by default, which is right for an operator's fleet — one unreachable
-   * server should not take a whole gateway's sessions down. Turn it **on**
-   * when the servers are the app's own: an embedder who mounts one wiki server
-   * and gets a session without it has a session that cannot do its job, and
-   * finding that out at connect time beats finding it out from a transcript
-   * where the agent apologises.
-   */
   required?: boolean;
 }): Promise<McpConnection>;
 //#endregion
 //#region src/lib/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;
@@ -1265,40 +518,19 @@ declare class InputQueue implements AsyncIterable<SDKUserMessage> {
 //#endregion
 //#region src/lib/normalize.d.ts
 declare function toApiMessage(message: unknown): ApiMessage;
-/**
- * The CLI's MCP status, as `McpServerStatusInfo`.
- *
- * The narrowing is the point: the SDK's config object carries `env` for stdio
- * servers and `headers` for HTTP ones, and both routinely hold API tokens. This
- * is the one place they are dropped, so no client — dashboard, phone, or a host
- * app reading the REST route — can turn "show me my MCP servers" into a
- * credential dump. Only the connection's identity survives.
- */
 declare function mcpStatusInfo(status: McpServerStatus): McpServerStatusInfo;
-/** The half of the SDK's `ModelInfo` this package forwards. Structurally typed so
- * the mapping can be unit-tested without a live query. */
 type SdkModelInfo = {
   value: string;
   resolvedModel?: string;
   displayName: string;
-  description?: string; /** Per-model reasoning efforts, when the SDK reports them (0.3.221+). */
+  description?: string;
   supportedEffortLevels?: string[];
   supportsEffort?: boolean;
 };
 declare function modelOptionsFromSdk(models: readonly SdkModelInfo[]): ModelOption[];
-/**
- * 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
 //#region src/engines/adapter.d.ts
-/**
- * A probe's verdict on one profile's credentials. 'unknown' means the probe
- * could not run at all — which is NOT evidence of a missing login and must
- * never be surfaced as one (the `checkClaudeAuth` discipline, generalized).
- */
 type EngineAvailability = {
   available: true;
 } | {
@@ -1307,68 +539,22 @@ type EngineAvailability = {
 } | {
   available: 'unknown';
 };
-/**
- * A model catalog shipped with the release — the answer to "what can a create
- * form offer" with no process spawned, correct from a gateway's first request.
- *
- * Never contains a 'default' sentinel row (a choice, not a model — forms add
- * their own "Profile default" row mapping to an unset model). Staleness is
- * bounded by the release cadence: the release checklist re-runs each catalog's
- * extraction procedure (documented in its file header) and diffs.
- */
 type ModelCatalog = {
-  models: ModelOption[]; /** Source + date, for the release-checklist refresh. Not served. */
+  models: ModelOption[];
   provenance: string;
 };
 type EngineRunnerRequest = {
   config: SessionRunnerConfig;
   profile?: ProfileInfo;
-  /** Rebuild a parked session instead of starting fresh. Engines that cannot
-   * rehydrate throw. */
   restore?: RunnerSnapshot;
-  /**
-   * Adopt this session id instead of minting one. For rehydrating a session
-   * across a gateway restart: the transcript comes back from the *engine's* own
-   * store via `config.resume`, but every client keys its watermarks, unread
-   * counts and routes on the WorkerDeck id, so that id has to survive too
-   * (`SessionInfo.id` is documented as stable across resumes). A `restore`
-   * carries its own id in the snapshot and does not need this.
-   */
   id?: string;
 };
-/**
- * One engine, as the server consumes it: its capability record, its shipped
- * model catalog, a credential probe, and a runner factory. The claude adapter
- * wraps `SessionRunner` without behaviour change; the codex adapter owns the
- * `codex app-server` integration; the provider adapter is a pseudo-adapter —
- * its runners are built by the host's `createEngineRunner` hook, so its
- * `createRunner` throws and the server routes around it.
- */
 interface EngineAdapter {
   readonly engine: ProfileEngine;
-  /** Must deep-equal ENGINE_CAPABILITIES[engine] — asserted by a core test, so
-   * the protocol's browser-safe defaults can never drift from the adapter. */
   readonly capabilities: EngineCapabilities;
   readonly catalog: ModelCatalog;
-  /**
-   * Probe whether `profile`'s credentials are usable under `env` — the full
-   * session environment the real assembly path produces, never a delta (codex
-   * replaces the child env wholesale, and a delta would strand HOME/PATH and
-   * the auth chain with it). Never rejects.
-   */
   checkAvailability(profile: ProfileInfo, env: Record<string, string | undefined>): Promise<EngineAvailability>;
-  /** Build a Runner. Throwing fails the create (session POST 500s, job fails). */
   createRunner(request: EngineRunnerRequest): Runner | Promise<Runner>;
-  /**
-   * List the engine's on-disk resumable sessions (`GET /sdk-sessions`) —
-   * present exactly when the capability record's `listSessions` is true. Must
-   * not require a live session: the codex adapter answers over a short-lived
-   * `thread/list` app-server child it closes before returning; the claude
-   * adapter reads the Agent SDK's store directly. `env` follows the
-   * checkAvailability contract (the profile's complete session environment,
-   * never a delta). `dir` narrows to one project directory; `limit`/`offset`
-   * page the newest-first result.
-   */
   listSessions?(options: {
     profile?: ProfileInfo;
     env: Record<string, string | undefined>;
@@ -1377,66 +563,18 @@ interface EngineAdapter {
     offset?: number;
   }): Promise<SdkSessionSummary[]>;
 }
-/** The in-repo adapter for an engine. An absent `engine` means 'claude'. */
 declare function getEngineAdapter(engine: ProfileEngine | undefined): EngineAdapter;
 //#endregion
 //#region src/engines/claude/adapter.d.ts
-/**
- * The Claude engine as an adapter — a thin, behaviourally inert wrapper:
- * `SessionRunner` unchanged, `checkClaudeAuth` as the probe, the static
- * catalog for create forms. Exists so catalogs, capabilities and availability
- * have one shape across engines; the runner itself is exactly what
- * `registry.prepare()` builds.
- */
 declare const claudeAdapter: EngineAdapter;
 //#endregion
 //#region src/engines/claude/catalog.d.ts
-/**
- * The Claude engine's model catalog — what a create form offers before any
- * session has run.
- *
- * **Refresh procedure** (release checklist): run `supportedModels()` on a
- * throwaway SDK query (no tokens spent) and re-apply the shaping rules of
- * `modelOptionsFromSdk` (`src/normalize.ts`) at authoring time: drop the
- * `default` sentinel row, derive display names from resolved ids where
- * unambiguous, mark the newest of each family `primary`, sort by family rank.
- * A unit test replays the raw extraction through `modelOptionsFromSdk` and
- * asserts these rows match, so the rules cannot drift.
- *
- * Two things the live `capabilities` event can never offer:
- * - rows for **older models** the CLI no longer reports (hand-maintained, the
- *   accepted cost of a static catalog; the CLI silently downgrades an effort a
- *   model doesn't support, so `reasoningEfforts` is omitted on them and the
- *   engine default set applies);
- * - an answer on a **cold server**. The live event still exists and remains
- *   the in-session truth for the model switcher; this catalog is the
- *   create-form truth.
- *
- * `defaultModel` is deliberately NOT here: a claude profile's default is the
- * operator's CLI config, unknowable statically.
- */
 declare const CLAUDE_CATALOG: ModelCatalog;
 //#endregion
 //#region src/engines/codex/types.d.ts
-/**
- * Structural mirror of the slice of the `codex app-server` JSON-RPC v2 surface
- * this engine consumes. Local on purpose: no published client for this
- * protocol exists, the shapes are regenerated from the binary itself
- * (`codex app-server generate-json-schema --out <dir>`, verified 2026-08-05
- * against 0.146.0), and every open-ended axis is a plain string so a newer
- * binary degrades to the unknown-item path instead of a type error.
- *
- * Naming note: the v2 surface is camelCase (`aggregatedOutput`, `exitCode`,
- * `localImage`) where `codex exec`'s JSONL — the retired first transport, and
- * what OpenAI's own docs mostly show — is snake_case. The two vocabularies
- * look alike but are not interchangeable.
- */
-/** `TokenUsageBreakdown` — one entry of `thread/tokenUsage/updated`. OpenAI
- * accounting: `inputTokens` INCLUDES the cached share (the relation the
- * runner's subtraction assumes, asserted in `smoke:codex`). */
 type AppServerTokenUsage = {
   inputTokens: number;
-  cachedInputTokens: number; /** Default 0 in the schema; absent in some payloads. */
+  cachedInputTokens: number;
   cacheWriteInputTokens?: number;
   outputTokens: number;
   reasoningOutputTokens: number;
@@ -1447,8 +585,6 @@ type AppServerAgentMessageItem = {
   type: 'agentMessage';
   text: string;
 };
-/** `summary` is what streams by default (`item/reasoning/summaryTextDelta`);
- * `content` is raw CoT and only populated when the operator's config asks. */
 type AppServerReasoningItem = {
   id: string;
   type: 'reasoning';
@@ -1460,11 +596,9 @@ type AppServerCommandExecutionItem = {
   type: 'commandExecution';
   command: string;
   aggregatedOutput?: string;
-  exitCode?: number | null; /** 'inProgress' | 'completed' | 'failed' | 'declined' — open. */
+  exitCode?: number | null;
   status: string;
 };
-/** v2 `kind` is an object (`{type: 'add'|'delete'|'update', move_path?}`) —
- * the snake_case JSONL's was a bare string; mapped defensively. */
 type AppServerFileChangeItem = {
   id: string;
   type: 'fileChange';
@@ -1494,18 +628,6 @@ type AppServerWebSearchItem = {
   type: 'webSearch';
   query: string;
 };
-/**
- * A picture the model made with codex's built-in `image_gen` tool.
- *
- * `savedPath` is an absolute path on the **host** — by default under
- * `$CODEX_HOME/generated_images/`, or inside the workspace when the model was
- * told the asset belongs to the project. It is the only reference we get: the
- * app-server never sends the bytes, and neither do we (the event log carries
- * references, never base64 — see the protocol's note on attachments).
- *
- * `result` is an undocumented free-form string. Treated as untrusted length:
- * short values are shown, anything long enough to be an encoded image is not.
- */
 type AppServerImageGenerationItem = {
   id: string;
   type: 'imageGeneration';
@@ -1514,37 +636,22 @@ type AppServerImageGenerationItem = {
   result: string;
   savedPath?: string;
 };
-/** The model *looked at* an image on disk (`path`, host-absolute). */
 type AppServerImageViewItem = {
   id: string;
   type: 'imageView';
   path: string;
 };
-/**
- * A sub-agent lifecycle edge, on the thread that OWNS the agent. The spawn
- * signal (verified live against 0.146.0, `_docs/codex-subagent-trace-fixed.jsonl`):
- * `kind: 'started'` announces a new agent, and `id` is the `call_id` of the
- * model's own `spawn_agent` function call — a genuine tool-use id, which is what
- * lets the runner hang the whole sidechain off it. There is **no 'completed'
- * kind**: an agent's end travels as its own thread's `turn/completed`.
- */
 type AppServerSubAgentActivityItem = {
   id: string;
-  type: 'subAgentActivity'; /** 'started' | 'interacted' | 'interrupted' — open, and 'completed' does not exist. */
-  kind: string; /** The thread the agent runs in — the key every later notification carries. */
-  agentThreadId: string; /** The agent's address, e.g. '/root/date_one'; the basename is its name. */
+  type: 'subAgentActivity';
+  kind: string;
+  agentThreadId: string;
   agentPath?: string | null;
 };
-/**
- * The model's collab-agent tool surface (`spawnAgent | sendInput | resumeAgent |
- * wait | closeAgent`). Decoration, not the design's load-bearing signal: on the
- * wire only `wait` has been observed, with every rich field empty — the spawn
- * truth is {@link AppServerSubAgentActivityItem} (same trace as above).
- */
 type AppServerCollabAgentToolCallItem = {
   id: string;
   type: 'collabAgentToolCall';
-  tool: string; /** 'inProgress' | 'completed' | 'failed' | 'declined' — open. */
+  tool: string;
   status: string;
   senderThreadId?: string | null;
   receiverThreadIds?: string[] | null;
@@ -1553,58 +660,38 @@ type AppServerCollabAgentToolCallItem = {
   reasoningEffort?: string | null;
   agentsStates?: Record<string, unknown> | null;
 };
-/** The user's own message, echoed back as an item — dropped (the runner
- * already emitted its `user_message`). */
 type AppServerUserMessageItem = {
   id: string;
   type: 'userMessage';
   content?: unknown;
 };
 type AppServerItem = AppServerAgentMessageItem | AppServerReasoningItem | AppServerCommandExecutionItem | AppServerFileChangeItem | AppServerMcpToolCallItem | AppServerWebSearchItem | AppServerImageGenerationItem | AppServerImageViewItem | AppServerUserMessageItem | AppServerSubAgentActivityItem | AppServerCollabAgentToolCallItem;
-/** The `Turn` object of `turn/started` / `turn/completed`. On a completed turn
- * `items` is a summary page whose final `agentMessage` is the turn's answer —
- * for a sub-agent's thread, that is the agent's report. */
 type AppServerTurn = {
-  id: string; /** 'inProgress' | 'completed' | 'failed' | 'interrupted' — open. */
+  id: string;
   status: string;
   error?: {
     message: string;
   } | null;
   items?: AppServerItem[];
 };
-/**
- * One historical turn as `thread/resume` / `thread/read {includeTurns: true}`
- * return it: the same `ThreadItem` vocabulary the live `item/completed`
- * notifications carry (so the live mapping replays it unchanged), plus an
- * `itemsView` marker ('full' | 'summary' | 'notLoaded') saying how much of
- * `items` was actually loaded. Measured against 0.146.0: both surfaces return
- * 'full' items in chronological order.
- */
 type AppServerHistoryTurn = {
   id: string;
   items?: AppServerItem[];
   itemsView?: string;
   status?: string;
 };
-/**
- * One `thread/list` row (the summary Thread shape — its `turns` is always
- * empty on list responses). Timestamps are epoch **seconds** (the protocol's
- * summaries want ms). `id` is what `CreateSessionRequest.resume` feeds
- * `thread/resume`; the row's separate `sessionId` field is not it.
- */
 type AppServerThreadSummary = {
-  id: string; /** Operator-set thread name, when one exists. */
-  name?: string | null; /** First user message — the natural summary line. */
+  id: string;
+  name?: string | null;
   preview?: string | null;
   createdAt?: number | null;
   updatedAt?: number | null;
-  cwd?: string | null; /** Ephemeral threads are never materialized on disk — not resumable. */
+  cwd?: string | null;
   ephemeral?: boolean;
   gitInfo?: {
     branch?: string | null;
   } | null;
 };
-/** `thread/list` result: one page plus an opaque continuation cursor. */
 type AppServerThreadListResponse = {
   data?: AppServerThreadSummary[];
   nextCursor?: string | null;
@@ -1616,57 +703,21 @@ type AppServerUserInput = {
   type: 'localImage';
   path: string;
 };
-/**
- * One live `codex app-server` child as the runner consumes it. The real
- * implementation (`process.ts`) spawns the binary and frames JSON-RPC
- * over its stdio; unit tests inject a scripted one — no process, no
- * credentials.
- */
 type AppServerConnection = {
-  /** Client→server request. Rejects on a JSON-RPC error response, a dead
-   * child, or a closed connection. */
-  request(method: string, params?: unknown): Promise<unknown>; /** Client→server notification (fire and forget). */
-  notify(method: string, params?: unknown): void; /** Server→client notifications. One handler (the runner). */
+  request(method: string, params?: unknown): Promise<unknown>;
+  notify(method: string, params?: unknown): void;
   onNotification(handler: (method: string, params: unknown) => void): void;
-  /** Server→client REQUESTS (approvals live here): the handler's resolution is
-   * sent back as the JSON-RPC result; a throw becomes an error response. `id`
-   * is the wire request id — `serverRequest/resolved` names it when codex
-   * settles a request on its own (auto-resolution), so the runner can retire
-   * the matching pending approval instead of leaving a stale card. */
   onRequest(handler: (method: string, params: unknown, id: string | number) => Promise<unknown>): void;
-  /** Fires once when the child exits or the pipe breaks — NOT on `close()`.
-   * The message carries an exit summary and a stderr tail for diagnostics. */
-  onClose(handler: (message: string) => void): void; /** Tear the child down (session close). Suppresses the onClose callback. */
+  onClose(handler: (message: string) => void): void;
   close(): void;
 };
 type AppServerConnectOptions = {
-  /** Complete child environment — a provided spawn env replaces process.env,
-   * never merges with it (CODEX_HOME pin already applied). */
   env: Record<string, string>;
 };
-/** The injectable connection factory: `connectAppServer` under the resolved
- * binary in production, a scripted peer in tests. */
 type AppServerConnectFn = (options: AppServerConnectOptions) => AppServerConnection;
 //#endregion
 //#region src/engines/codex/adapter.d.ts
-/**
- * The codex binary sessions will run: the per-platform package installed next
- * to `@openai/codex`, `vendor/<target-triple>/bin/codex` — the same file the
- * npm wrapper's own `bin/codex.js` launcher execs. Probing this binary rather
- * than whatever `codex` is on PATH means the availability answer is about the
- * executable sessions will actually run. Undefined when it can't be found;
- * callers degrade to 'unknown'.
- */
 declare function resolveBundledCodexExecutable(): string | undefined;
-/**
- * CODEX_HOME's threads over ONE short-lived `codex app-server` child: the
- * runner's own handshake (`experimentalApi` and all — one code path, no
- * second vocabulary to drift), `thread/list` pages walked by cursor, child
- * closed before returning. Requires no live session and costs no tokens —
- * it is how "resume" is offered before anything is running. The `connectFn`
- * seam exists for the scripted-peer tests; the adapter passes the real
- * spawn.
- */
 declare function listCodexSessions(options: {
   connectFn: AppServerConnectFn;
   profile?: ProfileInfo;
@@ -1675,26 +726,24 @@ declare function listCodexSessions(options: {
   limit?: number;
   offset?: number;
 }): Promise<SdkSessionSummary[]>;
-/**
- * OpenAI Codex as an engine: the codex CLI binary driven over its `app-server`
- * JSON-RPC surface — structurally the Claude engine's sibling (a local agent
- * binary with sessions, sandboxing and resume, resolving its own credentials
- * from the operator's environment). `@openai/codex` — the npm package that
- * carries the binary — is an **optional peer**: absent, every codex profile
- * reports unavailable and createRunner throws the same message, and no
- * consumer downloads a ~40 MB per-platform binary it never uses.
- */
 declare const codexAdapter: EngineAdapter;
 //#endregion
 //#region src/engines/codex/catalog.d.ts
 /**
- * The Codex engine's model catalog, seeded from the binary's own embedded
- * presets — `@openai/codex@0.146.0` ships its model table inside the
- * executable, and that table (not the SDK's stale `ModelReasoningEffort`
- * union) is the truth about which reasoning efforts each model takes.
- *
- * **Refresh procedure** (release checklist): extract the embedded JSON from
- * the platform binary and diff —
+ * The Codex engine's model catalog, seeded from the binary's own embedded model
+ * table (see `provenance` for the version) — that table, not the SDK's stale
+ * `ModelReasoningEffort` union, is the truth about which reasoning efforts each
+ * model takes. Mapping decisions: the internal `codex-auto-review` row is dropped
+ * (the codex analogue of the CLI's `default` sentinel), `primary` mirrors the
+ * binary's own `visibility` field so both UIs group the way codex's picker does,
+ * and `reasoningEfforts` carries `supported_reasoning_levels` verbatim — `max`
+ * and `ultra` go beyond the SDK union, so trust the binary and keep strings open.
+ *
+ * **Refresh procedure** (release checklist): extract the embedded JSON from the
+ * platform binary and diff. The two-hop resolve is NOT optional — under pnpm's
+ * strict layout the platform package is a dependency of `@openai/codex` and
+ * resolves only from that wrapper's location (MODULE_NOT_FOUND otherwise), the
+ * same two hops `resolveBundledCodexExecutable` makes.
  *
  *   node -e 'const d=require("fs").readFileSync(process.argv[1]);
  *     const s=d.indexOf(`{\n  "models": [`);
@@ -1706,55 +755,17 @@ declare const codexAdapter: EngineAdapter;
  *       const w=require.resolve("@openai/codex/package.json");
  *       createRequire(w).resolve("@openai/codex-darwin-arm64/package.json")
  *         .replace("package.json","vendor/aarch64-apple-darwin/bin/codex")')"
- *
- * The two-hop resolve is NOT optional: under pnpm's strict layout the platform
- * package is a dependency of `@openai/codex`, so it resolves only from that
- * wrapper's location, never from the repo root. Resolving it directly throws
- * MODULE_NOT_FOUND — the same two hops `resolveBundledCodexExecutable` makes.
- *
- * Mapping decisions:
- * - the internal `codex-auto-review` row is dropped (the codex analogue of
- *   dropping the CLI's `default` sentinel);
- * - `primary` mirrors the binary's own `visibility` field ('list' = shown in
- *   its picker, 'hide' = its "older models"), so both UIs group the way
- *   codex's own picker does;
- * - `reasoningEfforts` carries `supported_reasoning_levels` verbatim — note
- *   `max`/`ultra` beyond the SDK union; trust the binary, keep strings open.
  */
 declare const CODEX_CATALOG: ModelCatalog;
 //#endregion
 //#region src/engines/codex/runner.d.ts
 type CodexRunnerConfig = CreateSessionRequest & {
-  /** The injectable connection factory. The codex adapter passes
-   * `connectAppServer` under the resolved binary; unit tests pass a scripted
-   * peer. Required — this class never spawns anything itself. */
   connectFn: AppServerConnectFn;
-  /** Base environment for the codex child. Defaults to process.env. Passed to
-   * spawn **complete** — a child env replaces, never merges. */
-  env?: Record<string, string | undefined>; /** CODEX_HOME pin from the profile (auth, config.toml, thread storage). */
+  env?: Record<string, string | undefined>;
   codexHome?: string;
-  /** Timeout for pending approvals when the request itself doesn't set one.
-   * Default 300000 — the SessionRunner default. */
   defaultApprovalTimeoutMs?: number;
-  /** With `resume`: replay the thread's prior turns as `replay: true` events
-   * before anything else, so late-attaching clients get a full transcript —
-   * the SessionRunner option, same name, same default (true). */
   backfillHistory?: boolean;
 };
-/**
- * The Codex engine, over the binary's `app-server` JSON-RPC surface: ONE
- * `codex app-server` child per *session* (spawned lazily, held across turns),
- * streaming `item/agentMessage/delta` and the reasoning deltas token-by-token
- * (`streaming: 'token'`). Follows `SessionRunner`'s event-log/seq/status
- * discipline with `AiSdkRunner`'s turn-chain (one turn at a time; sendMessage
- * queues). The first codex transport was `codex exec --experimental-json` (one
- * child per turn) — retired because its JSONL carries no partial messages, so
- * a turn could never stream.
- *
- * A dead child is a failed *turn*, not a failed session: the thread persists
- * on disk, the connection is dropped, and the next message spawns a fresh
- * child that `thread/resume`s the same thread id.
- */
 declare class CodexRunner implements Runner {
   #private;
   readonly id: string;
@@ -1765,119 +776,32 @@ declare class CodexRunner implements Runner {
   get lastSeq(): number;
   get pendingApprovals(): PermissionRequest[];
   info(): SessionInfo;
-  /** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
-   * it (undefined) restores the derived title. The engine is never told. */
   setTitle(title: string | undefined): void;
   start(): Promise<void>;
   sendMessage(text: string, attachments?: readonly AttachmentInput[]): void;
-  /** Resolve a pending approval. Returns false if the id is unknown (e.g.
-   * timed out, or already settled by codex itself). */
   resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   interrupt(): Promise<void>;
-  /**
-   * Reset the conversation: a **fresh thread on the same session**.
-   *
-   * Codex has no clear/reset RPC — `thread/compact/start` summarises and
-   * continues, `thread/fork` makes a second thread, and neither is "same
-   * session, empty context". So the analog is to stop resuming the old thread
-   * and start a new one, which is the path a dead child already takes minus the
-   * resume. The old thread is NOT deleted: it stays in CODEX_HOME and stays
-   * resumable from `GET /sdk-sessions`.
-   *
-   * Two things it does on the way through, both mirroring the Claude engine's
-   * SDK-driven reset (`engines/claude/runner.ts`):
-   *
-   * 1. **The new thread id is adopted before `conversation_reset` is emitted**,
-   *    whenever a child is already up — the eager `thread/start` costs no
-   *    tokens and no model call, and it is what keeps the dormant record from
-   *    ever naming the conversation that was just cleared. With no child there
-   *    is nothing to start against and the id is simply dropped; the parking
-   *    service treats a resumable session with no engine session id as one with
-   *    nothing to come back to, and forgets the stale record.
-   * 2. **The context reading is retired**, in `#emit`'s `conversation_reset`
-   *    arm. Codex cannot re-poll it the way Claude does — the only source is
-   *    `thread/tokenUsage/updated`, which arrives *during* a turn — so there is
-   *    no reading at all until the next turn runs, and the protocol's rule
-   *    applies: render nothing rather than a stale ring or a 0%.
-   *
-   * The turn counter stays monotonic across this, on purpose (it is an unread
-   * cursor, not an item count), and so does `activityCount` — `#emit` owns both.
-   */
   clearContext(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   setModel(model?: string): Promise<void>;
   fail(message: string): void;
   close(reason?: 'client' | 'server' | 'error'): void;
-  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
-   * "show everything" on one row, so a per-runner seq index would be a map
-   * maintained on every emit to save a walk nobody makes twice a minute. */
   eventAt(seq: number): SessionEvent | undefined;
   subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => void;
-  /**
-   * The session's MCP servers, live from the binary.
-   *
-   * Two sources merged, because codex splits them: `mcpServerStatus/list` says
-   * what is configured and what each server exposes (including every tool's
-   * full JSON Schema, which the Agent SDK does not give us), and the
-   * `mcpServer/startupStatus/updated` notifications say which of them are
-   * actually up.
-   *
-   * Answers **before the session has connected**, over a throwaway child, for
-   * the same reason the skill list does: a codex session spawns nothing until
-   * it has work, and a panel that said "no MCP servers configured" until the
-   * first turn would be stating something false about the operator's config.
-   * The request blocks until the servers are enumerated (measured: complete on
-   * the very first call), so there is no half-populated answer to race.
-   *
-   * Resolves undefined only when there is genuinely nothing to say — the
-   * session is closed, or the child could not be spoken to. The route turns
-   * that into a 501.
-   *
-   * **Listing only.** There is no per-server reconnect or toggle on this
-   * transport — hence no `reconnectMcpServer`/`setMcpServerEnabled` here, and
-   * `ENGINE_CAPABILITIES.codex.mcpServerActions: false` so clients render the
-   * panel read-only instead of offering buttons that cannot work.
-   */
   mcpServers(): Promise<McpServerStatusInfo[] | undefined>;
 }
 //#endregion
 //#region src/engines/codex/process.d.ts
-/**
- * Spawn one `codex app-server` child and frame JSON-RPC over its stdio — the
- * real {@link AppServerConnectFn}. The child's env is passed **complete**
- * (a provided spawn env replaces process.env, never merges with it), with the
- * profile's CODEX_HOME pin already applied by the runner.
- *
- * No spawn cwd: the working directory is a thread/turn parameter, and a cwd
- * that doesn't exist should fail the *turn* with codex's own error, not the
- * spawn.
- */
 declare function connectAppServer(options: {
   executable: string;
   env: Record<string, string>;
 }): AppServerConnection;
 //#endregion
 //#region src/engines/codex/jsonrpc.d.ts
-/**
- * A JSON-RPC error response from the peer, or one we return to it. `code`
- * follows the JSON-RPC 2.0 reserved ranges (-32601 = method not found).
- */
 declare class JsonRpcError extends Error {
   readonly code: number;
   constructor(code: number, message: string);
 }
-/**
- * JSON-RPC over a `codex app-server` child's stdio: **newline-delimited JSON**,
- * one message per line, and — verified against 0.146.0 — an envelope *without*
- * the `jsonrpc: "2.0"` field (`{id, method, params}` / `{id, result}` /
- * `{id, error}`; the binary's own schema marks only those required). Server→
- * client notifications additionally carry a top-level `emittedAtMs`, ignored
- * here.
- *
- * Transport only: no method knowledge, no process ownership. The process
- * wrapper (`process.ts`) owns the child and calls {@link fail} when it dies so
- * every in-flight request rejects instead of hanging.
- */
 declare class JsonRpcStdioConnection {
   #private;
   constructor(options: {
@@ -1888,23 +812,10 @@ declare class JsonRpcStdioConnection {
   notify(method: string, params?: unknown): void;
   onNotification(handler: (method: string, params: unknown) => void): void;
   onRequest(handler: (method: string, params: unknown, id: string | number) => Promise<unknown>): void;
-  /** Reject everything in flight and refuse new traffic — the child is gone
-   * (or the session is over). Idempotent. */
   fail(message: string): void;
 }
 //#endregion
 //#region src/engines/provider/adapter.d.ts
-/**
- * The model-agnostic provider engine as a pseudo-adapter: capabilities and an
- * env-var probe live here, but its runners are assembled by the host's
- * `createEngineRunner` hook (which is where provider credentials are resolved
- * and model SDKs are imported — neither belongs in this repo's import graph).
- * The server routes provider creates to the hook; `createRunner` here throws
- * so a mis-routed call fails loudly instead of quietly building nothing.
- *
- * The catalog is empty by the same token: provider model ids are operator-
- * declared per profile (`provider.models`), not shipped with releases.
- */
 declare const providerAdapter: EngineAdapter;
 //#endregion
 export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type AppServerConnectFn, type AppServerConnectOptions, type AppServerConnection, type AppServerHistoryTurn, type AppServerItem, type AppServerThreadListResponse, type AppServerThreadSummary, type AppServerTokenUsage, type AppServerTurn, type AppServerUserInput, type AttachmentInput, type AttachmentKind, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, CLAUDE_CATALOG, CODEX_CATALOG, type ClaudeAuthProbe, type ClaudeAuthStatus, CodexRunner, type CodexRunnerConfig, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineAdapter, type EngineAvailability, type EngineRunnerRequest, type EngineSessionOptions, type HistoryFn, type HostFetch, type HostToolDefinition, InputQueue, JsonRpcError, JsonRpcStdioConnection, type LanguageModel, type McpConnection, type ModelCatalog, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, SUPPORTED_ATTACHMENT_TYPES, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type Tool, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolSet, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, truncateResultBlocks, withHostTools, withMcpTools };