@workerdeck/core 0.7.0 → 0.11.0

package/build/index.d.mts

@@ -1,8 +1,49 @@
-import { Options, Query, SDKMessage, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import { McpServerStatus, Options, Query, SDKMessage, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import { ApiMessage, CreateSessionRequest, EngineCapabilities, McpServerConfigWire, McpServerStatusInfo, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, ProfileInfo, SdkSessionSummary, SessionEvent, SessionEventBody, SessionInfo, SessionStatus, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput } from "@workerdeck/protocol";
 import { LanguageModel, ModelMessage, Tool, ToolSet } from "ai";
 import { SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
-import { ApiMessage, CreateSessionRequest, McpServerConfigWire, PermissionMode, PermissionRequest, ProfileEngine, ProfileInfo, SessionEvent, SessionEventBody, SessionInfo, SessionStatus, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput } from "@workerdeck/protocol";
+import { Readable, Writable } from "node:stream";
 
+//#region src/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;
+};
+/**
+ * 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/tool-executor.d.ts
 /**
  * Result of one tool execution, whenever it arrives. `failed` is a normal
@@ -136,8 +177,22 @@ interface Runner {
   info(): SessionInfo;
   /** Replay buffered events with seq > afterSeq, then deliver live events. Returns unsubscribe. */
   subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
-  /** Queue a user message for the session (starts the next turn when idle). */
-  sendMessage(text: string): void;
+  /** 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>;
@@ -202,10 +257,23 @@ declare class SessionRunner implements Runner {
   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). */
-  sendMessage(text: string): 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>;
@@ -348,7 +416,7 @@ declare class AiSdkRunner implements Runner {
    * or an already-closed/parked runner.
    */
   park(): RunnerSnapshot | undefined;
-  sendMessage(text: string): void;
+  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.
@@ -383,6 +451,9 @@ declare class AiSdkRunner implements Runner {
    * deferred executor). Idempotent by executionId.
    */
   settleExecution(executionId: string, result: ToolExecutionResult): boolean;
+  /** 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/claude-auth.d.ts
@@ -837,6 +908,27 @@ declare class InputQueue implements AsyncIterable<SDKUserMessage> {
 //#endregion
 //#region src/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+). */
+  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
@@ -844,5 +936,532 @@ declare function toApiMessage(message: unknown): ApiMessage;
  */
 declare function normalizeSdkMessage(msg: SDKMessage): SessionEventBody | null;
 //#endregion
-export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, type ClaudeAuthProbe, type ClaudeAuthStatus, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineSessionOptions, type HistoryFn, type HostFetch, InputQueue, type McpConnection, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, checkClaudeAuth, connectMcpTools, createEngineSession, createToolContext, createWebFetch, htmlToMarkdown, isHostAllowed, isPrivateAddress, normalizeSdkMessage, resolveBundledClaudeExecutable, toApiMessage, toExecutionResult, withMcpTools };
+//#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;
+} | {
+  available: false;
+  reason: string;
+} | {
+  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. */
+  provenance: string;
+};
+type EngineRunnerRequest = {
+  config: SessionRunnerConfig;
+  profile?: ProfileInfo;
+  /** Rebuild a parked session instead of starting fresh. Engines that cannot
+   * rehydrate throw. */
+  restore?: RunnerSnapshot;
+};
+/**
+ * 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>;
+    dir?: string;
+    limit?: number;
+    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. */
+  cacheWriteInputTokens?: number;
+  outputTokens: number;
+  reasoningOutputTokens: number;
+  totalTokens: number;
+};
+type AppServerAgentMessageItem = {
+  id: string;
+  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';
+  content?: string[];
+  summary?: string[];
+};
+type AppServerCommandExecutionItem = {
+  id: string;
+  type: 'commandExecution';
+  command: string;
+  aggregatedOutput?: string;
+  exitCode?: number | null; /** 'inProgress' | 'completed' | 'failed' | 'declined' — open. */
+  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';
+  changes: Array<{
+    path: string;
+    kind: string | {
+      type: string;
+    };
+    diff?: string;
+  }>;
+  status: string;
+};
+type AppServerMcpToolCallItem = {
+  id: string;
+  type: 'mcpToolCall';
+  server: string;
+  tool: string;
+  arguments: unknown;
+  result?: unknown;
+  error?: {
+    message: string;
+  } | null;
+  status: string;
+};
+type AppServerWebSearchItem = {
+  id: string;
+  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';
+  status: string;
+  revisedPrompt?: string | null;
+  result: string;
+  savedPath?: string;
+};
+/** The model *looked at* an image on disk (`path`, host-absolute). */
+type AppServerImageViewItem = {
+  id: string;
+  type: 'imageView';
+  path: string;
+};
+/** 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;
+/** The `Turn` object of `turn/started` / `turn/completed`. */
+type AppServerTurn = {
+  id: string; /** 'inProgress' | 'completed' | 'failed' | 'interrupted' — open. */
+  status: string;
+  error?: {
+    message: string;
+  } | null;
+};
+/**
+ * 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. */
+  preview?: string | null;
+  createdAt?: number | null;
+  updatedAt?: number | null;
+  cwd?: string | null; /** Ephemeral threads are never materialized on disk — not resumable. */
+  ephemeral?: boolean;
+  gitInfo?: {
+    branch?: string | null;
+  } | null;
+};
+/** `thread/list` result: one page plus an opaque continuation cursor. */
+type AppServerThreadListResponse = {
+  data?: AppServerThreadSummary[];
+  nextCursor?: string | null;
+};
+type AppServerUserInput = {
+  type: 'text';
+  text: string;
+} | {
+  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). */
+  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. */
+  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;
+  env: Record<string, string | undefined>;
+  dir?: string;
+  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 —
+ *
+ *   node -e 'const d=require("fs").readFileSync(process.argv[1]);
+ *     const s=d.indexOf(`{\n  "models": [`);
+ *     let i=s,n=0; do{n+=(d[i]===123)-(d[i]===125);i++}while(n);
+ *     const c=JSON.parse(d.slice(s,i));
+ *     for(const m of c.models) console.log(m.slug, m.display_name,
+ *       m.visibility, m.supported_reasoning_levels.map(l=>l.effort).join(","))'\
+ *     "$(node -p 'require.resolve("@openai/codex-darwin-arm64/package.json").replace("package.json","vendor/aarch64-apple-darwin/bin/codex")')"
+ *
+ * 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). */
+  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;
+  readonly createdAt: number;
+  constructor(config: CodexRunnerConfig, id?: string);
+  get status(): SessionStatus;
+  get sdkSessionId(): string | undefined;
+  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>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  setModel(model?: string): Promise<void>;
+  fail(message: string): void;
+  close(reason?: 'client' | 'server' | 'error'): void;
+  subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+  /**
+   * 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: {
+    input: Readable;
+    output: Writable;
+  });
+  request(method: string, params?: unknown): Promise<unknown>;
+  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, InputQueue, JsonRpcError, JsonRpcStdioConnection, 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 ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withMcpTools };
 //# sourceMappingURL=index.d.mts.map