@workerdeck/core 0.7.0 → 0.9.0

package/build/index.mjs

@@ -1,12 +1,108 @@
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
-import { getSessionMessages, query } from "@anthropic-ai/claude-agent-sdk";
+import { getSessionMessages, listSessions, query } from "@anthropic-ai/claude-agent-sdk";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION } from "@workerdeck/protocol";
 import { ToolLoopAgent, generateText, isStepCount, tool } from "ai";
-import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { createVfs, runScript } from "@workerdeck/sandbox";
 import { z } from "zod";
 import { lookup } from "node:dns/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+//#region src/attachments.ts
+/** The four the Anthropic API accepts. Notably absent: image/heic — an iPhone's
+* native photo format, which clients must transcode before upload. */
+const IMAGE_TYPES = new Set([
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp"
+]);
+/** Textual types whose media type doesn't start with `text/`. */
+const TEXT_TYPES = new Set([
+	"application/json",
+	"application/xml",
+	"application/yaml",
+	"application/x-yaml",
+	"application/toml",
+	"application/javascript",
+	"application/typescript",
+	"application/x-sh",
+	"application/x-httpd-php",
+	"application/sql"
+]);
+/** Strips any `; charset=…` parameter and lowercases. */
+function normalizeMediaType(mediaType) {
+	return mediaType.split(";")[0].trim().toLowerCase();
+}
+/** How this media type can be sent, or null if it can't be. */
+function attachmentKind(mediaType) {
+	const type = normalizeMediaType(mediaType);
+	if (IMAGE_TYPES.has(type)) return "image";
+	if (type === "application/pdf") return "document";
+	if (type.startsWith("text/") || TEXT_TYPES.has(type)) return "text";
+	return null;
+}
+/** Human-readable list for the 415 an unsupported upload gets. */
+const SUPPORTED_ATTACHMENT_TYPES = [
+	...IMAGE_TYPES,
+	"application/pdf",
+	"text/*"
+].join(", ");
+/**
+* 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.
+*/
+function attachmentContentBlocks(attachments) {
+	return attachments.map((attachment) => {
+		const mediaType = normalizeMediaType(attachment.mediaType);
+		switch (attachmentKind(mediaType)) {
+			case "image": return {
+				type: "image",
+				source: {
+					type: "base64",
+					media_type: mediaType,
+					data: attachment.data
+				}
+			};
+			case "document": return {
+				type: "document",
+				source: {
+					type: "base64",
+					media_type: mediaType,
+					data: attachment.data
+				},
+				title: attachment.name
+			};
+			case "text": return {
+				type: "text",
+				text: `<attachment name="${attachment.name}" type="${mediaType}">\n${decodeText(attachment.data)}\n</attachment>`
+			};
+			default: throw new Error(`unsupported attachment media type: ${attachment.mediaType}`);
+		}
+	});
+}
+/** Strip the bytes: the log-safe half of an attachment. */
+function attachmentRef(attachment) {
+	return {
+		id: attachment.id,
+		name: attachment.name,
+		mediaType: attachment.mediaType,
+		bytes: attachment.bytes
+	};
+}
+function decodeText(base64) {
+	return Buffer.from(base64, "base64").toString("utf8");
+}
+//#endregion
 //#region src/input-queue.ts
 /**
 * Push-based single-consumer AsyncIterable bridging imperative sendMessage() calls
@@ -78,6 +174,171 @@ function toApiMessage(message) {
 	};
 }
 /**
+* Plan rate-limit windows from the CLI's structured `/usage` data, as `rate_limit`
+* events — the same shape a live `rate_limit_event` produces.
+*
+* Without this a client shows no usage at all until a window *changes*, which the
+* CLI only reports after a turn moves the needle, and never for a session that is
+* only being watched. Polling the snapshot and forwarding it through the existing
+* event means replay, the dashboard and the iOS app all get it for free, with no
+* new protocol surface.
+*
+* `status` is not per-window in the usage payload — 'allowed' is what a session
+* the CLI is running for us is, by construction. A window with no utilization is
+* unknown, not zero, and is dropped rather than reported at 0%.
+*/
+function rateLimitEventsFromUsage(usage) {
+	if (!usage.rate_limits_available || !usage.rate_limits) return [];
+	const limits = usage.rate_limits;
+	const events = [];
+	const seen = /* @__PURE__ */ new Set();
+	const push = (rateLimitType, window) => {
+		if (!window || window.utilization === null || seen.has(rateLimitType)) return;
+		seen.add(rateLimitType);
+		const resetsAt = window.resets_at ? Date.parse(window.resets_at) : NaN;
+		events.push({
+			type: "rate_limit",
+			info: {
+				status: "allowed",
+				rateLimitType,
+				utilization: window.utilization,
+				...Number.isFinite(resetsAt) ? { resetsAt: resetsAt / 1e3 } : {}
+			}
+		});
+	};
+	push("five_hour", limits.five_hour);
+	push("seven_day", limits.seven_day);
+	push("seven_day_opus", limits.seven_day_opus);
+	push("seven_day_sonnet", limits.seven_day_sonnet);
+	push("seven_day_oauth_apps", limits.seven_day_oauth_apps);
+	for (const bucket of limits.model_scoped ?? []) {
+		const slug = bucket.display_name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_");
+		if (slug) push(`seven_day_${slug}`, bucket);
+	}
+	return events;
+}
+/**
+* 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.
+*/
+function mcpStatusInfo(status) {
+	const config = status.config;
+	const transport = config?.type ?? (config?.command ? "stdio" : void 0);
+	return {
+		name: status.name,
+		status: status.status,
+		scope: status.scope,
+		error: status.error,
+		serverInfo: status.serverInfo,
+		transport: transport === "stdio" || transport === "http" || transport === "sse" || transport === "sdk" ? transport : void 0,
+		command: config?.command,
+		args: config?.args,
+		url: config?.url,
+		tools: status.tools?.map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			annotations: tool.annotations
+		}))
+	};
+}
+/**
+* The CLI's model list, as `ModelOption[]`.
+*
+* Two decisions live here rather than in each client:
+*
+* - **`default` is dropped.** The CLI offers a row whose id is literally
+*   `default` ("Default (recommended)"), meaning "whatever I would have picked".
+*   It is a legal id to send, but it is not a model: a session running on it
+*   reports a real model, so a picker showing it has a row that can never be
+*   checked, and a status bar naming it would say "Default" for a session
+*   answering as Opus. Which model the default resolved to is a different
+*   question, and `system_init` answers it.
+* - **`primary` is derived.** The CLI reports one flat list; Claude Code's own
+*   picker shows the newest of each family and files the rest under "more
+*   models". The list arrives newest-first, so the first row of each family is
+*   the primary one. A heuristic, but a stable one — and doing it once here
+*   means the dashboard and the phone group identically.
+*/
+/** What the CLI's `default` row resolves to — the model a session will answer as
+* before it has answered anything. Dropped from the list, kept as this. */
+function defaultModelFromSdk(models) {
+	return models.find((model) => model.value === "default")?.resolvedModel;
+}
+function modelOptionsFromSdk(models) {
+	const rows = models.filter((model) => model.value !== "default");
+	const derivedCounts = /* @__PURE__ */ new Map();
+	for (const model of rows) {
+		const derived = friendlyModelName(model.resolvedModel ?? model.value);
+		if (derived) derivedCounts.set(derived, (derivedCounts.get(derived) ?? 0) + 1);
+	}
+	const seenFamilies = /* @__PURE__ */ new Set();
+	return rows.map((model) => {
+		const family = modelFamily(model.resolvedModel ?? model.value);
+		const primary = !seenFamilies.has(family);
+		seenFamilies.add(family);
+		const derived = friendlyModelName(model.resolvedModel ?? model.value);
+		return {
+			value: model.value,
+			resolvedModel: model.resolvedModel,
+			displayName: derived && derivedCounts.get(derived) === 1 ? derived : model.displayName,
+			description: model.description,
+			primary,
+			reasoningEfforts: model.supportedEffortLevels ?? (model.supportsEffort === false ? [] : void 0)
+		};
+	}).map((option, index) => ({
+		option,
+		index
+	})).sort((a, b) => {
+		const rankA = familyRank(a.option);
+		const rankB = familyRank(b.option);
+		return rankA === rankB ? a.index - b.index : rankA - rankB;
+	}).map(({ option }) => option);
+}
+const FAMILY_ORDER = [
+	"fable",
+	"opus",
+	"sonnet",
+	"haiku"
+];
+function familyRank(option) {
+	const rank = FAMILY_ORDER.indexOf(modelFamily(option.resolvedModel ?? option.value));
+	return rank === -1 ? FAMILY_ORDER.length : rank;
+}
+/**
+* The name a person says, from a wire model id: 'claude-opus-5[1m]' → "Opus 5",
+* 'claude-haiku-4-5-20251001' → "Haiku 4.5".
+*
+* The CLI's own `displayName` is the family alone ("Opus", "Haiku") or carries a
+* variant instead of a version ("Opus (1M context)"), and the version is the part
+* that answers "is this the current one". It is only ever in the id, so it is
+* read from there. Returns null when the id has no version to read — a bare
+* alias like 'sonnet' — and the CLI's name stands.
+*/
+function friendlyModelName(id) {
+	const parts = (id.split("[")[0] ?? id).toLowerCase().split("-").filter(Boolean);
+	if (parts[0] === "claude") parts.shift();
+	const family = parts.shift();
+	if (!family) return null;
+	const version = parts.filter((part) => !/^\d{8}$/.test(part));
+	if (version.length === 0 || version.some((part) => !/^\d+$/.test(part))) return null;
+	return `${family.charAt(0).toUpperCase()}${family.slice(1)} ${version.join(".")}`;
+}
+/** 'claude-opus-4-8[1m]' → "opus". The vendor prefix, the context-window suffix
+* and the version tail are all dropped; what is left is the family a person
+* names. Unrecognisable ids become their own family, so a model this rule has
+* never seen lands in the main list rather than being hidden. */
+function modelFamily(id) {
+	const withoutVariant = id.split("[")[0] ?? id;
+	const parts = withoutVariant.toLowerCase().split("-");
+	if (parts[0] === "claude") parts.shift();
+	return parts[0] ?? withoutVariant;
+}
+/**
 * 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).
@@ -139,7 +400,7 @@ function normalizeSdkMessage(msg) {
 }
 //#endregion
 //#region src/runner.ts
-const DEFAULT_APPROVAL_TIMEOUT_MS = 3e5;
+const DEFAULT_APPROVAL_TIMEOUT_MS$1 = 3e5;
 /**
 * 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.
@@ -165,6 +426,9 @@ var SessionRunner = class {
 	#input = new InputQueue();
 	#query;
 	#capabilitiesEmitted = false;
+	/** Last plan reported by the usage poll, so `plan_info` is emitted on change
+	* rather than once per turn. */
+	#subscriptionType;
 	#started = false;
 	#closed = false;
 	#runPromise;
@@ -198,8 +462,10 @@ var SessionRunner = class {
 			cwd: this.#config.cwd,
 			profile: this.#config.profile,
 			engine: "claude",
+			capabilities: ENGINE_CAPABILITIES.claude,
 			model: this.#model ?? this.#config.model,
 			permissionMode: this.#permissionMode,
+			canBypassPermissions: this.#config.permissionMode === "bypassPermissions" || this.#config.allowDangerouslySkipPermissions === true,
 			apiKeySource: this.#apiKeySource,
 			createdAt: this.createdAt,
 			lastSeq: this.#seq,
@@ -226,14 +492,23 @@ var SessionRunner = class {
 		this.#runPromise = this.#run();
 		return this.#runPromise;
 	}
-	/** Queue a user message for the session (starts the next turn when idle). */
-	sendMessage(text) {
+	/** 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, attachments) {
 		if (this.#closed) throw new Error("session is closed");
+		const blocks = attachments?.length ? attachmentContentBlocks(attachments) : [];
+		const content = blocks.length ? [...blocks, ...text ? [{
+			type: "text",
+			text
+		}] : []] : text;
 		this.#input.push({
 			type: "user",
 			message: {
 				role: "user",
-				content: text
+				content
 			},
 			parent_tool_use_id: null,
 			session_id: this.#sdkSessionId
@@ -245,9 +520,28 @@ var SessionRunner = class {
 				content: text
 			},
 			parentToolUseId: null,
+			attachments: attachments?.length ? attachments.map(attachmentRef) : void 0,
 			uuid: randomUUID()
 		});
 	}
+	/** 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. */
+	async mcpServers() {
+		const query = this.#query;
+		if (typeof query?.mcpServerStatus !== "function") return void 0;
+		return (await query.mcpServerStatus()).map(mcpStatusInfo);
+	}
+	async reconnectMcpServer(name) {
+		const query = this.#query;
+		if (typeof query?.reconnectMcpServer !== "function") throw new Error("this session cannot reconnect MCP servers");
+		await query.reconnectMcpServer(name);
+	}
+	async setMcpServerEnabled(name, enabled) {
+		const query = this.#query;
+		if (typeof query?.toggleMcpServer !== "function") throw new Error("this session cannot enable or disable MCP servers");
+		await query.toggleMcpServer(name, enabled);
+	}
 	/** Resolve a pending permission request. Returns false if the id is unknown (e.g. timed out). */
 	resolvePermission(requestId, decision) {
 		const pending = this.#pending.get(requestId);
@@ -323,6 +617,7 @@ var SessionRunner = class {
 				this.#setStatus("idle");
 				this.#fetchCapabilities();
 				this.#fetchContextUsage();
+				this.#fetchRateLimits();
 			}
 			for await (const message of this.#query) this.#handleMessage(message);
 			if (!this.#closed) {
@@ -393,6 +688,7 @@ var SessionRunner = class {
 			maxBudgetUsd: c.maxBudgetUsd,
 			resume: c.resume,
 			forkSession: c.forkSession,
+			effort: c.reasoningEffort,
 			includePartialMessages: c.includePartialMessages ?? true,
 			canUseTool: this.#canUseTool,
 			env: c.env,
@@ -423,6 +719,7 @@ var SessionRunner = class {
 			this.#setStatus("running");
 			this.#fetchCapabilities();
 			this.#fetchContextUsage();
+			this.#fetchRateLimits();
 			return;
 		}
 		if (msg.type === "system" && msg.subtype === "session_state_changed") {
@@ -439,6 +736,7 @@ var SessionRunner = class {
 				this.#numTurns = body.numTurns;
 				if (this.#pending.size === 0) this.#setStatus("idle");
 				this.#fetchContextUsage();
+				this.#fetchRateLimits();
 			}
 		}
 	}
@@ -457,11 +755,8 @@ var SessionRunner = class {
 			this.#capabilitiesEmitted = true;
 			this.#emit({
 				type: "capabilities",
-				models: models.map((m) => ({
-					value: m.value,
-					displayName: m.displayName,
-					description: m.description
-				})),
+				models: modelOptionsFromSdk(models),
+				defaultModel: defaultModelFromSdk(models),
 				commands: commands.map((c) => ({
 					name: c.name,
 					description: c.description,
@@ -495,9 +790,38 @@ var SessionRunner = class {
 			});
 		} catch {}
 	}
+	/**
+	* Snapshot the plan's rate-limit windows and surface them as `rate_limit`
+	* events — the same event a live `rate_limit_event` produces, so clients need
+	* nothing new to render it.
+	*
+	* The CLI only *pushes* a window when it changes, which for a session being
+	* watched rather than driven can be never; polling is what makes usage show up
+	* at all. The control request is marked experimental in the SDK, name included,
+	* so it is probed for by name and every failure is silent — one more reason
+	* this can only ever be decoration.
+	*/
+	async #fetchRateLimits() {
+		const query = this.#query;
+		const fetchUsage = query?.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET;
+		if (typeof fetchUsage !== "function") return;
+		try {
+			const usage = await fetchUsage.call(query);
+			if (this.#closed) return;
+			const subscriptionType = usage.subscription_type;
+			if (subscriptionType && subscriptionType !== this.#subscriptionType) {
+				this.#subscriptionType = subscriptionType;
+				this.#emit({
+					type: "plan_info",
+					subscriptionType
+				});
+			}
+			for (const body of rateLimitEventsFromUsage(usage)) this.#emit(body);
+		} catch {}
+	}
 	#canUseTool = (toolName, input, options) => {
 		const id = randomUUID();
-		const timeoutMs = this.#config.approvalTimeoutMs ?? this.#config.defaultApprovalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+		const timeoutMs = this.#config.approvalTimeoutMs ?? this.#config.defaultApprovalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS$1;
 		const request = {
 			id,
 			toolName,
@@ -762,6 +1086,7 @@ var AiSdkRunner = class {
 			cwd: this.#config.cwd ?? process.cwd(),
 			profile: this.#config.profile,
 			engine: "provider",
+			capabilities: ENGINE_CAPABILITIES.provider,
 			model: this.#modelId(),
 			permissionMode: this.#permissionMode,
 			createdAt: this.createdAt,
@@ -828,12 +1153,21 @@ var AiSdkRunner = class {
 		} catch {}
 		return snapshot;
 	}
-	sendMessage(text) {
+	sendMessage(text, attachments) {
 		if (this.#parked) throw new Error("session is parked");
 		if (this.#closed) throw new Error("session is closed");
+		const content = attachments?.length ? [...attachments.map((attachment) => ({
+			type: "file",
+			data: attachment.data,
+			mediaType: normalizeMediaType(attachment.mediaType),
+			filename: attachment.name
+		})), ...text ? [{
+			type: "text",
+			text
+		}] : []] : text;
 		this.#messages.push({
 			role: "user",
-			content: text
+			content
 		});
 		this.#emit({
 			type: "user_message",
@@ -842,6 +1176,7 @@ var AiSdkRunner = class {
 				content: text
 			},
 			parentToolUseId: null,
+			attachments: attachments?.length ? attachments.map(attachmentRef) : void 0,
 			uuid: randomUUID()
 		});
 		this.#scheduleTurn();
@@ -2319,6 +2654,1963 @@ function toTransport(server) {
 	};
 }
 //#endregion
-export { AiSdkRunner, BrowserBridgeExecutor, DeferredExecutor, InputQueue, PendingRequestRegistry, QuickJsExecutor, SessionRunner, checkClaudeAuth, connectMcpTools, createEngineSession, createToolContext, createWebFetch, htmlToMarkdown, isHostAllowed, isPrivateAddress, normalizeSdkMessage, resolveBundledClaudeExecutable, toApiMessage, toExecutionResult, withMcpTools };
+//#region src/engines/claude/catalog.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.
+*/
+const CLAUDE_CATALOG = {
+	provenance: "supportedModels() of @anthropic-ai/claude-agent-sdk 0.3.221 (Claude Code CLI), extracted 2026-08-05; older-model rows hand-maintained",
+	models: [
+		{
+			value: "claude-fable-5[1m]",
+			resolvedModel: "claude-fable-5",
+			displayName: "Fable 5",
+			description: "Fable 5 · Most capable for your hardest and longest-running tasks",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max"
+			]
+		},
+		{
+			value: "opus[1m]",
+			resolvedModel: "claude-opus-5[1m]",
+			displayName: "Opus 5",
+			description: "Opus 5 with 1M context · Best for everyday, complex tasks",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max"
+			]
+		},
+		{
+			value: "claude-opus-4-8",
+			resolvedModel: "claude-opus-4-8",
+			displayName: "Opus 4.8",
+			description: "Opus 4.8 · Previous Opus generation"
+		},
+		{
+			value: "sonnet",
+			resolvedModel: "claude-sonnet-5",
+			displayName: "Sonnet 5",
+			description: "Sonnet 5 · Efficient for routine tasks",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max"
+			]
+		},
+		{
+			value: "claude-sonnet-4-6",
+			resolvedModel: "claude-sonnet-4-6",
+			displayName: "Sonnet 4.6",
+			description: "Sonnet 4.6 · Previous Sonnet generation"
+		},
+		{
+			value: "haiku",
+			resolvedModel: "claude-haiku-4-5-20251001",
+			displayName: "Haiku 4.5",
+			description: "Haiku 4.5 · Fastest for quick answers",
+			primary: true,
+			reasoningEfforts: []
+		}
+	]
+};
+//#endregion
+//#region src/engines/claude/adapter.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.
+*/
+const claudeAdapter = {
+	engine: "claude",
+	capabilities: ENGINE_CAPABILITIES.claude,
+	catalog: CLAUDE_CATALOG,
+	async checkAvailability(profile, env) {
+		const status = await checkClaudeAuth(env);
+		if (status === "logged_in") return { available: true };
+		if (status === "logged_out") return {
+			available: false,
+			reason: `no usable Claude credentials for this profile's environment — log in under its config dir (CLAUDE_CONFIG_DIR=${profile.configDir ?? "~/.claude"} claude auth login) or set ANTHROPIC_API_KEY`
+		};
+		return { available: "unknown" };
+	},
+	createRunner({ config, restore }) {
+		if (restore) throw new Error("the Claude engine cannot rebuild a parked session");
+		return new SessionRunner(config);
+	},
+	/**
+	* The Agent SDK's on-disk session store, mapped browser-safe. The SDK reads
+	* the store of the *process* environment — it takes no config dir — so a
+	* profile pin cannot narrow this listing; that matches the route's
+	* pre-adapter behavior exactly (the listing was always process-global).
+	*/
+	async listSessions({ dir, limit, offset }) {
+		return (await listSessions({
+			dir,
+			limit,
+			offset
+		})).map((s) => ({
+			sessionId: s.sessionId,
+			summary: s.summary,
+			lastModified: s.lastModified,
+			createdAt: s.createdAt,
+			customTitle: s.customTitle,
+			firstPrompt: s.firstPrompt,
+			gitBranch: s.gitBranch,
+			cwd: s.cwd
+		}));
+	}
+};
+//#endregion
+//#region src/engines/codex/jsonrpc.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).
+*/
+var JsonRpcError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "JsonRpcError";
+		this.code = code;
+	}
+};
+/**
+* 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.
+*/
+var JsonRpcStdioConnection = class {
+	#output;
+	#nextId = 1;
+	#pending = /* @__PURE__ */ new Map();
+	#buffer = "";
+	#closed = false;
+	#notificationHandler;
+	#requestHandler;
+	constructor(options) {
+		this.#output = options.output;
+		options.input.on("data", (chunk) => this.#feed(String(chunk)));
+		options.input.on("error", () => {});
+		options.output.on("error", () => {});
+	}
+	request(method, params) {
+		if (this.#closed) return Promise.reject(/* @__PURE__ */ new Error(`codex app-server is closed (${method})`));
+		const id = this.#nextId++;
+		return new Promise((resolve, reject) => {
+			this.#pending.set(id, {
+				method,
+				resolve,
+				reject
+			});
+			this.#write({
+				id,
+				method,
+				...params === void 0 ? {} : { params }
+			});
+		});
+	}
+	notify(method, params) {
+		if (this.#closed) return;
+		this.#write({
+			method,
+			...params === void 0 ? {} : { params }
+		});
+	}
+	onNotification(handler) {
+		this.#notificationHandler = handler;
+	}
+	onRequest(handler) {
+		this.#requestHandler = handler;
+	}
+	/** Reject everything in flight and refuse new traffic — the child is gone
+	* (or the session is over). Idempotent. */
+	fail(message) {
+		if (this.#closed) return;
+		this.#closed = true;
+		const pending = [...this.#pending.values()];
+		this.#pending.clear();
+		for (const entry of pending) entry.reject(/* @__PURE__ */ new Error(`${message} (awaiting ${entry.method})`));
+	}
+	#write(payload) {
+		try {
+			this.#output.write(JSON.stringify(payload) + "\n");
+		} catch {}
+	}
+	#feed(chunk) {
+		this.#buffer += chunk;
+		let newline;
+		while ((newline = this.#buffer.indexOf("\n")) >= 0) {
+			const line = this.#buffer.slice(0, newline).trim();
+			this.#buffer = this.#buffer.slice(newline + 1);
+			if (!line) continue;
+			let message;
+			try {
+				message = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			this.#dispatch(message);
+		}
+	}
+	#dispatch(message) {
+		const { id, method } = message;
+		if (typeof method === "string") {
+			if (id === void 0 || id === null) {
+				this.#notificationHandler?.(method, message.params);
+				return;
+			}
+			const respond = (payload) => this.#write({
+				id,
+				...payload
+			});
+			const handler = this.#requestHandler;
+			if (!handler) {
+				respond({ error: {
+					code: -32601,
+					message: `no handler for server request '${method}'`
+				} });
+				return;
+			}
+			handler(method, message.params, id).then((result) => respond({ result: result ?? {} }), (error) => respond({ error: {
+				code: error instanceof JsonRpcError ? error.code : -32603,
+				message: error instanceof Error ? error.message : String(error)
+			} }));
+			return;
+		}
+		if (id === void 0 || id === null) return;
+		const pending = this.#pending.get(id);
+		if (!pending) return;
+		this.#pending.delete(id);
+		if (message.error !== void 0 && message.error !== null) {
+			const error = message.error;
+			pending.reject(new JsonRpcError(error.code ?? -32603, error.message ?? `request '${pending.method}' failed`));
+			return;
+		}
+		pending.resolve(message.result);
+	}
+};
+//#endregion
+//#region src/engines/codex/runner.ts
+/**
+* thread/start's sandbox axis (string form) — our permission modes as codex
+* sandbox modes: `default` → read-only (reads run; any mutation is refused by
+* the OS sandbox and — with the ask policy below — escalates to a real
+* question), `acceptEdits` → workspace-write (in-workspace writes sail
+* through, the acceptEdits grant), `bypassPermissions` → danger-full-access.
+*/
+const THREAD_SANDBOX_BY_MODE = {
+	default: "read-only",
+	acceptEdits: "workspace-write",
+	bypassPermissions: "danger-full-access"
+};
+/** turn/start's sandboxPolicy axis (object form — same policy, second shape). */
+const TURN_SANDBOX_BY_MODE = {
+	default: { type: "readOnly" },
+	acceptEdits: { type: "workspaceWrite" },
+	bypassPermissions: { type: "dangerFullAccess" }
+};
+/**
+* The approval axis, stated as the GRANULAR object on both thread/start and
+* turn/start — never the string vocabulary, deliberately and unconditionally:
+* measured against 0.146.0, plain `'untrusted'` never asked anything (a
+* sandbox-violating write was silently refused, a safe echo auto-approved),
+* while the granular flags make a blocked action a real server→client
+* question. Granular policies are gated on `capabilities.experimentalApi` at
+* initialize; WorkerDeck declares it always and keeps NO non-experimental
+* fallback — a future binary that rejects either gate fails loudly (see
+* {@link CodexRunner.#ensureThread}) instead of quietly not asking.
+*
+* `default`/`acceptEdits` ask (all flags on — the sandbox axis above already
+* decides *what needs asking*); `bypassPermissions` asks nothing, same shape.
+*/
+const GRANULAR_ASK = { granular: {
+	sandbox_approval: true,
+	rules: true,
+	mcp_elicitations: true,
+	request_permissions: true,
+	skill_approval: true
+} };
+const APPROVAL_POLICY_BY_MODE = {
+	default: GRANULAR_ASK,
+	acceptEdits: GRANULAR_ASK,
+	bypassPermissions: { granular: {
+		sandbox_approval: false,
+		rules: false,
+		mcp_elicitations: false,
+		request_permissions: false,
+		skill_approval: false
+	} }
+};
+/** Fallback timeout for a pending approval nobody answers — the SessionRunner
+* default, so unattended codex sessions land the same way Claude ones do. */
+const DEFAULT_APPROVAL_TIMEOUT_MS = 3e5;
+/**
+* The experimental per-request decision list, normalized to names: a string
+* entry is its own name, a structured entry (`{acceptWithExecpolicyAmendment:
+* …}`) is named by its key. Undefined = the request stated no list and the
+* channel's schema enum applies. Present only under `experimentalApi: true` —
+* which WorkerDeck always declares.
+*/
+function offeredDecisions(params) {
+	const raw = params?.availableDecisions;
+	if (!Array.isArray(raw)) return void 0;
+	const names = /* @__PURE__ */ new Set();
+	for (const entry of raw) if (typeof entry === "string") names.add(entry);
+	else if (entry && typeof entry === "object") for (const key of Object.keys(entry)) names.add(key);
+	return names.size > 0 ? names : void 0;
+}
+/**
+* Decision picking for the `{decision: …}` channels (commandExecution,
+* fileChange), honoring the request's own `availableDecisions`:
+*
+* - allow → 'accept' when offered (or when no list was stated). A request
+*   offering only the broader accepts ('acceptForSession',
+*   'acceptWithExecpolicyAmendment') yields undefined: a one-shot allow must
+*   not be silently widened into a session-wide or persistent policy grant, so
+*   the caller answers with the denial and says why.
+* - deny → 'decline', always: the response schema declares it unconditionally,
+*   and it was verified live against 0.146.0 answering a request whose
+*   availableDecisions omitted it — the turn completed cleanly. The list's job
+*   is to gate the accept variants, not to take "no, but keep going" away
+*   (its own alternative, 'cancel', would interrupt the whole turn).
+* - deny+interrupt → 'cancel' (codex's deny-and-interrupt) when offered;
+*   otherwise 'decline', and the caller interrupts the turn itself.
+*/
+function pickDecision(behavior, interrupt, offered) {
+	const has = (name) => !offered || offered.has(name);
+	if (behavior === "allow") return has("accept") ? "accept" : void 0;
+	if (interrupt && has("cancel")) return "cancel";
+	return "decline";
+}
+/** Codex `requestUserInput` questions in the AskUserQuestion wire shape both
+* clients already render (QuestionPrompt / QuestionPromptView). */
+function userQuestionsFromCodex(questions) {
+	return questions.map((question) => ({
+		question: question.question,
+		header: question.header ?? "",
+		options: (question.options ?? []).map((option) => ({
+			label: option.label,
+			description: option.description
+		}))
+	}));
+}
+/** The text of a history `userMessage` item: its content entries' text parts
+* joined. Image parts have no replayable representation (the bytes went to the
+* model, not into the rollout we can render from) and are skipped. */
+function historyUserText(item) {
+	if (!Array.isArray(item.content)) return "";
+	return item.content.map((part) => {
+		const candidate = part;
+		return candidate?.type === "text" && typeof candidate.text === "string" ? candidate.text : "";
+	}).filter(Boolean).join("\n");
+}
+/** The AskUserQuestion answer convention (question text → chosen label(s),
+* comma-joined) mapped back to codex's id-keyed shape. Questions the client
+* did not answer are absent, not empty. */
+function codexAnswers(questions, answers) {
+	const out = {};
+	for (const question of questions) {
+		const value = answers?.[question.question] ?? answers?.[question.id];
+		if (typeof value === "string" && value.length > 0) out[question.id] = { answers: [value] };
+	}
+	return out;
+}
+/** The two channels whose response is `{decision: …}` share their pick logic. */
+function decisionChannel(describe, itemId) {
+	return {
+		describe,
+		itemId,
+		allow: (_params, _updatedInput, offered) => {
+			const decision = pickDecision("allow", false, offered);
+			return decision ? {
+				response: { decision },
+				decision
+			} : void 0;
+		},
+		deny: (_params, interrupt, offered) => {
+			const decision = pickDecision("deny", interrupt, offered);
+			return {
+				response: { decision },
+				decision
+			};
+		}
+	};
+}
+/**
+* The ask channels, wired to the permission surface. Anything not listed here
+* still gets a JSON-RPC -32601 — never a hang (an unanswered server request
+* wedges the turn).
+*/
+const APPROVAL_CHANNELS = {
+	"item/commandExecution/requestApproval": decisionChannel((raw) => {
+		const params = raw;
+		const command = params.command ?? void 0;
+		return {
+			toolName: "CodexCommand",
+			input: {
+				...command !== void 0 ? { command } : {},
+				...params.cwd ? { cwd: params.cwd } : {},
+				...params.reason ? { reason: params.reason } : {}
+			},
+			title: params.reason ?? (command ? `Codex wants to run: ${command}` : "Codex wants to run a command"),
+			displayName: "Run command",
+			description: params.reason && command ? command : params.cwd ?? void 0,
+			decisionReason: params.reason ?? void 0
+		};
+	}, (raw) => raw.itemId),
+	"item/fileChange/requestApproval": decisionChannel((raw) => {
+		const params = raw;
+		return {
+			toolName: "CodexFileChange",
+			input: {
+				...params.grantRoot ? { grantRoot: params.grantRoot } : {},
+				...params.reason ? { reason: params.reason } : {}
+			},
+			title: params.reason ?? "Codex wants to apply file changes",
+			displayName: "Apply file changes",
+			description: params.grantRoot ? `write access under ${params.grantRoot}` : void 0,
+			decisionReason: params.reason ?? void 0
+		};
+	}, (raw) => raw.itemId),
+	"item/permissions/requestApproval": {
+		describe: (raw) => {
+			const params = raw;
+			return {
+				toolName: "CodexPermissions",
+				input: {
+					...params.permissions ? { permissions: params.permissions } : {},
+					...params.cwd ? { cwd: params.cwd } : {},
+					...params.reason ? { reason: params.reason } : {}
+				},
+				title: params.reason ?? "Codex requests additional permissions",
+				displayName: "Grant permissions",
+				description: void 0,
+				decisionReason: params.reason ?? void 0
+			};
+		},
+		itemId: (raw) => raw.itemId,
+		allow: (raw, updatedInput) => ({ response: { permissions: updatedInput?.permissions ?? raw.permissions ?? {} } }),
+		deny: () => ({ response: { permissions: {} } })
+	},
+	"item/tool/requestUserInput": {
+		describe: (raw) => ({
+			toolName: "AskUserQuestion",
+			input: { questions: userQuestionsFromCodex(raw.questions ?? []) },
+			title: "Codex asks a question",
+			displayName: "Answer questions",
+			description: void 0,
+			decisionReason: void 0
+		}),
+		itemId: (raw) => raw.itemId,
+		allow: (raw, updatedInput) => ({ response: { answers: codexAnswers(raw.questions ?? [], updatedInput?.answers) } }),
+		deny: () => ({ response: { answers: {} } })
+	},
+	"mcpServer/elicitation/request": {
+		describe: (raw) => {
+			const params = raw;
+			return {
+				toolName: "CodexMcpElicitation",
+				input: {
+					...params.serverName ? { serverName: params.serverName } : {},
+					...params.message ? { message: params.message } : {},
+					...params.mode ? { mode: params.mode } : {},
+					...params.requestedSchema !== void 0 ? { requestedSchema: params.requestedSchema } : {},
+					...params.url ? { url: params.url } : {}
+				},
+				title: params.serverName ? `MCP server '${params.serverName}' requests input` : "An MCP server requests input",
+				displayName: "MCP elicitation",
+				description: params.message ?? void 0,
+				decisionReason: void 0
+			};
+		},
+		itemId: () => void 0,
+		allow: (_raw, updatedInput) => ({ response: {
+			action: "accept",
+			...updatedInput !== void 0 ? { content: updatedInput } : {}
+		} }),
+		deny: (_raw, interrupt) => ({ response: { action: interrupt ? "cancel" : "decline" } })
+	}
+};
+/**
+* Name a subscription window by its measured length, so codex's positional
+* windows land in the protocol's named vocabulary. The two names clients
+* already understand are exact matches for codex's durations (300 min = 5h,
+* 10080 min = 7d); anything else keeps a self-describing key rather than
+* borrowing a name that would size it wrongly.
+*/
+function rateLimitWindowName(minutes) {
+	if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0) return void 0;
+	if (minutes === 300) return "five_hour";
+	if (minutes === 10080) return "seven_day";
+	return `window_${minutes}m`;
+}
+/**
+* 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.
+*/
+var CodexRunner = class {
+	id;
+	createdAt;
+	#config;
+	#events = [];
+	#listeners = /* @__PURE__ */ new Set();
+	#seq = 0;
+	#status = "starting";
+	#sdkSessionId;
+	#model;
+	#permissionMode;
+	#reasoningEffort;
+	/** What the binary said the profile's defaults resolve to (thread/start
+	* response) — lets `setModel(undefined)` mean "back to the default" even
+	* though a turn/start override persists for subsequent turns. */
+	#resolvedModel;
+	/** Last reported ChatGPT plan, so `plan_info` is emitted once per change. */
+	#planType;
+	#resolvedEffort;
+	#queue = [];
+	#turnChain = Promise.resolve();
+	#activeTurn;
+	#connection;
+	#threadLoaded = false;
+	#numTurns = 0;
+	#totalCostUsd;
+	#lastActivityAt;
+	#started = false;
+	#closed = false;
+	/** Session temp dir for image attachments (`localImage` takes host paths). */
+	#imageDir;
+	/** Pending server→client approvals, keyed by the surfaced request id. */
+	#approvals = /* @__PURE__ */ new Map();
+	/** True from start() until the resume backfill (the turn chain's first link)
+	* settles — while set, sendMessage defers its user_message echo behind the
+	* chain so a new turn can never precede or interleave the replayed history. */
+	#backfillPending = false;
+	/** The resumed thread's prior turns, stashed by {@link #ensureThread} from
+	* the ONE thread/resume the backfill consumes (`partial` = the response's
+	* turnsBackwardsCursor said older turns exist beyond this page). A mid-life
+	* reconnect also goes through thread/resume, but with no backfill pending
+	* nothing is stashed — history is never replayed twice. */
+	#resumedHistory;
+	/** Set around history replay: {@link #emit} stamps `replay: true` onto the
+	* message events the live item mapping produces. */
+	#replayingHistory = false;
+	constructor(config, id = randomUUID()) {
+		const mode = config.permissionMode ?? "default";
+		if (!ENGINE_CAPABILITIES.codex.permissionModes.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the codex engine`);
+		if (config.forkSession) throw new Error("the codex engine cannot fork a resumed thread");
+		this.#config = config;
+		this.#permissionMode = mode;
+		this.#model = config.model;
+		this.#reasoningEffort = config.reasoningEffort;
+		this.#sdkSessionId = config.resume;
+		this.id = id;
+		this.createdAt = Date.now();
+	}
+	/** The complete child environment — spawn env replaces process.env wholesale,
+	* so this must carry everything a shell would, with the profile's CODEX_HOME
+	* pin winning over operator env. */
+	#childEnv() {
+		const base = this.#config.env ?? process.env;
+		const env = {};
+		for (const [key, value] of Object.entries(base)) if (value !== void 0) env[key] = value;
+		if (this.#config.codexHome) env.CODEX_HOME = this.#config.codexHome;
+		return env;
+	}
+	get status() {
+		return this.#status;
+	}
+	get sdkSessionId() {
+		return this.#sdkSessionId;
+	}
+	get lastSeq() {
+		return this.#seq;
+	}
+	get pendingApprovals() {
+		return [...this.#approvals.values()].map((pending) => pending.request);
+	}
+	info() {
+		return {
+			id: this.id,
+			sdkSessionId: this.#sdkSessionId,
+			status: this.#status,
+			cwd: this.#config.cwd,
+			profile: this.#config.profile,
+			engine: "codex",
+			capabilities: ENGINE_CAPABILITIES.codex,
+			model: this.#model ?? this.#resolvedModel,
+			permissionMode: this.#permissionMode,
+			canBypassPermissions: true,
+			createdAt: this.createdAt,
+			lastSeq: this.#seq,
+			pendingPermissionCount: this.#approvals.size,
+			meta: this.#config.meta,
+			title: this.#title(),
+			totalCostUsd: this.#totalCostUsd,
+			numTurns: this.#numTurns || void 0,
+			lastActivityAt: this.#lastActivityAt
+		};
+	}
+	#title() {
+		const metaTitle = this.#config.meta?.title;
+		if (typeof metaTitle === "string" && metaTitle.length > 0) return metaTitle;
+		const prompt = this.#config.prompt;
+		if (!prompt) return void 0;
+		return prompt.length > 80 ? prompt.slice(0, 77) + "…" : prompt;
+	}
+	start() {
+		if (this.#started) return this.#turnChain;
+		this.#started = true;
+		if (this.#config.resume && this.#config.backfillHistory !== false) {
+			this.#backfillPending = true;
+			this.#turnChain = this.#turnChain.then(() => this.#backfillHistory());
+		} else this.#setStatus("idle");
+		if (this.#config.prompt) this.sendMessage(this.#config.prompt);
+		return this.#turnChain;
+	}
+	sendMessage(text, attachments) {
+		if (this.#closed) throw new Error("session is closed");
+		const input = this.#buildInput(text, attachments ?? []);
+		const echo = () => this.#emit({
+			type: "user_message",
+			message: {
+				role: "user",
+				content: text
+			},
+			parentToolUseId: null,
+			attachments: attachments?.length ? attachments.map(attachmentRef) : void 0,
+			uuid: randomUUID()
+		});
+		if (this.#backfillPending) this.#turnChain = this.#turnChain.then(echo);
+		else echo();
+		this.#queue.push({ input });
+		this.#scheduleTurn();
+	}
+	/**
+	* App-server input for a message with attachments: images land in a session
+	* temp dir and travel as `localImage` host paths, text files inline into the
+	* prompt in the shared named envelope, PDF has no representation (the
+	* gateway's 415 normally refuses it first).
+	*/
+	#buildInput(text, attachments) {
+		const parts = [];
+		for (const attachment of attachments) {
+			const mediaType = normalizeMediaType(attachment.mediaType);
+			switch (attachmentKind(mediaType)) {
+				case "image": {
+					this.#imageDir ??= join(tmpdir(), `workerdeck-codex-${this.id}`);
+					mkdirSync(this.#imageDir, { recursive: true });
+					const ext = mediaType.split("/")[1] ?? "bin";
+					const path = join(this.#imageDir, `${attachment.id}.${ext}`);
+					writeFileSync(path, Buffer.from(attachment.data, "base64"));
+					parts.push({
+						type: "localImage",
+						path
+					});
+					break;
+				}
+				case "text":
+					parts.push({
+						type: "text",
+						text: `<attachment name="${attachment.name}" type="${mediaType}">\n${Buffer.from(attachment.data, "base64").toString("utf8")}\n</attachment>`
+					});
+					break;
+				default: throw new Error(`unsupported attachment media type for the codex engine: ${attachment.mediaType}`);
+			}
+		}
+		if (text) parts.push({
+			type: "text",
+			text
+		});
+		return parts;
+	}
+	/** Resolve a pending approval. Returns false if the id is unknown (e.g.
+	* timed out, or already settled by codex itself). */
+	resolvePermission(requestId, decision) {
+		const pending = this.#approvals.get(requestId);
+		if (!pending) return false;
+		this.#settleApproval(requestId, pending, decision, "client");
+		return true;
+	}
+	async interrupt() {
+		for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
+			behavior: "deny",
+			message: "interrupted",
+			interrupt: true
+		}, "policy");
+		await this.#interruptTurn();
+		await this.#turnChain;
+	}
+	/** Address the in-flight turn only (no approval sweep) — also the follow-up
+	* for a deny+interrupt whose wire decision couldn't carry the interrupt. */
+	async #interruptTurn() {
+		const active = this.#activeTurn;
+		const connection = this.#connection;
+		if (active && !active.settled) {
+			active.interrupted = true;
+			if (connection && active.turnId && this.#sdkSessionId) try {
+				await connection.request("turn/interrupt", {
+					threadId: this.#sdkSessionId,
+					turnId: active.turnId
+				});
+			} catch {}
+			else if (connection) {
+				connection.close();
+				if (this.#connection === connection) this.#connection = void 0;
+				active.reject(/* @__PURE__ */ new Error("interrupted"));
+			}
+		}
+	}
+	async setPermissionMode(mode) {
+		if (!ENGINE_CAPABILITIES.codex.permissionModes.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the codex engine`);
+		if (this.#activeTurn) throw new Error("cannot change the permission mode mid-turn (the running turn's sandbox is fixed)");
+		this.#permissionMode = mode;
+		this.#emit({
+			type: "permission_mode_changed",
+			mode
+		});
+	}
+	async setModel(model) {
+		if (this.#activeTurn) throw new Error("cannot change the model mid-turn (the running turn's model is fixed)");
+		this.#model = model;
+		this.#emit({
+			type: "model_changed",
+			model
+		});
+	}
+	fail(message) {
+		if (this.#closed) return;
+		this.#emit({
+			type: "session_error",
+			message
+		});
+		this.#setStatus("failed");
+		this.close("error");
+	}
+	close(reason = "client") {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#queue.length = 0;
+		for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
+			behavior: "deny",
+			message: "Session closed"
+		}, "policy");
+		this.#connection?.close();
+		this.#connection = void 0;
+		this.#activeTurn?.reject(/* @__PURE__ */ new Error("session closed"));
+		if (this.#imageDir) try {
+			rmSync(this.#imageDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		this.#emit({
+			type: "session_closed",
+			reason
+		});
+		this.#setStatus("closed");
+	}
+	subscribe(listener, afterSeq = 0) {
+		for (const event of this.#events) if (event.seq > afterSeq) listener(event);
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+	#scheduleTurn() {
+		this.#turnChain = this.#turnChain.then(() => this.#runTurn());
+	}
+	/**
+	* The session's live connection with its thread loaded, (re)building both as
+	* needed: spawn + `initialize`/`initialized` on a fresh child, then
+	* `thread/start` (new) or `thread/resume` (a create-request `resume`, or a
+	* thread orphaned by a dead child). The response's resolved model/effort are
+	* kept so per-turn overrides can name "the profile default" explicitly.
+	*/
+	async #ensureThread() {
+		if (this.#closed) throw new Error("session is closed");
+		let connection = this.#connection;
+		if (!connection) {
+			connection = this.#config.connectFn({ env: this.#childEnv() });
+			this.#connection = connection;
+			this.#threadLoaded = false;
+			connection.onNotification((method, params) => this.#handleNotification(method, params));
+			connection.onRequest((method, params, id) => this.#answerServerRequest(method, params, id));
+			connection.onClose((message) => {
+				if (this.#connection === connection) {
+					this.#connection = void 0;
+					this.#threadLoaded = false;
+				}
+				for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
+					behavior: "deny",
+					message
+				}, "policy");
+				this.#activeTurn?.reject(new Error(message));
+			});
+			try {
+				await connection.request("initialize", {
+					clientInfo: {
+						name: "workerdeck",
+						title: "WorkerDeck",
+						version: `protocol-${PROTOCOL_VERSION}`
+					},
+					capabilities: { experimentalApi: true }
+				});
+			} catch (error) {
+				connection.close();
+				if (this.#connection === connection) this.#connection = void 0;
+				if (error instanceof JsonRpcError) throw new Error("codex app-server rejected initialize (capabilities.experimentalApi: true — required for the granular approval policy, and WorkerDeck has no non-experimental fallback): " + error.message);
+				throw error;
+			}
+			connection.notify("initialized");
+		}
+		if (!this.#threadLoaded) {
+			const options = {
+				cwd: this.#config.cwd,
+				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
+				sandbox: THREAD_SANDBOX_BY_MODE[this.#permissionMode]
+			};
+			if (this.#model) options.model = this.#model;
+			const resuming = this.#sdkSessionId !== void 0;
+			const result = resuming ? await connection.request("thread/resume", {
+				threadId: this.#sdkSessionId,
+				...options
+			}) : await connection.request("thread/start", options);
+			if (typeof result?.thread?.id === "string") this.#sdkSessionId = result.thread.id;
+			if (typeof result?.model === "string") this.#resolvedModel = result.model;
+			if (typeof result?.reasoningEffort === "string") this.#resolvedEffort = result.reasoningEffort;
+			if (resuming && this.#backfillPending && !this.#resumedHistory) this.#resumedHistory = {
+				turns: Array.isArray(result?.thread?.turns) ? result.thread.turns : [],
+				partial: typeof result?.turnsBackwardsCursor === "string"
+			};
+			this.#threadLoaded = true;
+		}
+		return connection;
+	}
+	/**
+	* On resume, replay the thread's prior turns as `replay: true` events,
+	* seq'd before any live turn — the SessionRunner backfill contract, fed
+	* from `thread/resume`'s own `thread.turns`. When the resume response says
+	* that page is partial (`turnsBackwardsCursor`), the FULL rollout history
+	* is fetched via `thread/read {includeTurns: true}` instead — and if even
+	* that fails, the partial page is replayed under a visible notice rather
+	* than silently posing as the whole thread. Best-effort like the Claude
+	* backfill: an unreadable history never blocks the resume itself.
+	*/
+	async #backfillHistory() {
+		try {
+			if (this.#closed) return;
+			const connection = await this.#ensureThread();
+			const resumed = this.#resumedHistory;
+			this.#resumedHistory = void 0;
+			let turns = resumed?.turns ?? [];
+			let partialReason;
+			if (resumed?.partial) try {
+				const full = (await connection.request("thread/read", {
+					threadId: this.#sdkSessionId,
+					includeTurns: true
+				}))?.thread?.turns;
+				if (Array.isArray(full) && full.length >= turns.length) turns = full;
+				else partialReason = "thread/read returned less history than the resume page";
+			} catch (error) {
+				partialReason = error instanceof Error ? error.message : String(error);
+			}
+			if (partialReason) this.#emit({
+				type: "session_error",
+				message: `Resumed thread history is incomplete — older turns could not be loaded (${partialReason})`
+			});
+			this.#replayTurns(turns);
+		} catch {} finally {
+			this.#backfillPending = false;
+			this.#setStatus("idle");
+		}
+	}
+	/** Replay historical turns through the SAME item mapping the live path uses. */
+	#replayTurns(turns) {
+		for (const turn of turns) {
+			if (this.#closed) return;
+			const state = this.#newTurnState();
+			this.#replayingHistory = true;
+			try {
+				for (const item of turn.items ?? []) {
+					if (item.type === "userMessage") {
+						const text = historyUserText(item);
+						if (!text) continue;
+						this.#emit({
+							type: "user_message",
+							message: {
+								role: "user",
+								content: text
+							},
+							parentToolUseId: null,
+							uuid: `${state.nonce}:${item.id}`
+						});
+						continue;
+					}
+					this.#handleItemCompleted(item, state);
+				}
+			} finally {
+				this.#replayingHistory = false;
+			}
+		}
+	}
+	/** Fresh per-turn state — one per live turn, and one per REPLAYED turn (the
+	* nonce is the item-id namespace, and its per-turn-ness is the invariant). */
+	#newTurnState() {
+		return {
+			nonce: randomUUID(),
+			interrupted: false,
+			usage: {
+				inputTokens: 0,
+				cachedInputTokens: 0,
+				cacheWriteInputTokens: 0,
+				outputTokens: 0,
+				reasoningOutputTokens: 0,
+				totalTokens: 0
+			},
+			sawUsage: false,
+			toolUseEmitted: /* @__PURE__ */ new Set(),
+			sectionIndex: /* @__PURE__ */ new Map(),
+			settled: false,
+			resolve: () => {},
+			reject: () => {}
+		};
+	}
+	async #runTurn() {
+		if (this.#closed) return;
+		const turn = this.#queue.shift();
+		if (!turn) return;
+		this.#setStatus("running");
+		const startedAt = Date.now();
+		const active = this.#newTurnState();
+		const outcome = new Promise((resolve, reject) => {
+			active.resolve = (turnResult) => {
+				if (active.settled) return;
+				active.settled = true;
+				resolve(turnResult);
+			};
+			active.reject = (error) => {
+				if (active.settled) return;
+				active.settled = true;
+				reject(error);
+			};
+		});
+		this.#activeTurn = active;
+		try {
+			const connection = await this.#ensureThread();
+			const params = {
+				threadId: this.#sdkSessionId,
+				input: turn.input,
+				cwd: this.#config.cwd,
+				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
+				sandboxPolicy: TURN_SANDBOX_BY_MODE[this.#permissionMode]
+			};
+			const model = this.#model ?? this.#resolvedModel;
+			if (model) params.model = model;
+			const effort = this.#reasoningEffort ?? this.#resolvedEffort;
+			if (effort) params.effort = effort;
+			connection.request("turn/start", params).then((result) => {
+				const started = result?.turn;
+				if (!started) return;
+				active.turnId ??= started.id;
+				if (started.status && started.status !== "inProgress") active.resolve(started);
+			}, (error) => active.reject(error instanceof Error ? error : new Error(String(error))));
+			const result = await outcome;
+			if (this.#closed) return;
+			if (result.status === "completed") this.#finishTurn("success", startedAt, active);
+			else {
+				const reason = result.status === "interrupted" ? "interrupted" : result.error?.message ?? active.lastError ?? "codex app-server ended the turn without a result";
+				this.#finishTurn("failure", startedAt, active, [reason]);
+			}
+		} catch (error) {
+			if (this.#closed) return;
+			const message = error instanceof Error ? error.message : String(error);
+			this.#finishTurn("failure", startedAt, active, [active.interrupted ? "interrupted" : message]);
+		} finally {
+			if (this.#activeTurn === active) this.#activeTurn = void 0;
+		}
+	}
+	#handleNotification(method, params) {
+		if (this.#closed) return;
+		const active = this.#activeTurn;
+		switch (method) {
+			case "thread/started": {
+				const thread = params?.thread;
+				if (typeof thread?.id === "string") this.#sdkSessionId = thread.id;
+				return;
+			}
+			case "turn/started": {
+				const turn = params?.turn;
+				if (active && turn && !active.turnId) active.turnId = turn.id;
+				return;
+			}
+			case "turn/completed": {
+				const turn = params?.turn;
+				if (active && turn) active.resolve(turn);
+				return;
+			}
+			case "item/started":
+			case "item/updated": {
+				if (!active) return;
+				const item = params?.item;
+				if (item) this.#handleItemProgress(item, active);
+				return;
+			}
+			case "item/completed": {
+				if (!active) return;
+				const item = params?.item;
+				if (item) this.#handleItemCompleted(item, active);
+				return;
+			}
+			case "item/agentMessage/delta": {
+				if (!active) return;
+				const delta = params?.delta;
+				if (typeof delta === "string" && delta) this.#emitDelta({
+					type: "text_delta",
+					text: delta
+				});
+				return;
+			}
+			case "item/reasoning/textDelta":
+			case "item/reasoning/summaryTextDelta": {
+				if (!active) return;
+				const payload = params;
+				if (typeof payload?.delta !== "string" || !payload.delta) return;
+				const index = payload.contentIndex ?? payload.summaryIndex ?? 0;
+				const key = `${payload.itemId ?? ""}:${method}`;
+				const previous = active.sectionIndex.get(key);
+				active.sectionIndex.set(key, index);
+				const separator = previous !== void 0 && index > previous ? "\n\n" : "";
+				this.#emitDelta({
+					type: "thinking_delta",
+					thinking: separator + payload.delta
+				});
+				return;
+			}
+			case "thread/tokenUsage/updated": {
+				if (!active) return;
+				const last = params?.tokenUsage?.last;
+				if (!last) return;
+				active.sawUsage = true;
+				active.usage.inputTokens += last.inputTokens ?? 0;
+				active.usage.cachedInputTokens += last.cachedInputTokens ?? 0;
+				active.usage.cacheWriteInputTokens = (active.usage.cacheWriteInputTokens ?? 0) + (last.cacheWriteInputTokens ?? 0);
+				active.usage.outputTokens += last.outputTokens ?? 0;
+				active.usage.reasoningOutputTokens += last.reasoningOutputTokens ?? 0;
+				const update = params;
+				active.contextTokens = last.totalTokens ?? void 0;
+				active.contextWindow = update.tokenUsage?.modelContextWindow ?? void 0;
+				return;
+			}
+			case "account/rateLimits/updated":
+				this.#emitRateLimits(params?.rateLimits);
+				return;
+			case "turn/plan/updated": {
+				if (!active) return;
+				const plan = params?.plan;
+				if (!Array.isArray(plan)) return;
+				this.#emit({
+					type: "sdk_event",
+					payload: {
+						type: "codex.todo_list",
+						id: `${active.nonce}:plan`,
+						items: plan.map((step) => ({
+							text: step.step,
+							completed: step.status === "completed"
+						}))
+					}
+				});
+				return;
+			}
+			case "serverRequest/resolved": {
+				const requestId = params?.requestId;
+				if (requestId === void 0) return;
+				for (const [id, pending] of this.#approvals) if (pending.wireId === requestId) {
+					this.#settleApproval(id, pending, {
+						behavior: "deny",
+						message: "resolved by codex"
+					}, "policy");
+					return;
+				}
+				return;
+			}
+			case "error": {
+				const error = params?.error;
+				if (active && typeof error?.message === "string") active.lastError = error.message;
+				return;
+			}
+			default: return;
+		}
+	}
+	/** Answer a server→client request: the ask channels become pending
+	* permission requests; anything else gets a JSON-RPC -32601 rather than a
+	* hang (an unanswered server request wedges the turn). */
+	async #answerServerRequest(method, params, wireId) {
+		const channel = APPROVAL_CHANNELS[method];
+		if (channel) return this.#requestApproval(channel, method, params, wireId);
+		throw new JsonRpcError(-32601, `workerdeck does not handle server request '${method}'`);
+	}
+	/**
+	* Surface one ask-channel request as a pending {@link PermissionRequest};
+	* the returned promise is the JSON-RPC response, resolved when a
+	* `permission_decision` lands — or by the timeout, an interrupt, turn end,
+	* session close, or codex resolving it itself. Never left hanging.
+	*/
+	#requestApproval(channel, method, params, wireId) {
+		if (method === "item/tool/requestUserInput") {
+			const behavior = this.#config.questionBehavior ?? "ask";
+			if (behavior !== "ask") return Promise.resolve(this.#resolveQuestionByPolicy(channel, params, behavior));
+		}
+		const id = randomUUID();
+		const timeoutMs = this.#config.approvalTimeoutMs ?? this.#config.defaultApprovalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+		const itemId = channel.itemId(params);
+		const request = {
+			id,
+			...channel.describe(params),
+			toolUseId: itemId ? `${this.#activeTurn?.nonce ?? "codex"}:${itemId}` : id,
+			expiresAt: Date.now() + timeoutMs
+		};
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				const pending = this.#approvals.get(id);
+				if (pending) this.#settleApproval(id, pending, {
+					behavior: "deny",
+					message: "Approval timed out"
+				}, "timeout");
+			}, timeoutMs);
+			this.#approvals.set(id, {
+				request,
+				channel,
+				params,
+				offered: offeredDecisions(params),
+				wireId,
+				timer,
+				respond: resolve
+			});
+			this.#emit({
+				type: "permission_requested",
+				request
+			});
+			if (this.#activeTurn) this.#setStatus("awaiting_approval");
+		});
+	}
+	/** 'auto'/'deny' sessions settle codex questions synchronously instead of
+	* pending. Request/resolved events still fire so transcripts and job
+	* webhooks show what was chosen. */
+	#resolveQuestionByPolicy(channel, params, mode) {
+		const itemId = channel.itemId(params);
+		const request = {
+			id: randomUUID(),
+			...channel.describe(params),
+			toolUseId: itemId ? `${this.#activeTurn?.nonce ?? "codex"}:${itemId}` : randomUUID()
+		};
+		this.#emit({
+			type: "permission_requested",
+			request
+		});
+		if (mode === "deny") {
+			this.#emit({
+				type: "permission_resolved",
+				requestId: request.id,
+				behavior: "deny",
+				resolvedBy: "policy",
+				message: "Interactive questions are disabled for this session — choose the most reasonable option yourself and continue."
+			});
+			return { answers: {} };
+		}
+		const answers = {};
+		for (const question of params.questions ?? []) {
+			const first = question.options?.[0]?.label;
+			if (first) answers[question.id] = { answers: [first] };
+		}
+		this.#emit({
+			type: "permission_resolved",
+			requestId: request.id,
+			behavior: "allow",
+			resolvedBy: "policy"
+		});
+		return { answers };
+	}
+	/**
+	* Settle one pending approval: pick the channel's wire response for the
+	* decision, answer the JSON-RPC request, and emit `permission_resolved`.
+	* An allow the request offered no plain accept for becomes the channel's
+	* denial, said out loud — never a silently widened grant, and never a
+	* decision the request didn't offer.
+	*/
+	#settleApproval(id, pending, decision, resolvedBy) {
+		clearTimeout(pending.timer);
+		this.#approvals.delete(id);
+		let behavior = decision.behavior;
+		let message = decision.behavior === "deny" ? decision.message ?? "Denied" : void 0;
+		let sent;
+		if (decision.behavior === "allow") {
+			const allowed = pending.channel.allow(pending.params, decision.updatedInput, pending.offered);
+			if (allowed) sent = allowed;
+			else {
+				behavior = "deny";
+				resolvedBy = "policy";
+				message = "codex offered no plain accept for this request (only broader session/policy grants) — denied instead";
+				sent = pending.channel.deny(pending.params, false, pending.offered);
+			}
+		} else sent = pending.channel.deny(pending.params, decision.interrupt === true, pending.offered);
+		pending.respond(sent.response);
+		this.#emit({
+			type: "permission_resolved",
+			requestId: id,
+			behavior,
+			resolvedBy,
+			message
+		});
+		if (behavior === "deny" && decision.behavior === "deny" && decision.interrupt && sent.decision !== "cancel") this.#interruptTurn();
+		if (!this.#closed && this.#approvals.size === 0 && this.#status === "awaiting_approval") this.#setStatus("running");
+	}
+	/** Tool calls surface as tool_use when they start; text and reasoning stream
+	* natively via the delta notifications. */
+	#handleItemProgress(item, active) {
+		const id = `${active.nonce}:${item.id}`;
+		if (item.type === "commandExecution" && !active.toolUseEmitted.has(id)) {
+			active.toolUseEmitted.add(id);
+			this.#emitToolUse(id, "CodexCommand", { command: item.command });
+			return;
+		}
+		if (item.type === "mcpToolCall" && !active.toolUseEmitted.has(id)) {
+			active.toolUseEmitted.add(id);
+			this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments);
+		}
+	}
+	#handleItemCompleted(item, active) {
+		const id = `${active.nonce}:${item.id}`;
+		switch (item.type) {
+			case "userMessage": return;
+			case "agentMessage": {
+				const text = typeof item.text === "string" ? item.text : "";
+				this.#emitAssistant(id, [{
+					type: "text",
+					text
+				}]);
+				active.finalText = text;
+				return;
+			}
+			case "reasoning": {
+				const summary = Array.isArray(item.summary) ? item.summary.filter(Boolean) : [];
+				const content = Array.isArray(item.content) ? item.content.filter(Boolean) : [];
+				const thinking = (summary.length > 0 ? summary : content).join("\n\n");
+				if (thinking) this.#emitAssistant(id, [{
+					type: "thinking",
+					thinking
+				}]);
+				return;
+			}
+			case "commandExecution": {
+				if (!active.toolUseEmitted.has(id)) {
+					active.toolUseEmitted.add(id);
+					this.#emitToolUse(id, "CodexCommand", { command: item.command });
+				}
+				const exitCode = item.exitCode ?? void 0;
+				const failed = item.status === "failed" || item.status === "declined" || exitCode !== void 0 && exitCode !== 0;
+				const output = (item.aggregatedOutput ?? "") + (exitCode !== void 0 && exitCode !== 0 ? `\n(exit code ${exitCode})` : "");
+				this.#emitToolResult(id, output, failed);
+				return;
+			}
+			case "fileChange": {
+				this.#emitToolUse(id, "CodexFileChange", { changes: item.changes });
+				const lines = item.changes.map((change) => {
+					return `${(typeof change.kind === "string" ? change.kind : change.kind?.type) ?? "change"}: ${change.path}`;
+				});
+				this.#emitToolResult(id, lines.join("\n") || item.status, item.status === "failed" || item.status === "declined");
+				return;
+			}
+			case "mcpToolCall": {
+				if (!active.toolUseEmitted.has(id)) {
+					active.toolUseEmitted.add(id);
+					this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments);
+				}
+				const isError = item.error !== void 0 && item.error !== null || item.status === "failed";
+				this.#emitToolResult(id, item.error?.message ?? (item.result === void 0 || item.result === null ? "" : JSON.stringify(item.result)), isError);
+				return;
+			}
+			case "webSearch":
+				this.#emitToolUse(id, "CodexWebSearch", { query: item.query });
+				this.#emitToolResult(id, "", false);
+				return;
+			default: {
+				const unknown = item;
+				this.#emit({
+					type: "sdk_event",
+					payload: {
+						type: `codex.${unknown.type}`,
+						item: unknown
+					}
+				});
+			}
+		}
+	}
+	#emitDelta(delta) {
+		if (this.#config.includePartialMessages === false) return;
+		this.#emit({
+			type: "stream_delta",
+			event: {
+				type: "content_block_delta",
+				delta
+			},
+			parentToolUseId: null,
+			uuid: randomUUID()
+		});
+	}
+	#emitAssistant(uuid, content) {
+		this.#emit({
+			type: "assistant_message",
+			message: {
+				role: "assistant",
+				content,
+				model: this.#model ?? this.#resolvedModel
+			},
+			parentToolUseId: null,
+			uuid
+		});
+	}
+	#emitToolUse(id, name, input) {
+		this.#emit({
+			type: "assistant_message",
+			message: {
+				role: "assistant",
+				content: [{
+					type: "tool_use",
+					id,
+					name,
+					input
+				}],
+				model: this.#model ?? this.#resolvedModel
+			},
+			parentToolUseId: null,
+			uuid: `${id}-use`
+		});
+	}
+	#emitToolResult(toolUseId, content, isError) {
+		this.#emit({
+			type: "user_message",
+			message: {
+				role: "user",
+				content: [{
+					type: "tool_result",
+					tool_use_id: toolUseId,
+					content,
+					is_error: isError || void 0
+				}]
+			},
+			parentToolUseId: null,
+			synthetic: true,
+			uuid: `${toolUseId}-result`
+		});
+	}
+	/**
+	* Per-turn usage re-mapped to the Anthropic accounting convention the whole
+	* stack assumes (GOTCHAS §Codex engine): OpenAI's `inputTokens` includes the
+	* cached share, so input excludes it (else queue token budgets double-count
+	* cache-heavy runs); reasoning tokens are billed output; `totalCostUsd: 0` =
+	* unknown, the AiSdkRunner precedent. Usage is summed from the turn's
+	* `thread/tokenUsage/updated` notifications — `turn/completed` carries none.
+	*/
+	#finishTurn(kind, startedAt, active, errors) {
+		for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
+			behavior: "deny",
+			message: "Turn ended"
+		}, "policy");
+		this.#numTurns += 1;
+		this.#totalCostUsd = 0;
+		const usage = active.sawUsage ? active.usage : void 0;
+		this.#emit({
+			type: "turn_result",
+			subtype: kind === "success" ? "success" : "error_during_execution",
+			isError: kind !== "success",
+			durationMs: Date.now() - startedAt,
+			numTurns: this.#numTurns,
+			totalCostUsd: 0,
+			result: kind === "success" ? active.finalText ?? "" : void 0,
+			errors,
+			usage: usage ? {
+				input_tokens: Math.max(0, usage.inputTokens - usage.cachedInputTokens),
+				output_tokens: usage.outputTokens + usage.reasoningOutputTokens,
+				cache_creation_input_tokens: usage.cacheWriteInputTokens ?? 0,
+				cache_read_input_tokens: usage.cachedInputTokens
+			} : void 0
+		});
+		this.#emitContextUsage(active);
+		this.#setStatus("idle");
+	}
+	/**
+	* Subscription windows, mapped onto the protocol's named vocabulary.
+	*
+	* The shapes disagree: codex reports windows *positionally* (`primary` /
+	* `secondary`) with a length in minutes, while `RateLimitInfo.rateLimitType`
+	* is a name whose meaning clients already know — iOS labels `seven_day` as
+	* "Weekly" and derives the pace marker's denominator from it. Naming the
+	* window by its measured duration is therefore the honest mapping rather
+	* than a borrowed one: codex's primary window is 10080 minutes, which *is*
+	* seven days. A duration we have no name for keeps an explicit
+	* `window_<n>m` key — clients render it verbatim and simply draw no pace
+	* marker, which beats mislabeling it as a week.
+	*
+	* `status` is 'allowed' by construction (the session is running), matching
+	* `rateLimitEventsFromUsage`; codex's `rateLimitReachedType` is the one
+	* signal that a limit is actually biting, so it becomes 'rejected'.
+	*/
+	#emitRateLimits(limits) {
+		if (!limits) return;
+		const status = limits.rateLimitReachedType ? "rejected" : "allowed";
+		for (const window of [limits.primary, limits.secondary]) {
+			if (!window || window.usedPercent === null || window.usedPercent === void 0) continue;
+			this.#emit({
+				type: "rate_limit",
+				info: {
+					status,
+					rateLimitType: rateLimitWindowName(window.windowDurationMins),
+					utilization: window.usedPercent,
+					...typeof window.resetsAt === "number" ? { resetsAt: window.resetsAt } : {}
+				}
+			});
+		}
+		if (limits.planType && limits.planType !== this.#planType) {
+			this.#planType = limits.planType;
+			this.#emit({
+				type: "plan_info",
+				subscriptionType: limits.planType
+			});
+		}
+	}
+	/**
+	* Context occupancy, after the turn — the same cadence the Claude runner
+	* polls `getContextUsage()` on, so clients need nothing new.
+	*
+	* Emitted only when the binary gave BOTH numbers: the protocol is explicit
+	* that a client renders nothing rather than a 0% ring, and a window of
+	* `null` (which app-server does send) would otherwise divide into a
+	* meaningless percentage. `categories` is empty because codex publishes no
+	* breakdown — clients must not render an empty "Breakdown" section for it.
+	*/
+	#emitContextUsage(active) {
+		const totalTokens = active.contextTokens;
+		const maxTokens = active.contextWindow;
+		if (totalTokens === void 0 || !maxTokens || maxTokens <= 0) return;
+		this.#emit({
+			type: "context_usage",
+			usage: {
+				categories: [],
+				totalTokens,
+				maxTokens,
+				percentage: Math.min(100, totalTokens / maxTokens * 100),
+				model: this.#model ?? this.#resolvedModel
+			}
+		});
+	}
+	#setStatus(status, detail) {
+		if (this.#status === status) return;
+		if (this.#status === "closed" || this.#status === "failed") return;
+		this.#status = status;
+		this.#emit({
+			type: "status_changed",
+			status,
+			detail
+		});
+	}
+	#emit(body) {
+		if (this.#replayingHistory && (body.type === "assistant_message" || body.type === "user_message")) body = {
+			...body,
+			replay: true
+		};
+		const event = {
+			...body,
+			seq: ++this.#seq,
+			ts: Date.now()
+		};
+		this.#lastActivityAt = event.ts;
+		this.#events.push(event);
+		for (const listener of this.#listeners) try {
+			listener(event);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/engines/codex/catalog.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.
+*/
+const CODEX_CATALOG = {
+	provenance: "embedded model presets of @openai/codex@0.146.0 (darwin-arm64 binary), extracted 2026-08-05",
+	models: [
+		{
+			value: "gpt-5.6-sol",
+			resolvedModel: "gpt-5.6-sol",
+			displayName: "GPT-5.6 Sol",
+			description: "Latest frontier agentic coding model.",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max",
+				"ultra"
+			]
+		},
+		{
+			value: "gpt-5.6-terra",
+			resolvedModel: "gpt-5.6-terra",
+			displayName: "GPT-5.6 Terra",
+			description: "Balanced agentic coding model for everyday work.",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max",
+				"ultra"
+			]
+		},
+		{
+			value: "gpt-5.6-luna",
+			resolvedModel: "gpt-5.6-luna",
+			displayName: "GPT-5.6 Luna",
+			description: "Fast and affordable agentic coding model.",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh",
+				"max"
+			]
+		},
+		{
+			value: "gpt-5.5",
+			resolvedModel: "gpt-5.5",
+			displayName: "GPT-5.5",
+			description: "Frontier model for complex coding, research, and real-world work.",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh"
+			]
+		},
+		{
+			value: "gpt-5.4",
+			resolvedModel: "gpt-5.4",
+			displayName: "GPT-5.4",
+			description: "Strong model for everyday coding.",
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh"
+			]
+		},
+		{
+			value: "gpt-5.4-mini",
+			resolvedModel: "gpt-5.4-mini",
+			displayName: "GPT-5.4 Mini",
+			description: "Small, fast, and cost-efficient model for simpler coding tasks.",
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh"
+			]
+		},
+		{
+			value: "gpt-5.2",
+			resolvedModel: "gpt-5.2",
+			displayName: "GPT-5.2",
+			description: "Optimized for professional work and long-running agents.",
+			primary: true,
+			reasoningEfforts: [
+				"low",
+				"medium",
+				"high",
+				"xhigh"
+			]
+		}
+	]
+};
+//#endregion
+//#region src/engines/codex/process.ts
+/** How much stderr to keep for the exit diagnostic. The binary logs startup
+* noise there; only the tail explains a death. */
+const STDERR_TAIL_BYTES = 4096;
+/**
+* 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.
+*/
+function connectAppServer(options) {
+	const child = spawn(options.executable, ["app-server"], {
+		env: options.env,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+	const rpc = new JsonRpcStdioConnection({
+		input: child.stdout,
+		output: child.stdin
+	});
+	let stderrTail = "";
+	child.stderr.on("data", (chunk) => {
+		stderrTail = (stderrTail + String(chunk)).slice(-STDERR_TAIL_BYTES);
+	});
+	let closeHandler;
+	let done = false;
+	const settle = (message) => {
+		if (done) return;
+		done = true;
+		rpc.fail(message);
+		closeHandler?.(message);
+	};
+	child.on("error", (error) => settle(`codex app-server failed to start: ${error.message}`));
+	child.on("exit", (code, signal) => {
+		const tail = stderrTail.trim();
+		settle(`codex app-server exited (${signal ?? `code ${code}`})` + (tail ? `: ${tail.slice(-500)}` : ""));
+	});
+	return {
+		request: (method, params) => rpc.request(method, params),
+		notify: (method, params) => rpc.notify(method, params),
+		onNotification: (handler) => rpc.onNotification(handler),
+		onRequest: (handler) => rpc.onRequest(handler),
+		onClose: (handler) => {
+			closeHandler = handler;
+		},
+		close: () => {
+			done = true;
+			rpc.fail("codex app-server connection closed");
+			child.kill();
+		}
+	};
+}
+//#endregion
+//#region src/engines/codex/adapter.ts
+const NOT_INSTALLED = "@openai/codex is not installed — add it (an optional peer of @workerdeck/core) to run codex profiles";
+/**
+* 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'.
+*/
+function resolveBundledCodexExecutable() {
+	const triple = targetTriple();
+	if (!triple) return void 0;
+	try {
+		const path = createRequire(createRequire(import.meta.url).resolve("@openai/codex/package.json")).resolve(`@openai/codex-${platformPackageSuffix()}/package.json`).replace(/package\.json$/, `vendor/${triple}/bin/codex`);
+		if (existsSync(path)) return path;
+	} catch {}
+}
+function targetTriple() {
+	const { platform, arch } = process;
+	if (platform === "darwin") return arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin";
+	if (platform === "linux") return arch === "arm64" ? "aarch64-unknown-linux-musl" : "x86_64-unknown-linux-musl";
+	if (platform === "win32") return "x86_64-pc-windows-msvc";
+}
+function platformPackageSuffix() {
+	return `${process.platform}-${process.arch}`;
+}
+/**
+* Availability, mirroring **the app-server surface's actual credential chain**
+* (verified 2026-08-05 against 0.146.0 by driving the raw binary): auth comes
+* solely from the CODEX_HOME auth store (`codex login`, file or keyring). The
+* env-key routes are dead ends here — `CODEX_API_KEY` is read only by
+* `codex exec` (a turn goes out with no credential at all: "Missing bearer"),
+* and `OPENAI_API_KEY` was never read by either surface. So, in order:
+*
+* 1. Binary resolvable, else unavailable with the install reason;
+* 2. `codex login status` under the profile's complete session env:
+*    exit 0 → available; the "Not logged in" verdict → unavailable, with an
+*    exact remedy when a stranded env key explains the misconfiguration;
+*    anything else (a stray CODEX_ACCESS_TOKEN JWT error, a crashed spawn) →
+*    'unknown' — the checkClaudeAuth never-overclaim discipline.
+*
+* Only the exit code and the fixed verdict line are consulted — never
+* surfaced: `login status` output includes a masked key fragment. The
+* `smoke:codex --canary` run is the drift alarm for all of this.
+*/
+async function checkCodexAvailability(profile, env, options = {}) {
+	const executable = resolveBundledCodexExecutable();
+	if (!executable) return {
+		available: false,
+		reason: NOT_INSTALLED
+	};
+	const childEnv = {};
+	for (const [key, value] of Object.entries(env)) if (value !== void 0) childEnv[key] = value;
+	if (profile.codexHome) childEnv.CODEX_HOME = profile.codexHome;
+	return new Promise((resolve) => {
+		execFile(executable, ["login", "status"], {
+			env: childEnv,
+			timeout: options.timeoutMs ?? 1e4
+		}, (error, stdout, stderr) => {
+			if (!error) {
+				resolve({ available: true });
+				return;
+			}
+			if (`${stdout}\n${stderr}`.includes("Not logged in")) {
+				const hint = childEnv.CODEX_API_KEY ? " CODEX_API_KEY is read only by `codex exec`, never by the app-server — run `codex login --with-api-key` under this profile’s CODEX_HOME to persist it." : childEnv.OPENAI_API_KEY ? " OPENAI_API_KEY is not used by codex — run `codex login --with-api-key` under this profile’s CODEX_HOME." : "";
+				resolve({
+					available: false,
+					reason: `codex is not logged in for this profile's environment — run \`codex login\`` + (profile.codexHome ? ` with CODEX_HOME=${profile.codexHome}` : "") + `.${hint}`
+				});
+				return;
+			}
+			resolve({ available: "unknown" });
+		});
+	});
+}
+/** `thread/list` page size (its own default is 25) and a hard page bound so a
+* misbehaving cursor can never spin the listing forever. */
+const LIST_PAGE_SIZE = 100;
+const MAX_LIST_PAGES = 40;
+/** thread/list's `cwd` filter is an EXACT path match (measured, 0.146.0), so
+* offer both the spelled and canonical forms — macOS listings would otherwise
+* miss `/tmp/...` threads recorded under `/private/tmp/...`. */
+function cwdFilter(dir) {
+	const forms = new Set([dir]);
+	try {
+		forms.add(realpathSync(dir));
+	} catch {}
+	return [...forms];
+}
+const secondsToMs = (value) => typeof value === "number" && Number.isFinite(value) ? value * 1e3 : void 0;
+/** One thread row in the protocol's browser-safe summary shape. `id` is what
+* `CreateSessionRequest.resume` feeds `thread/resume` — the row's separate
+* `sessionId` field is not it. */
+function summarizeThread(row) {
+	const name = typeof row.name === "string" && row.name.length > 0 ? row.name : void 0;
+	const preview = typeof row.preview === "string" && row.preview.length > 0 ? row.preview : void 0;
+	return {
+		sessionId: row.id,
+		summary: name ?? preview ?? row.id,
+		lastModified: secondsToMs(row.updatedAt) ?? secondsToMs(row.createdAt) ?? 0,
+		createdAt: secondsToMs(row.createdAt),
+		customTitle: name,
+		firstPrompt: preview,
+		gitBranch: typeof row.gitInfo?.branch === "string" && row.gitInfo.branch.length > 0 ? row.gitInfo.branch : void 0,
+		cwd: typeof row.cwd === "string" ? row.cwd : void 0
+	};
+}
+/**
+* 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.
+*/
+async function listCodexSessions(options) {
+	const childEnv = {};
+	for (const [key, value] of Object.entries(options.env)) if (value !== void 0) childEnv[key] = value;
+	if (options.profile?.codexHome) childEnv.CODEX_HOME = options.profile.codexHome;
+	const connection = options.connectFn({ env: childEnv });
+	const rows = [];
+	try {
+		await connection.request("initialize", {
+			clientInfo: {
+				name: "workerdeck",
+				title: "WorkerDeck",
+				version: `protocol-${PROTOCOL_VERSION}`
+			},
+			capabilities: { experimentalApi: true }
+		});
+		connection.notify("initialized");
+		const base = {
+			limit: LIST_PAGE_SIZE,
+			sortKey: "updated_at",
+			...options.dir ? { cwd: cwdFilter(options.dir) } : {}
+		};
+		const want = options.limit === void 0 ? void 0 : (options.offset ?? 0) + options.limit;
+		let cursor;
+		for (let page = 0; page < MAX_LIST_PAGES; page++) {
+			const result = await connection.request("thread/list", {
+				...base,
+				...cursor ? { cursor } : {}
+			});
+			const data = Array.isArray(result?.data) ? result.data : [];
+			rows.push(...data);
+			if (want !== void 0 && rows.length >= want) break;
+			if (data.length === 0 || typeof result?.nextCursor !== "string") break;
+			cursor = result.nextCursor;
+		}
+	} finally {
+		connection.close();
+	}
+	const summaries = rows.filter((row) => typeof row.id === "string" && row.id.length > 0 && !row.ephemeral).map(summarizeThread);
+	const start = options.offset ?? 0;
+	return options.limit === void 0 ? summaries.slice(start) : summaries.slice(start, start + options.limit);
+}
+/**
+* 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.
+*/
+const codexAdapter = {
+	engine: "codex",
+	capabilities: ENGINE_CAPABILITIES.codex,
+	catalog: CODEX_CATALOG,
+	checkAvailability: (profile, env) => checkCodexAvailability(profile, env),
+	createRunner({ config, profile, restore }) {
+		if (restore) throw new Error("the codex engine cannot rebuild a parked session");
+		const executable = config.codexPathOverride ?? resolveBundledCodexExecutable();
+		if (!executable) throw new Error(NOT_INSTALLED);
+		return new CodexRunner({
+			...config,
+			codexHome: profile?.codexHome,
+			connectFn: (options) => connectAppServer({
+				executable,
+				...options
+			})
+		});
+	},
+	async listSessions(options) {
+		const executable = resolveBundledCodexExecutable();
+		if (!executable) throw new Error(NOT_INSTALLED);
+		return listCodexSessions({
+			...options,
+			connectFn: (connect) => connectAppServer({
+				executable,
+				...connect
+			})
+		});
+	}
+};
+//#endregion
+//#region src/engines/provider/adapter.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.
+*/
+const providerAdapter = {
+	engine: "provider",
+	capabilities: ENGINE_CAPABILITIES.provider,
+	catalog: {
+		models: [],
+		provenance: "provider model ids are operator-declared (provider.models)"
+	},
+	async checkAvailability(profile, env) {
+		const keyEnv = profile.provider?.apiKeyEnv;
+		if (!keyEnv) return { available: "unknown" };
+		const value = env[keyEnv];
+		if (value !== void 0 && value !== "") return { available: true };
+		return {
+			available: false,
+			reason: `${keyEnv} is not set in the server environment (profile '${profile.name}' names it as apiKeyEnv)`
+		};
+	},
+	createRunner() {
+		throw new Error("provider-engine runners are built by the host's createEngineRunner hook, not the adapter");
+	}
+};
+//#endregion
+//#region src/engines/adapter.ts
+const ADAPTERS = {
+	claude: claudeAdapter,
+	codex: codexAdapter,
+	provider: providerAdapter
+};
+/** The in-repo adapter for an engine. An absent `engine` means 'claude'. */
+function getEngineAdapter(engine) {
+	return ADAPTERS[engine ?? "claude"];
+}
+//#endregion
+export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, PendingRequestRegistry, QuickJsExecutor, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, 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.mjs.map