@workerdeck/core 0.13.0 → 0.16.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
-import { getSessionMessages, listSessions, query } from "@anthropic-ai/claude-agent-sdk";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, transcriptActivity } from "@workerdeck/protocol";
+import { getSessionInfo, getSessionMessages, listSessions, query } from "@anthropic-ai/claude-agent-sdk";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, replayCoalesceKey, transcriptActivity, transcriptContent } from "@workerdeck/protocol";
 import { ToolLoopAgent, generateText, isStepCount, tool } from "ai";
 import { execFile, spawn } from "node:child_process";
 import { existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -10,7 +10,7 @@ import { z } from "zod";
 import { lookup } from "node:dns/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-//#region src/attachments.ts
+//#region src/lib/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([
@@ -103,7 +103,7 @@ function decodeText(base64) {
 	return Buffer.from(base64, "base64").toString("utf8");
 }
 //#endregion
-//#region src/input-queue.ts
+//#region src/lib/input-queue.ts
 /**
 * Push-based single-consumer AsyncIterable bridging imperative sendMessage() calls
 * into the streaming `prompt` the Agent SDK consumes.
@@ -162,7 +162,160 @@ var InputQueue = class {
 	}
 };
 //#endregion
-//#region src/normalize.ts
+//#region src/lib/patch.ts
+/**
+* Turning an engine's edit output into the wire's {@link FilePatch}.
+*
+* Both engines know exactly which lines of which file changed, and both say so
+* in their own vocabulary: the Claude SDK hands over a `structuredPatch` array
+* on `SDKUserMessage.tool_use_result`, codex puts a unified diff string on each
+* `fileChange` item. A client can reconstruct neither — it has never seen the
+* file — so anything not normalized here is a diff that renders without line
+* numbers.
+*
+* Normalizing in the runner rather than in each client is the point: one shape
+* reaches the wire, and the dashboard, the extension and the phone all render
+* from it without a per-engine branch or a diff parser of their own.
+*/
+/**
+* The most lines a patch may put on the wire.
+*
+* A patch is replayed on every attach and captured into parking snapshots, so
+* "the diff is big" must not become "this session is expensive to open forever".
+* Whole hunks are kept or dropped — half a hunk has misleading line numbers —
+* and the drop is flagged so a renderer can say the diff is partial instead of
+* presenting it as the whole change.
+*/
+const MAX_PATCH_LINES = 400;
+function capHunks(hunks) {
+	const kept = [];
+	let lines = 0;
+	for (const hunk of hunks) {
+		if (lines + hunk.lines.length > MAX_PATCH_LINES && kept.length > 0) return {
+			hunks: kept,
+			truncated: true
+		};
+		kept.push(hunk);
+		lines += hunk.lines.length;
+	}
+	return { hunks: kept };
+}
+/** Structural, not `instanceof`: this reads a field the SDK types as `unknown`,
+* and a shape check is the only honest way to know what arrived. */
+function isHunk(value) {
+	const hunk = value;
+	return !!hunk && typeof hunk.oldStart === "number" && typeof hunk.oldLines === "number" && typeof hunk.newStart === "number" && typeof hunk.newLines === "number" && Array.isArray(hunk.lines) && hunk.lines.every((line) => typeof line === "string");
+}
+/**
+* A {@link FilePatch} from the Claude SDK's structured tool output
+* (`SDKUserMessage.tool_use_result` for Edit/Write/NotebookEdit).
+*
+* Everything else on that object is deliberately left behind — `originalFile`
+* alone is the entire pre-edit file, which is precisely what must not be logged
+* (see `FilePatch`'s own note).
+*/
+function filePatchFromToolResult(result) {
+	const output = result;
+	if (!output || !Array.isArray(output.structuredPatch)) return void 0;
+	const hunks = output.structuredPatch.filter(isHunk);
+	if (hunks.length === 0) return void 0;
+	const { hunks: kept, truncated } = capHunks(hunks);
+	return {
+		...typeof output.filePath === "string" && { path: output.filePath },
+		...output.type === "create" || output.originalFile === null ? { kind: "create" } : output.type === "update" || typeof output.originalFile === "string" ? { kind: "update" } : {},
+		hunks: kept,
+		...truncated && { truncated }
+	};
+}
+/** `@@ -oldStart,oldLines +newStart,newLines @@` — the counts are optional and
+* mean 1 when absent, which is what a single-line hunk looks like. */
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+/**
+* A {@link FilePatch} from a unified diff — codex's `fileChange.diff`.
+*
+* Only the hunks are read. A diff's `---`/`+++` header names the file, but codex
+* already reports the path on the change itself, and a header path is often
+* relative or `/dev/null`, so the caller's path is the one worth trusting.
+*
+* Returns undefined when there is no hunk header at all: that is not a unified
+* diff, and inventing hunk numbers for it would put wrong line numbers on screen
+* — worse than none.
+*/
+function parseUnifiedDiff(diff, path) {
+	const hunks = [];
+	let current;
+	for (const line of diff.split("\n")) {
+		const header = HUNK_HEADER.exec(line);
+		if (header) {
+			current = {
+				oldStart: Number(header[1]),
+				oldLines: header[2] === void 0 ? 1 : Number(header[2]),
+				newStart: Number(header[3]),
+				newLines: header[4] === void 0 ? 1 : Number(header[4]),
+				lines: []
+			};
+			hunks.push(current);
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith(" ") || line.startsWith("-") || line.startsWith("+")) current.lines.push(line);
+		else if (line === "") current.lines.push(" ");
+		else current = void 0;
+	}
+	if (hunks.length === 0) return void 0;
+	const { hunks: kept, truncated } = capHunks(hunks);
+	return {
+		...path && { path },
+		hunks: kept,
+		...truncated && { truncated }
+	};
+}
+//#endregion
+//#region src/lib/normalize.ts
+/** Does this message answer exactly one tool call? A patch is per-file-edit and
+* the message says nothing about which of two results it describes, so anything
+* else gets no patch rather than a diff pinned to the wrong call. */
+function singleToolResult(message) {
+	const content = message.content;
+	if (!Array.isArray(content)) return false;
+	return content.filter((block) => block.type === "tool_result").length === 1;
+}
+/**
+* The wrappers the CLI writes into the transcript when the *harness* is talking
+* to the model rather than a person talking to the session.
+*
+* Deliberately a text test, and only these two. The live path has structure to
+* go on (`isSynthetic`, `origin.kind`), but **the resumed path has none**: the
+* SDK's `SessionMessage` carries exactly `message`, `uuid`, `session_id`,
+* `parent_tool_use_id`, `parent_agent_id` and `timestamp` — every one of
+* `isMeta`, `isSidechain`, `promptSource` and `origin` is dropped between the
+* stored JSONL and what `getSessionMessages` hands back (verified against real
+* transcripts). So on resume this is the only signal there is, and without it a
+* `<task-notification>` blob comes back as a blue user row and a scrubber mark,
+* as if someone had typed it.
+*
+* `<local-command-caveat>` is here for symmetry and cheap insurance: the SDK
+* filters `isMeta` entries out of a resumed transcript itself today, which is
+* not a contract anyone wrote down.
+*
+* What is *not* here matters as much:
+* - `<local-command-stdout>` — the reducer turns it into a notice row on
+*   purpose; marking it synthetic would delete a row both paths show.
+* - `<command-name>` — that is a person running a slash command. The reducer
+*   renders it as the command line they typed; hiding it would erase the turn's
+*   cause.
+*/
+const SYNTHETIC_USER_PREFIXES = ["<task-notification>", "<local-command-caveat>"];
+/** First text block's leading tag, for the test above. Tool results and images
+* carry no text and are never synthetic by this rule (a tool result is already
+* a tool result to every renderer). */
+function isSyntheticUserText(message) {
+	const content = message.content;
+	const text = typeof content === "string" ? content : Array.isArray(content) ? content.find((block) => block.type === "text")?.text : void 0;
+	if (typeof text !== "string") return false;
+	const head = text.trimStart();
+	return SYNTHETIC_USER_PREFIXES.some((prefix) => head.startsWith(prefix));
+}
 function toApiMessage(message) {
 	const m = message;
 	return {
@@ -351,14 +504,18 @@ function normalizeSdkMessage(msg) {
 			parentToolUseId: msg.parent_tool_use_id,
 			uuid: msg.uuid
 		};
-		case "user": return {
-			type: "user_message",
-			message: toApiMessage(msg.message),
-			parentToolUseId: msg.parent_tool_use_id,
-			replay: "isReplay" in msg && msg.isReplay === true ? true : void 0,
-			synthetic: msg.isSynthetic === true ? true : void 0,
-			uuid: msg.uuid
-		};
+		case "user": {
+			const message = toApiMessage(msg.message);
+			return {
+				type: "user_message",
+				message,
+				parentToolUseId: msg.parent_tool_use_id,
+				replay: "isReplay" in msg && msg.isReplay === true ? true : void 0,
+				synthetic: msg.isSynthetic === true || msg.origin?.kind === "task-notification" || isSyntheticUserText(message) ? true : void 0,
+				patch: singleToolResult(message) ? filePatchFromToolResult(msg.tool_use_result) : void 0,
+				uuid: msg.uuid
+			};
+		}
 		case "stream_event": return {
 			type: "stream_delta",
 			event: msg.event,
@@ -376,6 +533,10 @@ function normalizeSdkMessage(msg) {
 			errors: msg.subtype === "success" ? void 0 : msg.errors,
 			usage: msg.usage
 		};
+		case "conversation_reset": return {
+			type: "conversation_reset",
+			sdkSessionId: msg.new_conversation_id
+		};
 		case "rate_limit_event": return {
 			type: "rate_limit",
 			info: {
@@ -399,7 +560,41 @@ function normalizeSdkMessage(msg) {
 	}
 }
 //#endregion
-//#region src/runner.ts
+//#region src/lib/replay.ts
+/**
+* Which buffered events a coalesced replay should skip: everything superseded
+* by a later event with the same {@link replayCoalesceKey}.
+*
+* A **backwards** scan, keeping the first occurrence of each key — which is the
+* whole trick. Walking forwards would need a second pass to know which of the
+* fifty context readings was the last one; walking backwards, the first one you
+* meet *is* the last one, and everything after it (in scan order) is history.
+*
+* Note what this does **not** do: it never reorders and never touches an event
+* with no key. Transcript content is an ordered fold — a stream delta
+* accumulates onto a message, a tool result attaches to a call that came
+* earlier, a turn result finalizes — so it must arrive exactly as it was
+* emitted. Only last-write-wins *state* is eligible, and `replayCoalesceKey`
+* is where that judgement lives.
+*
+* `afterSeq` is honoured so the scan agrees with the caller's replay window: an
+* event the caller was never going to send must not suppress one it was.
+*/
+function staleReplaySeqs(events, afterSeq) {
+	const stale = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	for (let index = events.length - 1; index >= 0; index--) {
+		const event = events[index];
+		if (event.seq <= afterSeq) break;
+		const key = replayCoalesceKey(event);
+		if (key === void 0) continue;
+		if (seen.has(key)) stale.add(event.seq);
+		else seen.add(key);
+	}
+	return stale;
+}
+//#endregion
+//#region src/engines/claude/runner.ts
 const DEFAULT_APPROVAL_TIMEOUT_MS$1 = 3e5;
 /**
 * One live Agent SDK session: owns the query() call, the streaming input queue, the
@@ -410,10 +605,21 @@ var SessionRunner = class {
 	id;
 	createdAt;
 	#config;
+	/** {@link SessionRunnerConfig.cwd}, checked once in the constructor. */
+	#cwd;
 	#events = [];
 	#listeners = /* @__PURE__ */ new Set();
 	#seq = 0;
 	#activityCount = 0;
+	/**
+	* Seq of the latest `conversation_reset` event, 0 when none. The log itself is
+	* never truncated — it still carries the state-bearing events (`capabilities`,
+	* `system_init`, …) a fresh attacher depends on and which are not re-emitted —
+	* but `subscribe()` skips transcript *content* strictly below this mark, so a
+	* replay does not resurrect a cleared conversation. A later reset supersedes
+	* an earlier one by overwriting it.
+	*/
+	#resetSeq = 0;
 	#status = "starting";
 	#statusDetail;
 	#sdkSessionId;
@@ -430,10 +636,15 @@ var SessionRunner = class {
 	/** Last plan reported by the usage poll, so `plan_info` is emitted on change
 	* rather than once per turn. */
 	#subscriptionType;
+	/** The title the CLI gave this thread (see `#fetchEngineTitle`). Undefined
+	* until it has one — a session gets its summary a turn or two in. */
+	#engineTitle;
 	#started = false;
 	#closed = false;
 	#runPromise;
 	constructor(config, id = randomUUID()) {
+		if (!config.cwd) throw new Error("the claude engine requires a cwd");
+		this.#cwd = config.cwd;
 		this.#config = config;
 		this.#permissionMode = config.permissionMode;
 		this.id = id;
@@ -460,7 +671,7 @@ var SessionRunner = class {
 			id: this.id,
 			sdkSessionId: this.#sdkSessionId,
 			status: this.#status,
-			cwd: this.#config.cwd,
+			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "claude",
 			capabilities: ENGINE_CAPABILITIES.claude,
@@ -473,15 +684,27 @@ var SessionRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: this.#pending.size,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			totalCostUsd: this.#totalCostUsd,
 			numTurns: this.#numTurns,
 			lastActivityAt: this.#lastActivityAt
 		};
 	}
+	/**
+	* Three sources, most-deliberate first: the host's own rename (`meta.title`),
+	* the title the CLI gave this thread (`#engineTitle`), then the first prompt
+	* truncated.
+	*
+	* The rename outranks everything by design — a person naming a session must
+	* not have it renamed under them by a model — which is also why the engine
+	* title is *only ever read* while `meta.title` is unset (see
+	* `#fetchEngineTitle`), rather than read and then discarded here.
+	*/
 	#title() {
 		const metaTitle = this.#config.meta?.title;
 		if (typeof metaTitle === "string" && metaTitle.length > 0) return metaTitle;
+		if (this.#engineTitle) return this.#engineTitle;
 		const prompt = this.#config.prompt;
 		if (!prompt) return void 0;
 		return prompt.length > 80 ? prompt.slice(0, 77) + "…" : prompt;
@@ -611,9 +834,24 @@ var SessionRunner = class {
 	/**
 	* Replay buffered events with seq > afterSeq, then deliver live events.
 	* Returns an unsubscribe function.
+	*
+	* Replay honours the reset watermark: transcript content below the latest
+	* `conversation_reset` is skipped (the reducer would clear it again anyway,
+	* and a pre-reset client that never learned the reducer's case would render
+	* a conversation the engine has discarded), while state-bearing events —
+	* which are emitted once and never again — always replay. The reset event
+	* itself replays (the skip is strictly-below), which is what clears a
+	* reconnecting client still holding pre-reset rows; superseded resets are
+	* content below the newer one and are skipped with what they cleared.
 	*/
-	subscribe(listener, afterSeq = 0) {
-		for (const event of this.#events) if (event.seq > afterSeq) listener(event);
+	subscribe(listener, afterSeq = 0, options) {
+		const stale = options?.coalesceReplay ? staleReplaySeqs(this.#events, afterSeq) : void 0;
+		for (const event of this.#events) {
+			if (event.seq <= afterSeq) continue;
+			if (event.seq < this.#resetSeq && transcriptContent(event)) continue;
+			if (stale?.has(event.seq)) continue;
+			listener(event);
+		}
 		this.#listeners.add(listener);
 		return () => this.#listeners.delete(listener);
 	}
@@ -665,20 +903,23 @@ var SessionRunner = class {
 		const historyFn = c.historyFn ?? ((sessionId, options) => getSessionMessages(sessionId, options));
 		let messages;
 		try {
-			messages = await historyFn(c.resume, { dir: c.cwd });
+			messages = await historyFn(c.resume, { dir: this.#cwd });
 		} catch {
 			return;
 		}
 		for (const m of messages) {
 			if (this.#closed) return;
-			if (m.type === "user") this.#emit({
-				type: "user_message",
-				message: toApiMessage(m.message),
-				parentToolUseId: m.parent_tool_use_id,
-				replay: true,
-				uuid: m.uuid
-			});
-			else if (m.type === "assistant") this.#emit({
+			if (m.type === "user") {
+				const message = toApiMessage(m.message);
+				this.#emit({
+					type: "user_message",
+					message,
+					parentToolUseId: m.parent_tool_use_id,
+					replay: true,
+					synthetic: isSyntheticUserText(message) ? true : void 0,
+					uuid: m.uuid
+				});
+			} else if (m.type === "assistant") this.#emit({
 				type: "assistant_message",
 				message: toApiMessage(m.message),
 				parentToolUseId: m.parent_tool_use_id,
@@ -690,7 +931,7 @@ var SessionRunner = class {
 	#buildOptions() {
 		const c = this.#config;
 		return {
-			cwd: c.cwd,
+			cwd: this.#cwd,
 			permissionMode: c.permissionMode,
 			allowedTools: c.allowedTools,
 			disallowedTools: c.disallowedTools,
@@ -733,6 +974,7 @@ var SessionRunner = class {
 			this.#fetchCapabilities();
 			this.#fetchContextUsage();
 			this.#fetchRateLimits();
+			this.#fetchEngineTitle();
 			return;
 		}
 		if (msg.type === "system" && msg.subtype === "session_state_changed") {
@@ -744,12 +986,17 @@ var SessionRunner = class {
 		const body = normalizeSdkMessage(msg);
 		if (body) {
 			this.#emit(body);
+			if (body.type === "conversation_reset") {
+				if (body.sdkSessionId) this.#sdkSessionId = body.sdkSessionId;
+				this.#fetchContextUsage();
+			}
 			if (body.type === "turn_result") {
 				this.#totalCostUsd = body.totalCostUsd;
 				this.#numTurns = body.numTurns;
 				if (this.#pending.size === 0) this.#setStatus("idle");
 				this.#fetchContextUsage();
 				this.#fetchRateLimits();
+				this.#fetchEngineTitle();
 			}
 		}
 	}
@@ -779,6 +1026,44 @@ var SessionRunner = class {
 			});
 		} catch {}
 	}
+	/**
+	* Adopt the title the CLI gave this thread — the "friendly title" it writes a
+	* turn or two into a session, and the name a resumed thread already carries.
+	*
+	* A **poll, not an observation**, and unavoidably so: no member of the SDK's
+	* `SDKMessage` union carries it (the whole union was checked). It lives on
+	* `SDKSessionInfo`, which only `getSessionInfo` / `listSessions` return — the
+	* same record `GET /sdk-sessions` already serves as `SdkSessionSummary`. So it
+	* is read at init and after each turn, which is also roughly the rate at which
+	* it changes.
+	*
+	* Two rules:
+	* - **Never while `meta.title` is set.** A rename is a person's decision and a
+	*   generated summary must not overwrite it. Not read at all in that case, so
+	*   there is no stored value waiting to resurface if the rename is cleared —
+	*   the next turn simply fetches it again.
+	* - `summary` falls back to the first prompt when the session has no real
+	*   title yet, so it is taken only when it *differs* from `firstPrompt`.
+	*   Otherwise `#title()`'s own prompt fallback covers it, and the two would
+	*   disagree only in how they truncate.
+	*
+	* Best-effort throughout: an unreadable transcript, a session file that is not
+	* there yet, an SDK without the function — all leave the title as it was.
+	*/
+	async #fetchEngineTitle() {
+		const metaTitle = this.#config.meta?.title;
+		if (typeof metaTitle === "string" && metaTitle.length > 0) return;
+		const sdkSessionId = this.#sdkSessionId;
+		if (!sdkSessionId) return;
+		const read = this.#config.sessionInfoFn ?? getSessionInfo;
+		try {
+			const info = await read(sdkSessionId, { dir: this.#cwd });
+			if (this.#closed || !info) return;
+			const summary = info.summary && info.summary !== info.firstPrompt ? info.summary : void 0;
+			const title = info.customTitle || summary;
+			if (title) this.#engineTitle = title;
+		} catch {}
+	}
 	/** Snapshot the context window after a turn and surface it as an event. Optional-chained
 	* and best-effort for the same reasons as #fetchCapabilities. */
 	async #fetchContextUsage() {
@@ -960,6 +1245,7 @@ var SessionRunner = class {
 		};
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
+		if (body.type === "conversation_reset") this.#resetSeq = event.seq;
 		this.#events.push(event);
 		for (const listener of this.#listeners) try {
 			listener(event);
@@ -981,7 +1267,7 @@ function recommendedAnswers(input) {
 	return answers;
 }
 //#endregion
-//#region src/ai-sdk-runner.ts
+//#region src/engines/provider/runner.ts
 /** Permission modes this engine can honor. The rest of the protocol vocabulary
 * (acceptEdits/plan/auto) is Claude Code CLI semantics with no meaning here —
 * setPermissionMode rejects them, which the server surfaces as protocol_error. */
@@ -1099,7 +1385,7 @@ var AiSdkRunner = class {
 		return {
 			id: this.id,
 			status: this.#status,
-			cwd: this.#config.cwd ?? process.cwd(),
+			cwd: this.#config.cwd ?? "",
 			profile: this.#config.profile,
 			engine: "provider",
 			capabilities: ENGINE_CAPABILITIES.provider,
@@ -1110,6 +1396,7 @@ var AiSdkRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: 0,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			numTurns: this.#numTurns || void 0,
 			lastActivityAt: this.#lastActivityAt
@@ -1351,8 +1638,13 @@ var AiSdkRunner = class {
 			Promise.resolve(this.#config.onClose?.()).catch(() => {});
 		} catch {}
 	}
-	subscribe(listener, afterSeq = 0) {
-		for (const event of this.#events) if (event.seq > afterSeq) listener(event);
+	subscribe(listener, afterSeq = 0, options) {
+		const stale = options?.coalesceReplay ? staleReplaySeqs(this.#events, afterSeq) : void 0;
+		for (const event of this.#events) {
+			if (event.seq <= afterSeq) continue;
+			if (stale?.has(event.seq)) continue;
+			listener(event);
+		}
 		this.#listeners.add(listener);
 		return () => this.#listeners.delete(listener);
 	}
@@ -1483,29 +1775,29 @@ var AiSdkRunner = class {
 			cacheWrite: 0,
 			cacheRead: 0
 		};
+		let blocks = [];
+		const textBuf = /* @__PURE__ */ new Map();
+		const reasoningBuf = /* @__PURE__ */ new Map();
+		const flush = () => {
+			if (blocks.length === 0) return;
+			this.#emit({
+				type: "assistant_message",
+				message: {
+					role: "assistant",
+					content: blocks,
+					model: this.#modelId()
+				},
+				parentToolUseId: null,
+				uuid: randomUUID()
+			});
+			blocks = [];
+		};
 		try {
 			const result = await agent.stream({
 				messages: [...this.#messages],
 				abortSignal: abort.signal
 			});
 			const partials = this.#config.includePartialMessages !== false;
-			let blocks = [];
-			const textBuf = /* @__PURE__ */ new Map();
-			const reasoningBuf = /* @__PURE__ */ new Map();
-			const flush = () => {
-				if (blocks.length === 0) return;
-				this.#emit({
-					type: "assistant_message",
-					message: {
-						role: "assistant",
-						content: blocks,
-						model: this.#modelId()
-					},
-					parentToolUseId: null,
-					uuid: randomUUID()
-				});
-				blocks = [];
-			};
 			const emitToolResult = (toolCallId, content, isError) => {
 				flush();
 				this.#emit({
@@ -1635,6 +1927,15 @@ var AiSdkRunner = class {
 			this.#finishTurn(text);
 		} catch (error) {
 			if (this.#closed) return;
+			for (const [, thinking] of reasoningBuf) if (thinking) blocks.push({
+				type: "thinking",
+				thinking
+			});
+			for (const [, text] of textBuf) if (text) blocks.push({
+				type: "text",
+				text
+			});
+			flush();
 			const message = error instanceof Error ? error.message : String(error);
 			this.#numTurns += 1;
 			this.#emit({
@@ -1694,6 +1995,17 @@ var AiSdkRunner = class {
 		if (!prompt) return void 0;
 		return prompt.length > 80 ? prompt.slice(0, 77) + "…" : prompt;
 	}
+	/**
+	* This session's MCP servers, as the host assembled them.
+	*
+	* Always answers — an empty list when no MCP was wired — because the
+	* alternative (undefined, which the server turns into a 501) says "this
+	* engine cannot tell you", and this engine can: the host that built the
+	* session is the only party who knows, and it has been asked.
+	*/
+	async mcpServers() {
+		return await this.#config.reportMcpServers?.() ?? [];
+	}
 	/** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
 	* it (undefined) restores the derived title. The engine is never told. */
 	setTitle(title) {
@@ -1744,7 +2056,7 @@ function errorText(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
-//#region src/claude-auth.ts
+//#region src/engines/claude/auth.ts
 /**
 * The native Claude Code binary the Agent SDK itself spawns, resolved the way
 * the SDK resolves it: the platform-specific optional dependency installed next
@@ -1798,7 +2110,7 @@ function checkClaudeAuth(env, options = {}) {
 	});
 }
 //#endregion
-//#region src/quickjs-executor.ts
+//#region src/executors/quickjs-executor.ts
 /**
 * In-process execution backend: runs a tool's untrusted script in the QuickJS
 * WASM guest. Always settles inline — nothing downstream assumes that, which is
@@ -1896,7 +2208,7 @@ function isHostAllowed(url, allowedHosts) {
 	});
 }
 //#endregion
-//#region src/pending-registry.ts
+//#region src/lib/pending-registry.ts
 var PendingRequestRegistry = class {
 	#slots = /* @__PURE__ */ new Map();
 	get size() {
@@ -2003,7 +2315,7 @@ function toEntry(slot) {
 	};
 }
 //#endregion
-//#region src/browser-bridge-executor.ts
+//#region src/executors/browser-bridge-executor.ts
 /**
 * Executes tool calls in the attached client's own sandbox. The first backend
 * that genuinely returns `pending`: dispatch puts a request on the wire and
@@ -2114,7 +2426,7 @@ function toExecutionResult(outcome) {
 	};
 }
 //#endregion
-//#region src/deferred-executor.ts
+//#region src/executors/deferred-executor.ts
 /**
 * The executor for work that outlives the session's process residency: dispatch
 * hands the call off and returns `pending` **without holding a promise**, because
@@ -2161,7 +2473,7 @@ var DeferredExecutor = class {
 	}
 };
 //#endregion
-//#region src/tools.ts
+//#region src/engines/provider/tools.ts
 const MAX_FILE_BYTES = 1024 * 1024;
 /**
 * Build the capability-scoped tool set for a session.
@@ -2327,28 +2639,57 @@ function createToolContext(options) {
 /** Add host-side MCP tools to a context. They are ALWAYS authoritative: they run
 * server-side with server credentials, and must never be handed to a browser. */
 function withMcpTools(context, mcpTools) {
+	return withHostTools(context, Object.fromEntries(Object.entries(mcpTools).map(([name, mcpTool]) => [name, {
+		tool: mcpTool,
+		trust: "authoritative"
+	}])), "MCP tool");
+}
+/**
+* Add host-supplied tools to a context at an explicit trust level.
+*
+* The trust level is the whole point of the seam: {@link withMcpTools} can only
+* produce authoritative tools, so a host tool that *should* be sandboxed — and
+* therefore executable in the browser tab that asked for it — had no way to be
+* expressed at all. Here the host says which it is, and the contradictions are
+* refused rather than silently resolved:
+*
+* - a `sandboxed` tool carrying `execute` would run inline in this process with
+*   the gateway's ambient authority, which is exactly what sandboxing it was
+*   meant to prevent;
+* - an `authoritative` tool *without* `execute` would park the turn on a call no
+*   executor claims, and the session would simply stop.
+*/
+function withHostTools(context, hostTools, kind = "host tool") {
+	const entries = Object.entries(hostTools);
+	if (entries.length === 0) return context;
 	const definitions = [...context.definitions];
 	const tools = { ...context.tools };
-	for (const [name, mcpTool] of Object.entries(mcpTools)) {
-		if (context.sandboxedToolNames.includes(name)) throw new Error(`MCP tool '${name}' collides with a sandboxed tool of the same name`);
+	const sandboxedToolNames = [...context.sandboxedToolNames];
+	for (const [name, { tool: hostTool, trust }] of entries) {
+		if (name in tools) throw new Error(`${kind} '${name}' collides with an existing tool of the same name`);
+		const executes = typeof hostTool.execute === "function";
+		if (trust === "sandboxed" && executes) throw new Error(`${kind} '${name}' is declared sandboxed but has an \`execute\` — it would run in this process with full authority. Drop \`execute\` so it rides the ToolExecutor seam.`);
+		if (trust === "authoritative" && !executes) throw new Error(`${kind} '${name}' is declared authoritative but has no \`execute\` — nothing would ever answer its calls and the turn would stall.`);
 		definitions.push({
 			name,
-			trust: "authoritative",
-			tool: mcpTool
+			trust,
+			tool: hostTool
 		});
-		tools[name] = mcpTool;
+		tools[name] = hostTool;
+		if (trust === "sandboxed") sandboxedToolNames.push(name);
 	}
 	return {
 		...context,
 		tools,
-		definitions
+		definitions,
+		sandboxedToolNames
 	};
 }
 function truncate(text) {
 	return text.length > MAX_FILE_BYTES ? text.slice(0, MAX_FILE_BYTES) : text;
 }
 //#endregion
-//#region src/web-fetch.ts
+//#region src/engines/provider/web-fetch.ts
 const MAX_CACHE_ENTRIES = 64;
 const MAX_REDIRECTS = 5;
 function createWebFetch(options = {}) {
@@ -2560,7 +2901,7 @@ function decodeEntities(text) {
 	return text.replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code))).replace(/&#x([\da-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16))).replace(/&nbsp;/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;|&apos;/g, "'").replace(/&amp;/g, "&");
 }
 //#endregion
-//#region src/engine.ts
+//#region src/engines/provider/session.ts
 /** Which capability a wired backend yields, for grant filtering. */
 const CAPABILITY_TOOLS = {
 	search: "web_search",
@@ -2581,7 +2922,7 @@ const CAPABILITY_TOOLS = {
 * the host wired, which is what a host that ignores profiles gets.
 */
 function createEngineSession(options) {
-	const vfs = options.config.vfs ?? createVfs(options.config.restore?.vfs);
+	const vfs = options.config.vfs ?? createVfs(options.config.restore ? options.config.restore.vfs : options.seedVfs);
 	const executor = options.selectExecutor();
 	const granted = options.config.capabilities ?? options.profile?.session?.capabilities;
 	const isGranted = (key) => granted === void 0 || granted.includes(CAPABILITY_TOOLS[key]);
@@ -2602,8 +2943,12 @@ function createEngineSession(options) {
 		webFetch,
 		onFileDelivered: options.capabilities?.deliverFiles === false || !isGranted("deliverFiles") ? void 0 : (file) => runner?.emitFileDelivered(file)
 	});
-	const mcpTools = selectMcpTools(options.mcpTools, options.profile?.session?.mcpServers);
-	const context = mcpTools ? withMcpTools(base, mcpTools) : base;
+	const declaredServers = options.profile?.session?.mcpServers;
+	const connected = options.mcp?.tools ?? options.mcpTools;
+	requireDeclaredServers(options.profile?.name ?? "(unnamed)", declaredServers, options.mcp, connected);
+	const mcpTools = selectMcpTools(connected, declaredServers);
+	const withMcp = mcpTools ? withMcpTools(base, mcpTools) : base;
+	const context = options.tools ? withHostTools(withMcp, options.tools) : withMcp;
 	runner = new AiSdkRunner({
 		...options.config,
 		languageModel: options.resolveModel(options.profile, options.config),
@@ -2613,11 +2958,42 @@ function createEngineSession(options) {
 		executor,
 		executableTools: context.sandboxedToolNames,
 		executionBackend: options.backend ?? "server",
-		executionLimits: options.executionLimits
-	});
+		executionLimits: options.executionLimits,
+		reportMcpServers: options.mcp ? () => Promise.resolve(declaredServers === void 0 ? options.mcp.servers : options.mcp.servers.filter((s) => declaredServers.includes(s.name))) : void 0
+	}, options.id);
 	return runner;
 }
 /**
+* Refuse to build a session whose profile names an MCP server that isn't there.
+*
+* A profile's `mcpServers` list is a **declaration**, not a filter: an embedder
+* who wrote it meant the agent to have those tools. Honouring it partially is
+* the worst failure mode this engine has — the session starts, reports healthy,
+* and the agent apologises its way through every request that needed the server,
+* with one warning line in a log nobody is reading.
+*
+* With a {@link McpConnection} the check is exact (did this server connect?).
+* With a bare tool set all we can see is whether any tool carries the server's
+* namespace, so a genuinely tool-less server would trip it — the fix there is to
+* pass `mcp` rather than to weaken this.
+*/
+function requireDeclaredServers(profileName, declared, mcp, tools) {
+	if (!declared || declared.length === 0) return;
+	const missing = declared.filter((name) => {
+		if (mcp) {
+			const server = mcp.servers.find((s) => s.name === name);
+			return !server || server.status !== "connected";
+		}
+		return !Object.keys(tools ?? {}).some((tool) => tool.split("__")[0] === name);
+	});
+	if (missing.length === 0) return;
+	const reasons = missing.map((name) => {
+		const error = mcp?.servers.find((s) => s.name === name)?.error;
+		return error ? `${name} (${error})` : name;
+	}).join(", ");
+	throw new Error(`profile '${profileName}' declares MCP server(s) that are not connected: ${reasons}. A session missing a declared server is a session whose agent silently cannot do its job.`);
+}
+/**
 * Restrict a connected tool set to the MCP servers a profile grants, by the
 * `<server>__<tool>` namespace {@link connectMcpTools} assigns. Undefined `servers`
 * = no declaration, so every connected server passes through.
@@ -2637,31 +3013,88 @@ function selectMcpTools(tools, servers) {
 * Server-side only, with server credentials: these tools are authoritative and
 * must never be bridged to a browser. `@ai-sdk/mcp` is imported lazily and is an
 * optional dependency — an operator who wires no MCP servers never needs it.
+*
+* **A stateless MCP server must answer `GET` with 405.** The client opens the
+* SSE stream with a `GET` before it sends anything, and a POST-only server
+* mounted under a framework's default 404 makes the whole connect fail with an
+* error that names neither the method nor the route. This is the single most
+* common way an otherwise-correct MCP mount fails.
 */
 async function connectMcpTools(servers, options = {}) {
 	const entries = Object.entries(servers);
 	if (entries.length === 0) return {
 		tools: {},
+		servers: [],
 		close: async () => {}
 	};
 	const { createMCPClient } = await import("@ai-sdk/mcp");
 	const clients = [];
 	const tools = {};
-	for (const [name, server] of entries) try {
-		const client = await createMCPClient({
-			transport: toTransport(server),
-			onUncaughtError: (error) => options.onError?.(name, error)
-		});
-		clients.push(client);
-		for (const [toolName, mcpTool] of Object.entries(await client.tools())) tools[`${name}__${toolName}`] = mcpTool;
-	} catch (error) {
-		options.onError?.(name, error);
+	const statuses = [];
+	const closeAll = async () => {
+		await Promise.allSettled(clients.map((c) => c.close()));
+	};
+	for (const [name, server] of entries) {
+		const identity = describeServer(server);
+		try {
+			const client = await createMCPClient({
+				transport: toTransport(server),
+				onUncaughtError: (error) => options.onError?.(name, error)
+			});
+			clients.push(client);
+			const connected = await client.tools();
+			for (const [toolName, mcpTool] of Object.entries(connected)) tools[`${name}__${toolName}`] = mcpTool;
+			statuses.push({
+				name,
+				status: "connected",
+				...identity,
+				tools: Object.entries(connected).map(([toolName, mcpTool]) => toToolInfo(toolName, mcpTool))
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			statuses.push({
+				name,
+				status: "failed",
+				error: message,
+				...identity
+			});
+			options.onError?.(name, error);
+			if (options.required) {
+				await closeAll();
+				throw new Error(`MCP server '${name}' failed to connect: ${message}`);
+			}
+		}
 	}
 	return {
 		tools,
-		close: async () => {
-			await Promise.allSettled(clients.map((c) => c.close()));
-		}
+		servers: statuses,
+		close: closeAll
+	};
+}
+/** The connection's identity, minus its secrets — `headers` never travel. */
+function describeServer(server) {
+	if ("url" in server) return {
+		transport: server.type === "sse" ? "sse" : "http",
+		url: server.url
+	};
+	return {
+		transport: "stdio",
+		command: server.command,
+		args: server.args
+	};
+}
+/**
+* The AI SDK hands back its own `Tool`, whose `inputSchema` may be a zod schema
+* or a `jsonSchema()` wrapper. Only the latter carries a JSON Schema document,
+* so that is the only case where parameters are reported — `McpServerToolInfo`
+* models the absence deliberately, and inventing one here would be worse.
+*/
+function toToolInfo(name, mcpTool) {
+	const { description, inputSchema } = mcpTool ?? {};
+	return {
+		name,
+		description: typeof description === "string" ? description : void 0,
+		inputSchema: inputSchema?.jsonSchema
 	};
 }
 /**
@@ -2797,9 +3230,9 @@ const claudeAdapter = {
 		};
 		return { available: "unknown" };
 	},
-	createRunner({ config, restore }) {
+	createRunner({ config, restore, id }) {
 		if (restore) throw new Error("the Claude engine cannot rebuild a parked session");
-		return new SessionRunner(config);
+		return new SessionRunner(config, id);
 	},
 	/**
 	* The Agent SDK's on-disk session store, mapped browser-safe. The SDK reads
@@ -3177,15 +3610,29 @@ function userQuestionsFromCodex(questions) {
 		}))
 	}));
 }
-/** 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. */
+/**
+* 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 — so they are named rather than
+* dropped. A prompt that was *only* an image used to produce an empty string,
+* which the caller read as "nothing to replay" and skipped: the turn lost its
+* user row and, with it, the prompt mark the scrubber navigates by, so a resumed
+* thread had answers with no visible question. A word in place of the picture is
+* a smaller lie than a turn that never happened.
+*/
 function historyUserText(item) {
 	if (!Array.isArray(item.content)) return "";
-	return item.content.map((part) => {
+	let images = 0;
+	const text = item.content.map((part) => {
 		const candidate = part;
-		return candidate?.type === "text" && typeof candidate.text === "string" ? candidate.text : "";
+		if (candidate?.type === "text" && typeof candidate.text === "string") return candidate.text;
+		if (typeof candidate?.type === "string" && candidate.type.toLowerCase().includes("image")) images += 1;
+		return "";
 	}).filter(Boolean).join("\n");
+	if (text) return text;
+	return images > 0 ? `[${images === 1 ? "image" : `${images} images`}]` : "";
 }
 /** The AskUserQuestion answer convention (question text → chosen label(s),
 * comma-joined) mapped back to codex's id-keyed shape. Questions the client
@@ -3345,6 +3792,8 @@ var CodexRunner = class {
 	id;
 	createdAt;
 	#config;
+	/** {@link CodexRunnerConfig.cwd}, checked once in the constructor. */
+	#cwd;
 	#events = [];
 	#listeners = /* @__PURE__ */ new Set();
 	#seq = 0;
@@ -3407,6 +3856,8 @@ var CodexRunner = class {
 		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");
+		if (!config.cwd) throw new Error("the codex engine requires a cwd");
+		this.#cwd = config.cwd;
 		this.#config = config;
 		this.#permissionMode = mode;
 		this.#model = config.model;
@@ -3442,7 +3893,7 @@ var CodexRunner = class {
 			id: this.id,
 			sdkSessionId: this.#sdkSessionId,
 			status: this.#status,
-			cwd: this.#config.cwd,
+			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "codex",
 			capabilities: ENGINE_CAPABILITIES.codex,
@@ -3454,6 +3905,7 @@ var CodexRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: this.#approvals.size,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			totalCostUsd: this.#totalCostUsd,
 			numTurns: this.#numTurns || void 0,
@@ -3684,8 +4136,13 @@ var CodexRunner = class {
 		});
 		this.#setStatus("closed");
 	}
-	subscribe(listener, afterSeq = 0) {
-		for (const event of this.#events) if (event.seq > afterSeq) listener(event);
+	subscribe(listener, afterSeq = 0, options) {
+		const stale = options?.coalesceReplay ? staleReplaySeqs(this.#events, afterSeq) : void 0;
+		for (const event of this.#events) {
+			if (event.seq <= afterSeq) continue;
+			if (stale?.has(event.seq)) continue;
+			listener(event);
+		}
 		this.#listeners.add(listener);
 		return () => this.#listeners.delete(listener);
 	}
@@ -3738,7 +4195,7 @@ var CodexRunner = class {
 		}
 		if (!this.#threadLoaded) {
 			const options = {
-				cwd: this.#config.cwd,
+				cwd: this.#cwd,
 				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
 				sandbox: THREAD_SANDBOX_BY_MODE[this.#permissionMode]
 			};
@@ -3779,7 +4236,7 @@ var CodexRunner = class {
 		if (this.#skillsRefresh) return this.#skillsRefresh;
 		const run = (async () => {
 			try {
-				const result = await connection.request("skills/list", { cwds: [this.#config.cwd] });
+				const result = await connection.request("skills/list", { cwds: [this.#cwd] });
 				if (this.#closed) return;
 				const entries = Array.isArray(result?.data) ? result.data : [];
 				const seen = /* @__PURE__ */ new Set();
@@ -3981,7 +4438,7 @@ var CodexRunner = class {
 			const params = {
 				threadId: this.#sdkSessionId,
 				input: turn.input,
-				cwd: this.#config.cwd,
+				cwd: this.#cwd,
 				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
 				sandboxPolicy: TURN_SANDBOX_BY_MODE[this.#permissionMode]
 			};
@@ -4012,131 +4469,137 @@ var CodexRunner = class {
 	}
 	#handleNotification(method, params) {
 		if (this.#closed) return;
+		this.#notifications[method]?.(params);
+	}
+	/** Reasoning deltas arrive on two methods that differ only in which section
+	* counter they advance; the section key carries the method so the two streams
+	* never share a boundary. Section boundaries (a new summary/content entry)
+	* render as paragraph breaks — the completed item joins sections with '\n\n'. */
+	#reasoningDelta(method) {
+		return (params) => {
+			const active = this.#activeTurn;
+			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
+			});
+		};
+	}
+	/** One item-progress handler serves `item/started` and `item/updated`. */
+	#itemProgress = (params) => {
 		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 "mcpServer/startupStatus/updated": {
-				const update = params;
-				if (typeof update?.name !== "string") return;
-				this.#mcpStatus.set(update.name, {
-					status: typeof update.status === "string" ? update.status : "starting",
-					...update.error ? { error: update.error } : {},
-					...update.failureReason ? { failureReason: update.failureReason } : {}
-				});
-				return;
-			}
-			case "skills/changed": {
-				const connection = this.#connection;
-				if (connection) this.#refreshSkills(connection);
-				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;
+		if (!active) return;
+		const item = params?.item;
+		if (item) this.#handleItemProgress(item, active);
+	};
+	/** The notification dispatch table — every method the child emits that this
+	* runner maps, in one place. Handlers read `this.#activeTurn` themselves:
+	* dispatch is synchronous, so the read is the same one the old switch made. */
+	#notifications = {
+		"thread/started": (params) => {
+			const thread = params?.thread;
+			if (typeof thread?.id === "string") this.#sdkSessionId = thread.id;
+		},
+		"turn/started": (params) => {
+			const active = this.#activeTurn;
+			const turn = params?.turn;
+			if (active && turn && !active.turnId) active.turnId = turn.id;
+		},
+		"turn/completed": (params) => {
+			const active = this.#activeTurn;
+			const turn = params?.turn;
+			if (active && turn) active.resolve(turn);
+		},
+		"item/started": this.#itemProgress,
+		"item/updated": this.#itemProgress,
+		"item/completed": (params) => {
+			const active = this.#activeTurn;
+			if (!active) return;
+			const item = params?.item;
+			if (item) this.#handleItemCompleted(item, active);
+		},
+		"item/agentMessage/delta": (params) => {
+			if (!this.#activeTurn) return;
+			const delta = params?.delta;
+			if (typeof delta === "string" && delta) this.#emitDelta({
+				type: "text_delta",
+				text: delta
+			});
+		},
+		"item/reasoning/textDelta": this.#reasoningDelta("item/reasoning/textDelta"),
+		"item/reasoning/summaryTextDelta": this.#reasoningDelta("item/reasoning/summaryTextDelta"),
+		"thread/tokenUsage/updated": (params) => {
+			const active = this.#activeTurn;
+			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;
+		},
+		"mcpServer/startupStatus/updated": (params) => {
+			const update = params;
+			if (typeof update?.name !== "string") return;
+			this.#mcpStatus.set(update.name, {
+				status: typeof update.status === "string" ? update.status : "starting",
+				...update.error ? { error: update.error } : {},
+				...update.failureReason ? { failureReason: update.failureReason } : {}
+			});
+		},
+		"skills/changed": () => {
+			const connection = this.#connection;
+			if (connection) this.#refreshSkills(connection);
+		},
+		"account/rateLimits/updated": (params) => {
+			this.#emitRateLimits(params?.rateLimits);
+		},
+		"turn/plan/updated": (params) => {
+			const active = this.#activeTurn;
+			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"
+					}))
 				}
+			});
+		},
+		"serverRequest/resolved": (params) => {
+			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;
 			}
-			case "error": {
-				const error = params?.error;
-				if (active && typeof error?.message === "string") active.lastError = error.message;
-				return;
-			}
-			default: return;
+		},
+		"error": (params) => {
+			const active = this.#activeTurn;
+			const error = params?.error;
+			if (active && typeof error?.message === "string") active.lastError = error.message;
 		}
-	}
+	};
 	/** 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). */
@@ -4282,83 +4745,89 @@ var CodexRunner = class {
 	}
 	#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;
+		const handler = this.#itemCompleted[item.type];
+		if (handler) {
+			handler(item, active, id);
+			return;
+		}
+		const unknown = item;
+		this.#emit({
+			type: "sdk_event",
+			payload: {
+				type: `codex.${unknown.type}`,
+				item: unknown
 			}
-			case "webSearch":
-				this.#emitToolUse(id, "CodexWebSearch", { query: item.query });
-				this.#emitToolResult(id, "", false);
-				return;
-			case "imageGeneration": {
+		});
+	}
+	/**
+	* The completed-item mapping, one handler per member of the {@link AppServerItem}
+	* union. The mapped type is the invariant made checkable: model a new item
+	* type in `types.ts` and this table fails to compile until it says what the
+	* item becomes on the wire — the old switch silently fell through to the
+	* unknown-item passthrough instead. (The runtime still receives types the
+	* union has never heard of; those take the passthrough above.)
+	*/
+	#itemCompleted = {
+		userMessage: () => {},
+		agentMessage: (item, active, id) => {
+			const text = typeof item.text === "string" ? item.text : "";
+			this.#emitAssistant(id, [{
+				type: "text",
+				text
+			}]);
+			active.finalText = text;
+		},
+		reasoning: (item, _active, id) => {
+			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
+			}]);
+		},
+		commandExecution: (item, active, id) => {
+			if (!active.toolUseEmitted.has(id)) {
 				active.toolUseEmitted.add(id);
-				this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
-				if (item.savedPath) this.#emitFileProduced(item.savedPath, id);
-				const lines = [item.savedPath ? `Saved to ${item.savedPath}` : "No saved path reported", ...shortResult(item.result) ? [item.result] : []];
-				this.#emitToolResult(id, lines.join("\n"), item.status === "failed");
-				return;
+				this.#emitToolUse(id, "CodexCommand", { command: item.command });
 			}
-			case "imageView":
-				this.#emitToolUse(id, "CodexImageView", { path: item.path });
-				this.#emitToolResult(id, item.path, false);
-				return;
-			default: {
-				const unknown = item;
-				this.#emit({
-					type: "sdk_event",
-					payload: {
-						type: `codex.${unknown.type}`,
-						item: unknown
-					}
-				});
+			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);
+		},
+		fileChange: (item, _active, id) => {
+			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}`;
+			});
+			const only = item.changes.length === 1 ? item.changes[0] : void 0;
+			this.#emitToolResult(id, lines.join("\n") || item.status, item.status === "failed" || item.status === "declined", only?.diff ? parseUnifiedDiff(only.diff, only.path) : void 0);
+		},
+		mcpToolCall: (item, active, id) => {
+			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);
+		},
+		webSearch: (item, _active, id) => {
+			this.#emitToolUse(id, "CodexWebSearch", { query: item.query });
+			this.#emitToolResult(id, "", false);
+		},
+		imageGeneration: (item, active, id) => {
+			active.toolUseEmitted.add(id);
+			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
+			if (item.savedPath) this.#emitFileProduced(item.savedPath, id);
+			const lines = [item.savedPath ? `Saved to ${item.savedPath}` : "No saved path reported", ...shortResult(item.result) ? [item.result] : []];
+			this.#emitToolResult(id, lines.join("\n"), item.status === "failed");
+		},
+		imageView: (item, _active, id) => {
+			this.#emitToolUse(id, "CodexImageView", { path: item.path });
+			this.#emitToolResult(id, item.path, false);
 		}
-	}
+	};
 	#emitDelta(delta) {
 		if (this.#config.includePartialMessages === false) return;
 		this.#emit({
@@ -4400,7 +4869,7 @@ var CodexRunner = class {
 			uuid: `${id}-use`
 		});
 	}
-	#emitToolResult(toolUseId, content, isError) {
+	#emitToolResult(toolUseId, content, isError, patch) {
 		this.#emit({
 			type: "user_message",
 			message: {
@@ -4414,6 +4883,7 @@ var CodexRunner = class {
 			},
 			parentToolUseId: null,
 			synthetic: true,
+			patch,
 			uuid: `${toolUseId}-result`
 		});
 	}
@@ -4905,7 +5375,7 @@ const codexAdapter = {
 	capabilities: ENGINE_CAPABILITIES.codex,
 	catalog: CODEX_CATALOG,
 	checkAvailability: (profile, env) => checkCodexAvailability(profile, env),
-	createRunner({ config, profile, restore }) {
+	createRunner({ config, profile, restore, id }) {
 		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);
@@ -4916,7 +5386,7 @@ const codexAdapter = {
 				executable,
 				...options
 			})
-		});
+		}, id);
 	},
 	async listSessions(options) {
 		const executable = resolveBundledCodexExecutable();
@@ -4976,6 +5446,6 @@ 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 };
+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, withHostTools, withMcpTools };
 
 //# sourceMappingURL=index.mjs.map