@workerdeck/core 0.16.0 → 0.18.0

package/build/index.mjs

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
 import { getSessionInfo, getSessionMessages, listSessions, query } from "@anthropic-ai/claude-agent-sdk";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, replayCoalesceKey, transcriptActivity, transcriptContent } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, contextReading, imagePartRef, replayCoalesceKey, replayRetains, snapshotRetains, 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";
+import { appendFileSync, existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createVfs, runScript } from "@workerdeck/sandbox";
 import { z } from "zod";
 import { lookup } from "node:dns/promises";
@@ -593,6 +593,496 @@ function staleReplaySeqs(events, afterSeq) {
 	}
 	return stale;
 }
+/**
+* The one replay body, and what a socket receives from it.
+*
+* Every runner had a byte-identical copy of this loop — three spellings of four
+* rules, one of which ("never drop the highest-seq event, whatever the rule
+* says") is load-bearing and was three copies of a comment. Not a base class:
+* the runners share nothing else, and a base class would have to own `#emit`,
+* the most engine-specific method each of them has.
+*
+* The rules, in the order they are applied:
+*
+* 1. `afterSeq` — the caller already holds everything at or below it.
+* 2. `resetSeq` — transcript *content* strictly below the latest
+*    `conversation_reset` is skipped, so a re-attach cannot resurrect a cleared
+*    conversation while state events still replay. Claude's alone; the other
+*    engines pass 0.
+* 3. `coalesceReplay` — last-write-wins state readings superseded later in the
+*    same replay (`staleReplaySeqs`), plus everything `replayRetains` says the
+*    reducer reads and discards. Opt-in, and only sound for a consumer whose
+*    handling of those events is last-write-wins.
+* 4. `imageRefs` — a base64 image part is delivered as an `image_ref` address
+*    (protocol's {@link imagePartRef}), its bytes one REST fetch away. Applied
+*    **before** rule 5, because it stamps indices from the stored part array
+*    which rule 5 then reshapes. Unlike rule 5 this also applies to the live
+*    path (see `SubscriberSet`), which is the one place these two rules differ.
+* 5. `truncateResults` — a huge `tool_result` block is delivered as its head
+*    plus the markers that say so. **Never mutates the stored event**: the live
+*    path, the parking snapshot and the fetch route all need the whole thing,
+*    so this builds a copy and the log stays the log.
+*
+* The highest-seq event is delivered whatever rules 2 and 3 say — a client's
+* replay hold waits for `state.lastSeq` to reach the attach's and would
+* otherwise hang forever — but it is still *truncated* when rule 4 applies. A
+* session that ends on a `find /` puts its 641 KB frame exactly there.
+*/
+function replaySlice(events, options) {
+	const { afterSeq, resetSeq = 0, coalesceReplay, truncateResults, imageRefs } = options;
+	const stale = coalesceReplay ? staleReplaySeqs(events, afterSeq) : void 0;
+	const lastSeq = events[events.length - 1]?.seq ?? 0;
+	const out = [];
+	for (const event of events) {
+		if (event.seq <= afterSeq) continue;
+		if (event.seq < resetSeq && transcriptContent(event)) continue;
+		if (stale?.has(event.seq)) continue;
+		if (coalesceReplay && event.seq !== lastSeq && !replayRetains(event)) continue;
+		let delivered = event;
+		if (imageRefs) delivered = refImageParts(delivered);
+		if (truncateResults) delivered = truncateResultBlocks(delivered);
+		out.push(delivered);
+	}
+	return out;
+}
+/**
+* A copy of `event` whose oversized `tool_result` blocks carry their head and
+* say so — or `event` itself, unchanged and un-copied, when nothing is over the
+* budget. That identity matters: an attach is mostly small events, and a fresh
+* object for every one of them would cost more than the feature saves.
+*
+* Blocks are measured and cut **individually**. A message answering three calls
+* where one is a `find /` keeps the two small results whole, which is what makes
+* the per-block marker (rather than a per-event one) honest.
+*/
+function truncateResultBlocks(event) {
+	if (event.type !== "user_message") return event;
+	const content = event.message.content;
+	if (!Array.isArray(content)) return event;
+	let cut = false;
+	const blocks = content.map((block) => {
+		if (block.type !== "tool_result") return block;
+		const result = block;
+		if (result.truncated) return block;
+		const total = resultChars(result.content);
+		if (total <= TOOL_RESULT_HEAD_CHARS) return block;
+		cut = true;
+		return {
+			...result,
+			content: headOf(result.content, TOOL_RESULT_HEAD_CHARS),
+			truncated: true,
+			total_chars: total
+		};
+	});
+	if (!cut) return event;
+	return {
+		...event,
+		message: {
+			...event.message,
+			content: blocks
+		}
+	};
+}
+/** Characters in a result's content, in the same terms a reader sees it: the
+* string itself, or every text part of a block list joined by newlines — which
+* is exactly what `blockText` in the reducer builds. Non-text parts (an image
+* block) contribute nothing, because they are not what is large here and
+* slicing them would corrupt them. */
+function resultChars(content) {
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	return content.reduce((total, part, index) => total + (typeof part.text === "string" ? part.text.length + (index > 0 ? 1 : 0) : 0), 0);
+}
+/** The first `chars` characters, in the content's own shape — a string stays a
+* string, a block list stays a block list (cut at the part that crosses the
+* budget, with the remaining parts dropped). Shape-preserving on purpose: the
+* reducer, both renderers and the copy button all read this the same way they
+* read a whole one, so truncation is a shorter result and never a different
+* kind of one. */
+function headOf(content, chars) {
+	if (typeof content === "string") return content.slice(0, chars);
+	if (!Array.isArray(content)) return content;
+	const parts = [];
+	let used = 0;
+	for (const part of content) {
+		if (part.type === "image_ref") {
+			parts.push(part);
+			continue;
+		}
+		if (typeof part.text !== "string") continue;
+		if (used >= chars) continue;
+		const text = part.text.slice(0, chars - used);
+		parts.push({
+			...part,
+			text
+		});
+		used += text.length + 1;
+	}
+	return parts;
+}
+/**
+* A copy of `event` whose `tool_result` blocks carry `image_ref` addresses in
+* place of their base64 image parts — or `event` itself, unchanged and
+* un-copied, when it holds none. Same identity rule as
+* {@link truncateResultBlocks}, and it matters more here: an event carrying an
+* image at all is the exception, so the common path must not allocate.
+*
+* **Never mutates the stored event.** The log is what the parking snapshot
+* embeds, what `Runner.eventAt` reads, and therefore what the fetch route
+* serves the bytes back from — a drop that reached the log would 404 the very
+* lazy-load this rule promises.
+*
+* Indices are stamped from the **stored** array, which is why this runs *before*
+* truncation rather than after: `headOf` reshapes a block's parts, so an address
+* computed on its output would name the wrong part of the stored block. That
+* ordering is asserted in `replay-image-ref.test.ts`, not merely intended.
+*/
+function refImageParts(event) {
+	if (event.type !== "user_message") return event;
+	const content = event.message.content;
+	if (!Array.isArray(content)) return event;
+	let changed = false;
+	const blocks = content.map((block) => {
+		if (block.type !== "tool_result") return block;
+		const result = block;
+		const parts = result.content;
+		if (!Array.isArray(parts)) return block;
+		let blockChanged = false;
+		const mapped = parts.map((part, index) => {
+			const ref = imagePartRef(part, index);
+			if (!ref) return part;
+			blockChanged = true;
+			return ref;
+		});
+		if (!blockChanged) return block;
+		changed = true;
+		return {
+			...result,
+			content: mapped
+		};
+	});
+	if (!changed) return event;
+	return {
+		...event,
+		message: {
+			...event.message,
+			content: blocks
+		}
+	};
+}
+//#endregion
+//#region src/lib/subscribers.ts
+var SubscriberSet = class {
+	#listeners = /* @__PURE__ */ new Map();
+	/**
+	* Replay `events` to `listener` under `options`, then hold it for live
+	* delivery. Returns the unsubscribe.
+	*
+	* The replay runs *before* the listener joins the set, which is the ordering
+	* every runner already had and is load-bearing: joining first would deliver a
+	* live event emitted mid-replay ahead of the buffered events preceding it.
+	*/
+	subscribe(events, listener, afterSeq = 0, options, resetSeq = 0) {
+		const asked = options ?? {};
+		for (const event of replaySlice(events, {
+			...asked,
+			afterSeq,
+			resetSeq
+		})) listener(event);
+		this.#listeners.set(listener, asked);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	/** Drop every subscriber — a park, which ends the session's live stream. */
+	clear() {
+		this.#listeners.clear();
+	}
+	/** Fan one event out, transformed per subscriber. */
+	emit(event) {
+		for (const [listener, asked] of this.#listeners) try {
+			listener(asked.imageRefs ? refImageParts(event) : event);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/engines/claude/subagents.ts
+/**
+* The rollup behind `SessionInfo.subagents` — what a sessions list (which never
+* attaches) can know about the sub-agents running inside a session. Fed from
+* `SessionRunner.#emit`, the one chokepoint every event passes through, so the
+* resume backfill — which replays history through the same path — reconstructs
+* it with no persistence of its own. Grouping is by Task id throughout, never
+* adjacency: parallel sub-agents interleave in the stream, the same fact that
+* broke the terminal theme's positional row model.
+*
+* Three decisions live here rather than in the protocol doc:
+*
+* **What counts as a spawn.** A record opens when a *top-level* assistant
+* message carries a `tool_use` named `Task` or `Agent` — the moment the
+* sub-agent exists, so a just-spawned agent is visible before its first nested
+* event, with the block's input in hand for its labels. Both names are observed
+* SDK spellings (`Task` synchronous, `Agent` async), and the name is a
+* convention, not a law — a session that spawned three `Agent`s under a tracker
+* that only knew `Task` reported all three as label-less failures. So three
+* more openers back the allowlist up: the CLI's own `task_started` system event
+* (which positively names the `tool_use_id` an agent runs under, with the brief
+* as labels), the launch acknowledgement (below), and — as before — any nested
+* event whose `parentToolUseId` has no record: an id that events demonstrably
+* nest under *is* a sub-agent, whatever the spawning call was named. A fallback
+* record never saw an input, so it stays label-less until a named signal fills
+* it in rather than resetting an accumulated count.
+*
+* **A background agent's `tool_result` is a launch receipt, not a verdict.**
+* An async agent's spawn call resolves seconds after the spawn with "Async
+* agent launched successfully. (This tool result is internal metadata …)" —
+* long before the agent has done anything — and its actual outcome travels on
+* a `task_notification` system event instead (`status: 'completed'` is `done`,
+* any other way of stopping is `failed`: the report the notification exists to
+* deliver never came). Settling on the receipt would read "0 of 3 agents
+* running" while three agents burn tokens, so a non-error result on a record
+* known to be background never settles it. Known how: the `task_started` event
+* live, or the receipt's own wrapper text on a resume — the stored transcript
+* carries none of the CLI's system events, so, exactly as
+* `isSyntheticUserText` documents for the `<task-notification>` blob, the text
+* is the only signal the replayed path has.
+*
+* **What an interrupted turn leaves behind.** A Task whose `tool_result` never
+* arrives — interrupt, session error, a turn or budget cap — would otherwise
+* read `running` on an idle session forever, a lie a list re-renders at every
+* poll. So the end of a turn settles every still-running record as `failed`:
+* the report never came, which is the one thing `done` could have claimed. The
+* sweep keys on `turn_result`, on the status coming to rest (`idle` — which is
+* how a resumed history that ends mid-Task settles, since the backfill replays
+* no `turn_result` — or a terminal state), and on the session closing. A real
+* verdict arriving anyway outranks the sweep's inference. The sweep's premise
+* — "the turn ended, so anything still running was cut off" — is false for a
+* background agent, which is *designed* to outlive its turn: the real session
+* behind this file ended three turns while its agents ran, and every
+* `turn_result` re-branded live, working agents as failures. So the turn and
+* idle sweeps spare a record marked background by a **live** signal. They do
+* not spare one whose only evidence is replayed: the backfill describes a
+* process that is gone, and a background agent the old process died inside can
+* never notify — `running` would be the forever-lie again. `session_closed`
+* and the terminal statuses settle everything, background included, for the
+* same reason: the process hosting those agents is gone.
+*/
+var SubagentTracker = class {
+	#records = /* @__PURE__ */ new Map();
+	#settleCounter = 0;
+	/** Fold one emitted event body into the rollup, in log order. */
+	observe(body, ts) {
+		switch (body.type) {
+			case "assistant_message":
+				if (body.parentToolUseId != null) {
+					const record = this.#recordFor(body.parentToolUseId, ts);
+					record.toolCount += toolUseBlocks(body.message.content).length;
+					return;
+				}
+				for (const block of toolUseBlocks(body.message.content)) {
+					if (!SPAWNER_NAMES.has(block.name)) continue;
+					this.#open(block, ts);
+				}
+				return;
+			case "user_message": {
+				if (body.parentToolUseId != null) {
+					this.#recordFor(body.parentToolUseId, ts);
+					return;
+				}
+				const note = parseTaskNotification(firstText(body.message.content));
+				if (note) {
+					const record = this.#recordFor(note.toolUseId, ts);
+					const status = note.status === "completed" ? "done" : "failed";
+					if (record.status !== status) this.#settle(record, status);
+					return;
+				}
+				const content = body.message.content;
+				if (typeof content === "string") return;
+				for (const block of content) {
+					if (block.type !== "tool_result") continue;
+					const result = block;
+					if (typeof result.tool_use_id !== "string") continue;
+					if (result.is_error !== true && isLaunchAck(result.content)) {
+						const record = this.#recordFor(result.tool_use_id, ts);
+						if (record.background !== "live") record.background = body.replay === true ? "replay" : "live";
+						continue;
+					}
+					const record = this.#records.get(result.tool_use_id);
+					if (!record) continue;
+					if (result.is_error !== true && record.background !== void 0) continue;
+					const status = result.is_error === true ? "failed" : "done";
+					if (record.status === status) continue;
+					this.#settle(record, status);
+				}
+				return;
+			}
+			case "sdk_event": {
+				const p = body.payload;
+				if (p.type !== "system" || typeof p.tool_use_id !== "string") return;
+				if (p.subtype === "task_started") {
+					const record = this.#recordFor(p.tool_use_id, ts);
+					record.background = "live";
+					record.agentType ??= cleaned(p.subagent_type);
+					record.description ??= cleaned(p.description);
+					return;
+				}
+				if (p.subtype === "task_notification") {
+					const record = this.#recordFor(p.tool_use_id, ts);
+					const status = p.status === "completed" ? "done" : "failed";
+					if (record.status !== status) this.#settle(record, status);
+					return;
+				}
+				return;
+			}
+			case "turn_result":
+				this.#sweep(false);
+				return;
+			case "session_closed":
+				this.#sweep(true);
+				return;
+			case "status_changed":
+				if (body.status === "idle") this.#sweep(false);
+				else if (body.status === "failed" || body.status === "closed") this.#sweep(true);
+				return;
+			case "conversation_reset":
+				this.#records.clear();
+				return;
+			default: return;
+		}
+	}
+	/**
+	* The rollup as `SessionInfo.subagents` serves it: spawn order (the
+	* transcript's own), fresh objects, and `undefined` when there is nothing to
+	* say — absent and empty mean the same thing to a client, and an empty array
+	* on every row of a 1.2s-polled list is bytes spent saying nothing.
+	*/
+	list() {
+		if (this.#records.size === 0) return void 0;
+		const out = [];
+		for (const r of this.#records.values()) out.push({
+			toolUseId: r.toolUseId,
+			agentType: r.agentType,
+			description: r.description,
+			status: r.status,
+			startedAt: r.startedAt,
+			toolCount: r.toolCount
+		});
+		return out;
+	}
+	#recordFor(toolUseId, ts) {
+		let record = this.#records.get(toolUseId);
+		if (!record) {
+			record = {
+				toolUseId,
+				status: "running",
+				startedAt: ts,
+				toolCount: 0
+			};
+			this.#records.set(toolUseId, record);
+		}
+		return record;
+	}
+	#open(block, ts) {
+		const record = this.#recordFor(block.id, ts);
+		const input = block.input;
+		record.agentType ??= cleaned(input?.subagent_type);
+		record.description ??= cleaned(input?.description);
+	}
+	/**
+	* End of turn (`final: false`): anything still running was cut off before
+	* its report — except a background agent the live process still hosts, which
+	* is designed to outlive the turn and settles by notification instead. End
+	* of session (`final: true`): everything, background included, because the
+	* process those agents lived in is gone.
+	*/
+	#sweep(final) {
+		for (const record of this.#records.values()) {
+			if (record.status !== "running") continue;
+			if (!final && record.background === "live") continue;
+			this.#settle(record, "failed");
+		}
+	}
+	#settle(record, status) {
+		record.status = status;
+		record.settledOrder = ++this.#settleCounter;
+		let settled = 0;
+		for (const r of this.#records.values()) if (r.settledOrder !== void 0) settled++;
+		while (settled > SUBAGENT_HISTORY) {
+			let oldestId;
+			let oldestOrder = Infinity;
+			for (const r of this.#records.values()) {
+				if (r.settledOrder === void 0 || r.settledOrder >= oldestOrder) continue;
+				oldestId = r.toolUseId;
+				oldestOrder = r.settledOrder;
+			}
+			if (oldestId === void 0) break;
+			this.#records.delete(oldestId);
+			settled--;
+		}
+	}
+};
+/** The spawner names observed in the wild: `Task` runs the agent inside the
+* turn, `Agent` launches it in the background. Deliberately just these two —
+* a third spelling is caught by `task_started`, the launch receipt, or the
+* nested-event fallback, so widening this to every tool would only turn
+* ordinary calls into phantom agents. */
+const SPAWNER_NAMES = new Set(["Task", "Agent"]);
+/** The async spawn's immediate `tool_result` — "Async agent launched
+* successfully. (This tool result is internal metadata …)" — recognized by its
+* wrapper text because on a resume that text is the only signal there is (the
+* `SYNTHETIC_USER_PREFIXES` argument; the CLI's system events are not stored).
+* Live, `task_started` marks the record first and this is redundant armor. */
+const isLaunchAck = (content) => {
+	const text = typeof content === "string" ? content : firstText(Array.isArray(content) ? content : []);
+	return typeof text === "string" && text.trimStart().startsWith("Async agent launched");
+};
+/** A background agent stopping, parsed from the `<task-notification>` wrapper
+* the CLI writes into the transcript. Field-tolerant on purpose: only the
+* `tool-use-id` (this rollup's key) and the `status` verdict are read. */
+const parseTaskNotification = (text) => {
+	if (text === void 0 || !text.trimStart().startsWith("<task-notification>")) return void 0;
+	const toolUseId = /<tool-use-id>\s*([^<\s]+)\s*<\/tool-use-id>/.exec(text)?.[1];
+	if (toolUseId === void 0) return void 0;
+	return {
+		toolUseId,
+		status: /<status>\s*([^<]*?)\s*<\/status>/.exec(text)?.[1] ?? ""
+	};
+};
+/** The first text of a message body, however the content is spelled — the
+* stored transcript uses bare strings, the live stream uses blocks. */
+const firstText = (content) => {
+	if (typeof content === "string") return content;
+	for (const block of content) {
+		const b = block;
+		if (b?.type === "text" && typeof b.text === "string") return b.text;
+	}
+};
+/** Trim, drop blank, clip at the same 80 the terminal theme's `taskLabel` uses.
+* Model-authored input rides every row of a polled sessions list, so it is
+* bounded here rather than trusted — a 10KB `description` would be paid for at
+* every poll. */
+const cleaned = (value) => {
+	if (typeof value !== "string") return void 0;
+	const text = value.trim();
+	if (text === "") return void 0;
+	return text.length > 80 ? text.slice(0, 79) + "…" : text;
+};
+/** The `tool_use` blocks of a message body, however the content is spelled. */
+function toolUseBlocks(content) {
+	if (typeof content === "string") return [];
+	const blocks = [];
+	for (const block of content) {
+		if (block.type !== "tool_use") continue;
+		const b = block;
+		if (typeof b.id !== "string" || typeof b.name !== "string") continue;
+		blocks.push({
+			id: b.id,
+			name: b.name,
+			input: b.input
+		});
+	}
+	return blocks;
+}
 //#endregion
 //#region src/engines/claude/runner.ts
 const DEFAULT_APPROVAL_TIMEOUT_MS$1 = 3e5;
@@ -608,8 +1098,15 @@ var SessionRunner = class {
 	/** {@link SessionRunnerConfig.cwd}, checked once in the constructor. */
 	#cwd;
 	#events = [];
-	#listeners = /* @__PURE__ */ new Set();
+	#subscribers = new SubscriberSet();
 	#seq = 0;
+	/**
+	* Latest context-window reading, retained from the last `context_usage` this
+	* runner emitted so `GET /sessions` can answer it without an attach — see
+	* `SessionInfo.contextUsage`. Folded in the emit path, so it is by
+	* construction the same number the transcript last drew.
+	*/
+	#contextUsage;
 	#activityCount = 0;
 	/**
 	* Seq of the latest `conversation_reset` event, 0 when none. The log itself is
@@ -627,6 +1124,28 @@ var SessionRunner = class {
 	#apiKeySource;
 	#permissionMode;
 	#pending = /* @__PURE__ */ new Map();
+	/**
+	* The turn ended while an approval was standing, and nothing has started a
+	* new one since.
+	*
+	* `awaiting_approval` rightly outranks `idle` for display, so a turn-over
+	* signal arriving under a standing approval cannot be applied when it lands.
+	* It used to be **discarded** for that reason, which is a different thing
+	* from outranked: the settle path then asserted `running` on the assumption
+	* that an answered approval means work resumes, and when the turn was already
+	* over — an interrupt, a timeout — the session claimed to be running one that
+	* had produced its result. Status is purely edge-driven here, with no poll and
+	* no reconciliation anywhere, so that single dropped edge never came back and
+	* every client rendered it faithfully for the life of the session.
+	*
+	* So the fact is *deferred* rather than dropped, and it is deliberately
+	* cleared the moment work genuinely resumes — a turn-over belongs to the turn
+	* that produced it and must not settle the next one.
+	*/
+	#turnOverWhileBlocked = false;
+	/** The read-time sub-agent rollup (`SessionInfo.subagents`), fed from #emit —
+	* the one chokepoint — so the resume backfill reconstructs it for free. */
+	#subagents = new SubagentTracker();
 	#totalCostUsd;
 	#numTurns;
 	#lastActivityAt;
@@ -682,7 +1201,9 @@ var SessionRunner = class {
 			createdAt: this.createdAt,
 			lastSeq: this.#seq,
 			activityCount: this.#activityCount,
+			contextUsage: this.#contextUsage,
 			pendingPermissionCount: this.#pending.size,
+			subagents: this.#subagents.list(),
 			meta: this.#config.meta,
 			scope: this.#config.scope,
 			title: this.#title(),
@@ -831,6 +1352,12 @@ var SessionRunner = class {
 		});
 		this.#setStatus("closed");
 	}
+	/** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+	* "show everything" on one row, so a per-runner seq index would be a map
+	* maintained on every emit to save a walk nobody makes twice a minute. */
+	eventAt(seq) {
+		return this.#events.find((event) => event.seq === seq);
+	}
 	/**
 	* Replay buffered events with seq > afterSeq, then deliver live events.
 	* Returns an unsubscribe function.
@@ -845,15 +1372,7 @@ var SessionRunner = class {
 	* content below the newer one and are skipped with what they cleared.
 	*/
 	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);
+		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options, this.#resetSeq);
 	}
 	async #run() {
 		const queryFn = this.#config.queryFn ?? query;
@@ -944,6 +1463,7 @@ var SessionRunner = class {
 			forkSession: c.forkSession,
 			effort: c.reasoningEffort,
 			includePartialMessages: c.includePartialMessages ?? true,
+			forwardSubagentText: true,
 			canUseTool: this.#canUseTool,
 			env: c.env,
 			pathToClaudeCodeExecutable: c.pathToClaudeCodeExecutable,
@@ -970,6 +1490,7 @@ var SessionRunner = class {
 				claudeCodeVersion: msg.claude_code_version,
 				mcpServers: msg.mcp_servers
 			});
+			this.#turnOverWhileBlocked = false;
 			this.#setStatus("running");
 			this.#fetchCapabilities();
 			this.#fetchContextUsage();
@@ -978,7 +1499,11 @@ var SessionRunner = class {
 			return;
 		}
 		if (msg.type === "system" && msg.subtype === "session_state_changed") {
-			if (this.#pending.size > 0) return;
+			if (this.#pending.size > 0) {
+				if (msg.state === "idle") this.#turnOverWhileBlocked = true;
+				else if (msg.state === "running") this.#turnOverWhileBlocked = false;
+				return;
+			}
 			if (msg.state === "idle") this.#setStatus("idle");
 			else if (msg.state === "running") this.#setStatus("running");
 			return;
@@ -994,6 +1519,7 @@ var SessionRunner = class {
 				this.#totalCostUsd = body.totalCostUsd;
 				this.#numTurns = body.numTurns;
 				if (this.#pending.size === 0) this.#setStatus("idle");
+				else this.#turnOverWhileBlocked = true;
 				this.#fetchContextUsage();
 				this.#fetchRateLimits();
 				this.#fetchEngineTitle();
@@ -1224,7 +1750,12 @@ var SessionRunner = class {
 			resolvedBy,
 			message: decision.behavior === "deny" ? decision.message ?? "Denied" : void 0
 		});
-		if (this.#pending.size === 0 && this.#status === "awaiting_approval") this.#setStatus("running");
+		if (this.#pending.size === 0) {
+			const endedWhileBlocked = this.#turnOverWhileBlocked;
+			this.#turnOverWhileBlocked = false;
+			if (endedWhileBlocked) this.#setStatus("idle");
+			else if (this.#status === "awaiting_approval") this.#setStatus("running");
+		}
 	}
 	#setStatus(status, detail) {
 		if (this.#status === status && this.#statusDetail === detail) return;
@@ -1245,11 +1776,14 @@ var SessionRunner = class {
 		};
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
-		if (body.type === "conversation_reset") this.#resetSeq = event.seq;
+		this.#contextUsage = contextReading(body) ?? this.#contextUsage;
+		if (body.type === "conversation_reset") {
+			this.#resetSeq = event.seq;
+			this.#contextUsage = void 0;
+		}
+		this.#subagents.observe(body, event.ts);
 		this.#events.push(event);
-		for (const listener of this.#listeners) try {
-			listener(event);
-		} catch {}
+		this.#subscribers.emit(event);
 	}
 };
 /** Answer each AskUserQuestion question with its first option's label — the tool's
@@ -1292,8 +1826,15 @@ var AiSdkRunner = class {
 	#config;
 	#model;
 	#events = [];
-	#listeners = /* @__PURE__ */ new Set();
+	#subscribers = new SubscriberSet();
 	#seq = 0;
+	/**
+	* Latest context-window reading, retained from the last `context_usage` this
+	* runner emitted so `GET /sessions` can answer it without an attach — see
+	* `SessionInfo.contextUsage`. Folded in the emit path, so it is by
+	* construction the same number the transcript last drew.
+	*/
+	#contextUsage;
 	#activityCount = 0;
 	#status = "starting";
 	#permissionMode;
@@ -1343,7 +1884,12 @@ var AiSdkRunner = class {
 		if (!state || !Array.isArray(state.messages)) throw new Error("session snapshot is missing its provider-engine state");
 		this.#seq = snapshot.seq;
 		this.#events = [...snapshot.events];
-		this.#activityCount = this.#events.reduce((total, event) => total + transcriptActivity(event), 0);
+		this.#activityCount = 0;
+		for (const event of this.#events) {
+			this.#activityCount += transcriptActivity(event);
+			if (event.type === "conversation_reset") this.#contextUsage = void 0;
+			else this.#contextUsage = contextReading(event) ?? this.#contextUsage;
+		}
 		this.#messages = [...state.messages];
 		for (const call of state.pendingToolCalls) this.#pendingToolCalls.set(call.toolCallId, call);
 		this.#dispatched = new Set(state.dispatched);
@@ -1394,6 +1940,7 @@ var AiSdkRunner = class {
 			createdAt: this.createdAt,
 			lastSeq: this.#seq,
 			activityCount: this.#activityCount,
+			contextUsage: this.#contextUsage,
 			pendingPermissionCount: 0,
 			meta: this.#config.meta,
 			scope: this.#config.scope,
@@ -1405,10 +1952,7 @@ var AiSdkRunner = class {
 	start() {
 		if (this.#started) return this.#turnChain;
 		this.#started = true;
-		if (this.#config.restore) {
-			if (this.#pendingToolCalls.size === 0) this.#scheduleTurn();
-			return this.#turnChain;
-		}
+		if (this.#config.restore) return this.#turnChain;
 		this.#setStatus("idle");
 		if (this.#config.prompt) this.sendMessage(this.#config.prompt);
 		return this.#turnChain;
@@ -1423,6 +1967,61 @@ var AiSdkRunner = class {
 		if (this.#closed || this.#parked) return void 0;
 		if (this.#abort || !this.#restingOnDeferred()) return void 0;
 		this.#setStatus("parked");
+		const snapshot = this.#buildSnapshot();
+		this.#parked = true;
+		this.#subscribers.clear();
+		try {
+			Promise.resolve(this.#config.onClose?.()).catch(() => {});
+		} catch {}
+		return snapshot;
+	}
+	/**
+	* The same snapshot, taken without ending anything.
+	*
+	* `park()` and this are two operations that happen to produce the same value,
+	* and the difference is the whole point: `park()` *ends* the live runner
+	* (inert, listeners dropped, `onClose` called), which is right for deferred
+	* execution — the session has nothing to do for possibly days — and wrong for
+	* restart-survival, where the session is active and someone is mid-
+	* conversation. This one changes nothing at all: no status emit, no listener
+	* clear, no disposer. The host writes the value through to durable storage
+	* after each turn and keeps the runner live and warm, so a restart rebuilds
+	* from the last write through the existing `restore` path and the next message
+	* costs no wake.
+	*
+	* The gate is `park()`'s minus the requirement that there be something parked:
+	*
+	* - `#abort` set is refused for the reason it always was — a `generate()` in
+	*   flight has produced messages that are not in the history yet, so the
+	*   snapshot would be of a turn that half-happened.
+	* - Pending calls that are **not** all deferred are refused, which is
+	*   `park()`'s rule wearing a different hat. An in-process execution's result
+	*   is coming back to *this* runner and dies with the process; a restore would
+	*   wait on it forever, and `state.dispatched` is what would stop the rebuilt
+	*   runner from simply calling it again.
+	* - Idle with nothing pending — the case `park()` exists to refuse — is
+	*   exactly the case this exists to allow.
+	*/
+	snapshot() {
+		if (this.#closed || this.#parked || this.#abort) return void 0;
+		if (this.#pendingToolCalls.size > 0 && !this.#restingOnDeferred()) return void 0;
+		return this.#buildSnapshot();
+	}
+	/**
+	* The snapshot value itself, shared so a park and a write-through cannot
+	* disagree about what a session *is*.
+	*
+	* The event log is filtered through {@link snapshotRetains} — the persisted
+	* log drops stream deltas, which are superseded by the `assistant_message`
+	* that flushes them and would otherwise be tens of times the size of the text
+	* they spell. Parks get it too, and should: a park sits on disk for days.
+	*
+	* The `parked` list and `state.parkedAt` are honest under both callers. An
+	* idle write-through has no pending calls, so `parked` is empty and the host
+	* arms no watchdogs; `parkedAt` is "when this was taken", which is what
+	* `#restore` needs to discount a turn's clock either way.
+	*/
+	#buildSnapshot() {
 		const parked = [...this.#pendingToolCalls.values()].map((call) => ({
 			executionId: call.toolCallId,
 			toolName: call.toolName,
@@ -1440,22 +2039,16 @@ var AiSdkRunner = class {
 			lastActivityAt: this.#lastActivityAt,
 			parkedAt: Date.now()
 		};
-		const snapshot = {
+		return {
 			engine: "provider",
 			id: this.id,
 			createdAt: this.createdAt,
 			seq: this.#seq,
-			events: [...this.#events],
+			events: this.#events.filter((event) => snapshotRetains(event)),
 			vfs: this.#config.vfs?.snapshot(),
 			parked,
 			state
 		};
-		this.#parked = true;
-		this.#listeners.clear();
-		try {
-			Promise.resolve(this.#config.onClose?.()).catch(() => {});
-		} catch {}
-		return snapshot;
 	}
 	sendMessage(text, attachments) {
 		if (this.#parked) throw new Error("session is parked");
@@ -1638,15 +2231,14 @@ var AiSdkRunner = class {
 			Promise.resolve(this.#config.onClose?.()).catch(() => {});
 		} catch {}
 	}
+	/** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+	* "show everything" on one row, so a per-runner seq index would be a map
+	* maintained on every emit to save a walk nobody makes twice a minute. */
+	eventAt(seq) {
+		return this.#events.find((event) => event.seq === seq);
+	}
 	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);
+		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options);
 	}
 	#scheduleTurn() {
 		this.#turnChain = this.#turnChain.then(() => this.#runTurn());
@@ -2035,10 +2627,10 @@ var AiSdkRunner = class {
 		};
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
+		this.#contextUsage = contextReading(body) ?? this.#contextUsage;
+		if (body.type === "conversation_reset") this.#contextUsage = void 0;
 		this.#events.push(event);
-		for (const listener of this.#listeners) try {
-			listener(event);
-		} catch {}
+		this.#subscribers.emit(event);
 	}
 };
 function turnUsage(accum) {
@@ -3257,8 +3849,6 @@ const claudeAdapter = {
 		}));
 	}
 };
-//#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).
@@ -3290,9 +3880,12 @@ var JsonRpcStdioConnection = class {
 	#buffer = "";
 	#closed = false;
 	#notificationHandler;
+	/** Where {@link CODEX_TRACE_ENV} pointed, or undefined — read once. */
+	#trace;
 	#requestHandler;
 	constructor(options) {
 		this.#output = options.output;
+		this.#trace = process.env["WORKERDECK_CODEX_TRACE"] || void 0;
 		options.input.on("data", (chunk) => this.#feed(String(chunk)));
 		options.input.on("error", () => {});
 		options.output.on("error", () => {});
@@ -3353,9 +3946,28 @@ var JsonRpcStdioConnection = class {
 			} catch {
 				continue;
 			}
+			this.#traceLine(message);
 			this.#dispatch(message);
 		}
 	}
+	/**
+	* Append one inbound message to the trace file, when the operator asked for
+	* one. **Notifications and server→client requests only** — a response body is
+	* not needed to answer the questions this exists for, and `account/*` results
+	* are the one place app-server traffic can carry a masked credential
+	* fragment, which nothing of ours writes to disk (see the auth red lines).
+	* Best-effort and synchronous: a debug sink that loses lines proves nothing,
+	* and a debug sink that throws must not take the session with it.
+	*/
+	#traceLine(message) {
+		if (!this.#trace) return;
+		const method = message.method;
+		if (typeof method !== "string") return;
+		if (method.startsWith("account/") || method.startsWith("login")) return;
+		try {
+			appendFileSync(this.#trace, JSON.stringify(message) + "\n");
+		} catch {}
+	}
 	#dispatch(message) {
 		const { id, method } = message;
 		if (typeof method === "string") {
@@ -3394,6 +4006,117 @@ var JsonRpcStdioConnection = class {
 	}
 };
 //#endregion
+//#region src/engines/codex/subagents.ts
+/**
+* The codex side of `SessionInfo.subagents` — and the attribution table that
+* gives every event a spawned agent produces its `parentToolUseId`.
+*
+* Codex's signal is stronger than the claude engine's, so this is deliberately
+* NOT that tracker generalised (`engines/claude/subagents.ts` infers spawns
+* from tool names and verdicts from result-text sniffing, ~290 lines of module
+* doc explaining the inference). Here nothing is inferred: `subAgentActivity
+* {kind: 'started'}` on the owning thread positively announces an agent, names
+* it (`agentPath`), keys it (`agentThreadId` — the id every one of its later
+* notifications carries) and hands over the model's own `spawn_agent` call id;
+* the agent's end is its own thread's `turn/completed`, status included. So a
+* record is keyed by **thread id** — the wire's handle — while exposing a
+* **tool-use id** — the protocol's: `parentToolUseId` on nested events must
+* equal the anchor `tool_use`'s id for `subagentItems` (the frame membership
+* rule every client shares) to reassemble the sidechain, and this map is where
+* the two vocabularies meet.
+*
+* Two decisions worth their prose:
+*
+* **A record survives the runner's turns.** Codex agents are designed to
+* outlive the root turn that spawned them (`sendInput`/`resumeAgent` address a
+* thread that kept existing), so — unlike a pending approval — nothing here is
+* swept when a root turn ends. What does end every agent is the app-server
+* process itself: the runner calls {@link sweep} when the child dies or the
+* session closes, because an agent whose host process is gone can never report,
+* and `running` on a closed session would be a lie a polled list re-renders
+* forever (the claude tracker's argument, inherited whole).
+*
+* **The settled tail is bounded, running records never are** — the same
+* {@link SUBAGENT_HISTORY} discipline as the claude tracker, and enforced at
+* settle time for the same reason: a settle happens once per agent, `list()`
+* once per row of a 1.2s-polled sessions list.
+*/
+var CodexAgentTracker = class {
+	#byThread = /* @__PURE__ */ new Map();
+	#settleCounter = 0;
+	/** The record whose thread this is — the attribution lookup. */
+	get(agentThreadId) {
+		return this.#byThread.get(agentThreadId);
+	}
+	/** Open (or return) the record for a thread. Fill-in, never overwrite: a
+	* label-less fallback record keeps its accumulated count and its already
+	* published toolUseId when the announcing item arrives late. */
+	open(agentThreadId, toolUseId, agentType, ts) {
+		let record = this.#byThread.get(agentThreadId);
+		if (!record) {
+			record = {
+				agentThreadId,
+				toolUseId,
+				status: "running",
+				startedAt: ts,
+				toolCount: 0,
+				counted: /* @__PURE__ */ new Set()
+			};
+			this.#byThread.set(agentThreadId, record);
+		}
+		record.agentType ??= agentType;
+		return record;
+	}
+	/** The agent's thread ran again (`kind: 'interacted'`, or a fresh
+	* `turn/started` on its thread): a settled verdict no longer describes it. */
+	revive(record) {
+		record.status = "running";
+		record.settledOrder = void 0;
+	}
+	#settle(record, status) {
+		record.status = status;
+		record.settledOrder = ++this.#settleCounter;
+		let settled = 0;
+		for (const r of this.#byThread.values()) if (r.settledOrder !== void 0) settled++;
+		while (settled > SUBAGENT_HISTORY) {
+			let oldest;
+			for (const r of this.#byThread.values()) {
+				if (r.settledOrder === void 0) continue;
+				if (!oldest || r.settledOrder < oldest.settledOrder) oldest = r;
+			}
+			if (!oldest) break;
+			this.#byThread.delete(oldest.agentThreadId);
+			settled--;
+		}
+	}
+	/** A real verdict for one agent — its thread's `turn/completed`, or the
+	* `interrupted` activity edge. */
+	settle(record, status) {
+		if (record.status === status) return;
+		this.#settle(record, status);
+	}
+	/** The process the agents lived in is gone (child death, session close):
+	* everything still running is settled as failed — the report can never come. */
+	sweep() {
+		for (const record of this.#byThread.values()) if (record.status === "running") this.#settle(record, "failed");
+	}
+	/** The rollup as `SessionInfo.subagents` serves it — spawn order, fresh
+	* objects, and `undefined` when there is nothing to say (absent and empty
+	* mean the same thing to a client, and bytes on a polled list are paid for). */
+	list() {
+		if (this.#byThread.size === 0) return void 0;
+		const out = [];
+		for (const r of this.#byThread.values()) out.push({
+			toolUseId: r.toolUseId,
+			agentType: r.agentType,
+			status: r.status,
+			startedAt: r.startedAt,
+			toolCount: r.toolCount
+		});
+		return out;
+	}
+};
+//#endregion
 //#region src/engines/codex/runner.ts
 /**
 * thread/start's sandbox axis (string form) — our permission modes as codex
@@ -3434,16 +4157,27 @@ const GRANULAR_ASK = { granular: {
 	request_permissions: true,
 	skill_approval: true
 } };
+const GRANULAR_NEVER = { granular: {
+	sandbox_approval: false,
+	rules: false,
+	mcp_elicitations: false,
+	request_permissions: false,
+	skill_approval: false
+} };
+/**
+* Notifications whose meaning is scoped to ONE thread, and which are therefore
+* only ever read off the session's own. Everything else (items, deltas) is
+* accepted from any thread on the connection — see `#handleNotification`.
+*/
+const THREAD_SCOPED_NOTIFICATIONS = new Set([
+	"turn/started",
+	"turn/completed",
+	"thread/tokenUsage/updated"
+]);
 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
-	} }
+	bypassPermissions: GRANULAR_NEVER
 };
 /** Fallback timeout for a pending approval nobody answers — the SessionRunner
 * default, so unattended codex sessions land the same way Claude ones do. */
@@ -3454,6 +4188,47 @@ const DEFAULT_APPROVAL_TIMEOUT_MS = 3e5;
 * host filesystem, an inline preview) off it.
 */
 const CODEX_IMAGE_TOOL = "CodexImageGeneration";
+/**
+* Tool name for a spawned agent's anchor `tool_use` — the claude engine's
+* `Task` in this engine's vocabulary. Codex never sends such a call: the model's
+* `spawn_agent` surfaces only as the `subAgentActivity` marker item, so the
+* runner authors the call itself, because everything downstream is built on a
+* top-level `tool_use` existing — `terminalBlocks` absorbs a sidechain into the
+* call whose id its events carry as `parentToolUseId`, the takeover frames by
+* it, and `taskIdentity` labels it from the input's `subagent_type`. Not a new
+* wire idea, just a row: the same shape every other codex tool card uses.
+*/
+const CODEX_AGENT_TOOL = "CodexAgent";
+/** Tool name for the model's collab-agent calls (`wait`, `sendInput`, …), the
+* `tool` field carried in the input. One name for the whole open axis rather
+* than a name per verb, so a future verb renders instead of vanishing. */
+const CODEX_COLLAB_TOOL = "CodexCollab";
+/** An agent's name is its path's basename: '/root/date_one' → 'date_one'. */
+function agentName(agentPath) {
+	if (typeof agentPath !== "string") return void 0;
+	return agentPath.split("/").filter(Boolean).at(-1) || void 0;
+}
+/** The collab card's input: the verb always, the rich fields only when codex
+* actually filled them (measured against 0.146.0 they arrive empty — the card
+* must not render five null columns to say 'wait'). */
+function collabInput(item) {
+	return {
+		tool: item.tool,
+		...item.receiverThreadIds?.length ? { receiverThreadIds: item.receiverThreadIds } : {},
+		...item.prompt ? { prompt: item.prompt } : {},
+		...item.model ? { model: item.model } : {}
+	};
+}
+/** A completed turn's answer, from its summary `items` page — the last
+* `agentMessage` text. For a sub-agent's thread this is the agent's report,
+* which is exactly what belongs in the anchor's `tool_result`. */
+function turnReport(turn) {
+	const items = Array.isArray(turn.items) ? turn.items : [];
+	for (let index = items.length - 1; index >= 0; index--) {
+		const item = items[index];
+		if (item?.type === "agentMessage" && typeof item.text === "string" && item.text) return item.text;
+	}
+}
 /** Longest `result` worth putting in a tool card. The field is free-form and
 * undocumented; anything past this is assumed to be an encoded image rather
 * than a sentence, and encoded images do not go in the event log. */
@@ -3795,8 +4570,15 @@ var CodexRunner = class {
 	/** {@link CodexRunnerConfig.cwd}, checked once in the constructor. */
 	#cwd;
 	#events = [];
-	#listeners = /* @__PURE__ */ new Set();
+	#subscribers = new SubscriberSet();
 	#seq = 0;
+	/**
+	* Latest context-window reading, retained from the last `context_usage` this
+	* runner emitted so `GET /sessions` can answer it without an attach — see
+	* `SessionInfo.contextUsage`. Folded in the emit path, so it is by
+	* construction the same number the transcript last drew.
+	*/
+	#contextUsage;
 	#activityCount = 0;
 	#status = "starting";
 	#sdkSessionId;
@@ -3852,6 +4634,12 @@ var CodexRunner = class {
 	* `mcpServerStatus/list` does not carry a status field at all, so without
 	* this every server would read as "configured" and never as up or down. */
 	#mcpStatus = /* @__PURE__ */ new Map();
+	/** The spawned agents, keyed by their thread ids — the attribution table
+	* behind `parentToolUseId` and the rollup behind `info().subagents`. Runner-
+	* level, not per-turn: an agent's thread outlives the root turn that spawned
+	* it, and only the child process dying (or the session closing) ends them
+	* all — see the module doc in `subagents.ts`. */
+	#agents = new CodexAgentTracker();
 	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`);
@@ -3903,13 +4691,15 @@ var CodexRunner = class {
 			createdAt: this.createdAt,
 			lastSeq: this.#seq,
 			activityCount: this.#activityCount,
+			contextUsage: this.#contextUsage,
 			pendingPermissionCount: this.#approvals.size,
 			meta: this.#config.meta,
 			scope: this.#config.scope,
 			title: this.#title(),
 			totalCostUsd: this.#totalCostUsd,
 			numTurns: this.#numTurns || void 0,
-			lastActivityAt: this.#lastActivityAt
+			lastActivityAt: this.#lastActivityAt,
+			subagents: this.#agents.list()
 		};
 	}
 	#title() {
@@ -4123,6 +4913,7 @@ var CodexRunner = class {
 		}, "policy");
 		this.#connection?.close();
 		this.#connection = void 0;
+		this.#agents.sweep();
 		this.#activeTurn?.reject(/* @__PURE__ */ new Error("session closed"));
 		if (this.#imageDir) try {
 			rmSync(this.#imageDir, {
@@ -4136,15 +4927,14 @@ var CodexRunner = class {
 		});
 		this.#setStatus("closed");
 	}
+	/** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+	* "show everything" on one row, so a per-runner seq index would be a map
+	* maintained on every emit to save a walk nobody makes twice a minute. */
+	eventAt(seq) {
+		return this.#events.find((event) => event.seq === seq);
+	}
 	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);
+		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options);
 	}
 	#scheduleTurn() {
 		this.#turnChain = this.#turnChain.then(() => this.#runTurn());
@@ -4174,6 +4964,7 @@ var CodexRunner = class {
 					behavior: "deny",
 					message
 				}, "policy");
+				this.#agents.sweep();
 				this.#activeTurn?.reject(new Error(message));
 			});
 			try {
@@ -4469,11 +5260,79 @@ var CodexRunner = class {
 	}
 	#handleNotification(method, params) {
 		if (this.#closed) return;
+		if (THREAD_SCOPED_NOTIFICATIONS.has(method) && !this.#isRootThread(params)) {
+			if (method === "turn/completed") this.#settleAgentTurn(params);
+			else if (method === "turn/started") {
+				const threadId = this.#threadIdOf(params);
+				const record = threadId ? this.#agents.get(threadId) : void 0;
+				if (record && record.status !== "running") this.#agents.revive(record);
+			}
+			return;
+		}
 		this.#notifications[method]?.(params);
 	}
+	/** Whether a notification is about the session's own thread. A notification
+	* with no `threadId` counts as the root's: every thread-scoped method the
+	* schema defines carries one, so an absent id means an older or narrower
+	* shape, not a sub-agent. */
+	#isRootThread(params) {
+		const threadId = this.#threadIdOf(params);
+		if (threadId === void 0) return true;
+		return threadId === this.#sdkSessionId;
+	}
+	#threadIdOf(params) {
+		const threadId = params?.threadId;
+		return typeof threadId === "string" ? threadId : void 0;
+	}
+	/**
+	* The agent behind a notification's `threadId` — the attribution every item
+	* and delta handler asks before emitting, so two agents streaming
+	* concurrently into this one connection come apart again by the id each
+	* frame carries, never by any mutable "current agent".
+	*
+	* A non-root thread with no record still gets one: a thread emitting items on
+	* this connection *is* an agent, whatever announced it (codex runs threads of
+	* its own for review/compact, and a `subAgentActivity` could in principle be
+	* missed) — the claude tracker's nested-event fallback, on a stronger signal.
+	* The minted record is label-less and its anchor is authored here, because an
+	* attributed event whose parent id matches no top-level `tool_use` would
+	* render inline rather than as a frame; a late `started` edge fills the name
+	* in. Root-thread traffic — and, defensively, the pre-thread shapes with no
+	* id at all — stays unattributed (`undefined`).
+	*/
+	#agentFor(params) {
+		const threadId = this.#threadIdOf(params);
+		if (threadId === void 0 || threadId === this.#sdkSessionId) return void 0;
+		const known = this.#agents.get(threadId);
+		if (known) return known;
+		const nonce = this.#activeTurn?.nonce ?? "codex";
+		const record = this.#agents.open(threadId, `${nonce}:agent:${threadId}`, void 0, Date.now());
+		record.anchored = true;
+		this.#emitToolUse(record.toolUseId, CODEX_AGENT_TOOL, { agentThreadId: threadId });
+		return record;
+	}
+	/**
+	* A child thread's `turn/completed` is that AGENT's completion — the one
+	* codex sends (`subAgentActivity` has no 'completed' kind, verified live).
+	* The verdict is the turn's own status, and the report is the completed
+	* turn's final message, delivered as the anchor's `tool_result` so the row
+	* settles exactly the way a claude `Task`'s does. Deliberately not gated on
+	* `#activeTurn`: an agent finishing between root turns still finished.
+	*/
+	#settleAgentTurn(params) {
+		const threadId = this.#threadIdOf(params);
+		const record = threadId ? this.#agents.get(threadId) : void 0;
+		if (!record || record.status !== "running") return;
+		const turn = params?.turn;
+		const status = turn?.status === "completed" ? "done" : "failed";
+		this.#agents.settle(record, status);
+		const report = (turn ? turnReport(turn) : void 0) ?? turn?.error?.message ?? (status === "done" ? "" : turn?.status ?? "failed");
+		this.#emitToolResult(record.toolUseId, report, status === "failed");
+	}
 	/** 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)
+	* never share a boundary (and item ids are per-thread, so two agents' streams
+	* never share one either). Section boundaries (a new summary/content entry)
 	* render as paragraph breaks — the completed item joins sections with '\n\n'. */
 	#reasoningDelta(method) {
 		return (params) => {
@@ -4489,7 +5348,7 @@ var CodexRunner = class {
 			this.#emitDelta({
 				type: "thinking_delta",
 				thinking: separator + payload.delta
-			});
+			}, this.#agentFor(params)?.toolUseId ?? null);
 		};
 	}
 	/** One item-progress handler serves `item/started` and `item/updated`. */
@@ -4497,7 +5356,7 @@ var CodexRunner = class {
 		const active = this.#activeTurn;
 		if (!active) return;
 		const item = params?.item;
-		if (item) this.#handleItemProgress(item, active);
+		if (item) this.#handleItemProgress(item, active, this.#agentFor(params));
 	};
 	/** The notification dispatch table — every method the child emits that this
 	* runner maps, in one place. Handlers read `this.#activeTurn` themselves:
@@ -4515,7 +5374,9 @@ var CodexRunner = class {
 		"turn/completed": (params) => {
 			const active = this.#activeTurn;
 			const turn = params?.turn;
-			if (active && turn) active.resolve(turn);
+			if (!active || !turn) return;
+			if (active.turnId && turn.id && turn.id !== active.turnId) return;
+			active.resolve(turn);
 		},
 		"item/started": this.#itemProgress,
 		"item/updated": this.#itemProgress,
@@ -4523,7 +5384,7 @@ var CodexRunner = class {
 			const active = this.#activeTurn;
 			if (!active) return;
 			const item = params?.item;
-			if (item) this.#handleItemCompleted(item, active);
+			if (item) this.#handleItemCompleted(item, active, this.#agentFor(params));
 		},
 		"item/agentMessage/delta": (params) => {
 			if (!this.#activeTurn) return;
@@ -4531,7 +5392,7 @@ var CodexRunner = class {
 			if (typeof delta === "string" && delta) this.#emitDelta({
 				type: "text_delta",
 				text: delta
-			});
+			}, this.#agentFor(params)?.toolUseId ?? null);
 		},
 		"item/reasoning/textDelta": this.#reasoningDelta("item/reasoning/textDelta"),
 		"item/reasoning/summaryTextDelta": this.#reasoningDelta("item/reasoning/summaryTextDelta"),
@@ -4724,30 +5585,40 @@ var CodexRunner = class {
 		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) {
+	* natively via the delta notifications. `agent` is the sub-agent whose thread
+	* the item arrived on — undefined for the session's own. */
+	#handleItemProgress(item, active, agent) {
 		const id = `${active.nonce}:${item.id}`;
+		if (item.type === "subAgentActivity") {
+			this.#itemCompleted.subAgentActivity(item, active, id, agent);
+			return;
+		}
 		if (item.type === "commandExecution" && !active.toolUseEmitted.has(id)) {
 			active.toolUseEmitted.add(id);
-			this.#emitToolUse(id, "CodexCommand", { command: item.command });
+			this.#emitToolUse(id, "CodexCommand", { command: item.command }, agent);
 			return;
 		}
 		if (item.type === "mcpToolCall" && !active.toolUseEmitted.has(id)) {
 			active.toolUseEmitted.add(id);
-			this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments);
+			this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments, agent);
+			return;
+		}
+		if (item.type === "collabAgentToolCall" && !active.toolUseEmitted.has(id)) {
+			active.toolUseEmitted.add(id);
+			this.#emitToolUse(id, CODEX_COLLAB_TOOL, collabInput(item), agent);
 			return;
 		}
 		if (item.type === "imageGeneration" && !active.toolUseEmitted.has(id)) {
 			active.toolUseEmitted.add(id);
-			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
+			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item), agent);
 			if (item.savedPath) this.#emitFileProduced(item.savedPath, id);
 		}
 	}
-	#handleItemCompleted(item, active) {
+	#handleItemCompleted(item, active, agent) {
 		const id = `${active.nonce}:${item.id}`;
 		const handler = this.#itemCompleted[item.type];
 		if (handler) {
-			handler(item, active, id);
+			handler(item, active, id, agent);
 			return;
 		}
 		const unknown = item;
@@ -4768,67 +5639,121 @@ var CodexRunner = class {
 	* union has never heard of; those take the passthrough above.)
 	*/
 	#itemCompleted = {
-		userMessage: () => {},
-		agentMessage: (item, active, id) => {
+		userMessage: (item, active, _id, agent) => {
+			if (!agent) return;
+			const text = historyUserText(item);
+			if (!text) return;
+			this.#emit({
+				type: "user_message",
+				message: {
+					role: "user",
+					content: text
+				},
+				parentToolUseId: agent.toolUseId,
+				uuid: `${active.nonce}:${item.id}`
+			});
+		},
+		agentMessage: (item, active, id, agent) => {
 			const text = typeof item.text === "string" ? item.text : "";
 			this.#emitAssistant(id, [{
 				type: "text",
 				text
-			}]);
-			active.finalText = text;
+			}], agent?.toolUseId ?? null);
+			if (!agent) active.finalText = text;
 		},
-		reasoning: (item, _active, id) => {
+		reasoning: (item, _active, id, agent) => {
 			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
-			}]);
+			}], agent?.toolUseId ?? null);
 		},
-		commandExecution: (item, active, id) => {
+		commandExecution: (item, active, id, agent) => {
 			if (!active.toolUseEmitted.has(id)) {
 				active.toolUseEmitted.add(id);
-				this.#emitToolUse(id, "CodexCommand", { command: item.command });
+				this.#emitToolUse(id, "CodexCommand", { command: item.command }, agent);
 			}
 			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);
+			this.#emitToolResult(id, output, failed, void 0, agent?.toolUseId ?? null);
 		},
-		fileChange: (item, _active, id) => {
-			this.#emitToolUse(id, "CodexFileChange", { changes: item.changes });
+		fileChange: (item, _active, id, agent) => {
+			this.#emitToolUse(id, "CodexFileChange", { changes: item.changes }, agent);
 			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);
+			this.#emitToolResult(id, lines.join("\n") || item.status, item.status === "failed" || item.status === "declined", only?.diff ? parseUnifiedDiff(only.diff, only.path) : void 0, agent?.toolUseId ?? null);
 		},
-		mcpToolCall: (item, active, id) => {
+		mcpToolCall: (item, active, id, agent) => {
 			if (!active.toolUseEmitted.has(id)) {
 				active.toolUseEmitted.add(id);
-				this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments);
+				this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments, agent);
 			}
 			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);
+			this.#emitToolResult(id, item.error?.message ?? (item.result === void 0 || item.result === null ? "" : JSON.stringify(item.result)), isError, void 0, agent?.toolUseId ?? null);
 		},
-		webSearch: (item, _active, id) => {
-			this.#emitToolUse(id, "CodexWebSearch", { query: item.query });
-			this.#emitToolResult(id, "", false);
+		webSearch: (item, _active, id, agent) => {
+			this.#emitToolUse(id, "CodexWebSearch", { query: item.query }, agent);
+			this.#emitToolResult(id, "", false, void 0, agent?.toolUseId ?? null);
 		},
-		imageGeneration: (item, active, id) => {
+		imageGeneration: (item, active, id, agent) => {
 			active.toolUseEmitted.add(id);
-			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
+			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item), agent);
 			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");
+			this.#emitToolResult(id, lines.join("\n"), item.status === "failed", void 0, agent?.toolUseId ?? null);
 		},
-		imageView: (item, _active, id) => {
-			this.#emitToolUse(id, "CodexImageView", { path: item.path });
-			this.#emitToolResult(id, item.path, false);
+		imageView: (item, _active, id, agent) => {
+			this.#emitToolUse(id, "CodexImageView", { path: item.path }, agent);
+			this.#emitToolResult(id, item.path, false, void 0, agent?.toolUseId ?? null);
+		},
+		subAgentActivity: (item, _active, id, agent) => {
+			if (this.#replayingHistory) {
+				if (item.kind !== "started") return;
+				this.#emitToolUse(id, CODEX_AGENT_TOOL, {
+					...agentName(item.agentPath) ? { subagent_type: agentName(item.agentPath) } : {},
+					agentThreadId: item.agentThreadId,
+					...item.agentPath ? { agentPath: item.agentPath } : {}
+				}, agent);
+				this.#emitToolResult(id, "(ran in its own thread — its work is not part of this thread's stored history)", false, void 0, agent?.toolUseId ?? null);
+				return;
+			}
+			const record = this.#agents.get(item.agentThreadId) ?? this.#agents.open(item.agentThreadId, id, void 0, Date.now());
+			const name = agentName(item.agentPath);
+			const relabel = record.agentType === void 0 && name !== void 0;
+			if (relabel) record.agentType = name;
+			if (!record.anchored || relabel) {
+				record.anchored = true;
+				this.#emitToolUse(record.toolUseId, CODEX_AGENT_TOOL, {
+					...record.agentType ? { subagent_type: record.agentType } : {},
+					agentThreadId: item.agentThreadId,
+					...item.agentPath ? { agentPath: item.agentPath } : {}
+				}, agent);
+			}
+			if (item.kind === "interrupted") {
+				if (record.status === "running") {
+					this.#agents.settle(record, "failed");
+					this.#emitToolResult(record.toolUseId, "interrupted", true);
+				}
+				return;
+			}
+			if (item.kind !== "started" && record.status !== "running") this.#agents.revive(record);
+		},
+		collabAgentToolCall: (item, active, id, agent) => {
+			if (!active.toolUseEmitted.has(id)) {
+				active.toolUseEmitted.add(id);
+				this.#emitToolUse(id, CODEX_COLLAB_TOOL, collabInput(item), agent);
+			}
+			if (item.status === "inProgress") return;
+			const failed = item.status === "failed" || item.status === "declined";
+			this.#emitToolResult(id, failed ? item.status : "", failed, void 0, agent?.toolUseId ?? null);
 		}
 	};
-	#emitDelta(delta) {
+	#emitDelta(delta, parent) {
 		if (this.#config.includePartialMessages === false) return;
 		this.#emit({
 			type: "stream_delta",
@@ -4836,11 +5761,11 @@ var CodexRunner = class {
 				type: "content_block_delta",
 				delta
 			},
-			parentToolUseId: null,
+			parentToolUseId: parent,
 			uuid: randomUUID()
 		});
 	}
-	#emitAssistant(uuid, content) {
+	#emitAssistant(uuid, content, parent) {
 		this.#emit({
 			type: "assistant_message",
 			message: {
@@ -4848,11 +5773,19 @@ var CodexRunner = class {
 				content,
 				model: this.#model ?? this.#resolvedModel
 			},
-			parentToolUseId: null,
+			parentToolUseId: parent,
 			uuid
 		});
 	}
-	#emitToolUse(id, name, input) {
+	/** `agent` (rather than a bare parent id) because a nested call is also the
+	* agent's progress reading: `SubagentInfo.toolCount` ticks here, once per
+	* card — the `counted` set is what keeps an upserted re-emission (the
+	* finished imageGeneration input) from counting one picture twice. */
+	#emitToolUse(id, name, input, agent) {
+		if (agent && !agent.counted.has(id)) {
+			agent.counted.add(id);
+			agent.toolCount += 1;
+		}
 		this.#emit({
 			type: "assistant_message",
 			message: {
@@ -4865,11 +5798,11 @@ var CodexRunner = class {
 				}],
 				model: this.#model ?? this.#resolvedModel
 			},
-			parentToolUseId: null,
+			parentToolUseId: agent?.toolUseId ?? null,
 			uuid: `${id}-use`
 		});
 	}
-	#emitToolResult(toolUseId, content, isError, patch) {
+	#emitToolResult(toolUseId, content, isError, patch, parent = null) {
 		this.#emit({
 			type: "user_message",
 			message: {
@@ -4881,7 +5814,7 @@ var CodexRunner = class {
 					is_error: isError || void 0
 				}]
 			},
-			parentToolUseId: null,
+			parentToolUseId: parent,
 			synthetic: true,
 			patch,
 			uuid: `${toolUseId}-result`
@@ -5009,10 +5942,10 @@ var CodexRunner = class {
 		};
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
+		this.#contextUsage = contextReading(body) ?? this.#contextUsage;
+		if (body.type === "conversation_reset") this.#contextUsage = void 0;
 		this.#events.push(event);
-		for (const listener of this.#listeners) try {
-			listener(event);
-		} catch {}
+		this.#subscribers.emit(event);
 	}
 };
 //#endregion
@@ -5446,6 +6379,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, withHostTools, 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, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, truncateResultBlocks, withHostTools, withMcpTools };
 
 //# sourceMappingURL=index.mjs.map