@langchain/langgraph-sdk 1.9.15 → 1.9.17

package/dist/stream/controller.js

@@ -1,20 +1,47 @@
-import { ensureMessageInstances } from "../ui/messages.js";
+import { ensureMessageInstances } from "./message-coercion.js";
 import { ToolCallAssembler } from "../client/stream/handles/tools.js";
+import "./constants.js";
 import { resolveInterruptTargetForHeadlessResume } from "../headless-tools.js";
 import { StreamStore } from "./store.js";
 import { ChannelRegistry } from "./channel-registry.js";
 import { normalizeHitlResponseForServer } from "../ui/hitl-interrupt-payload.js";
 import { normalizeInterruptForClient } from "../ui/interrupts.js";
-import { isInternalWorkNamespace, isLegacySubagentNamespace, isRootNamespace } from "./namespace.js";
+import { isInternalWorkNamespace, isLegacySubagentNamespace, isRootNamespace, namespaceKey } from "./namespace.js";
 import { SubagentDiscovery } from "./discovery/subagents.js";
 import { SubgraphDiscovery } from "./discovery/subgraphs.js";
+import "./discovery/index.js";
+import { collectSubgraphHostNamespaces, getHistoryPage, mapSubagentNamespaces, resolveSubagentNamespaces } from "./discovery/namespace-from-history.js";
 import { MessageMetadataTracker } from "./message-metadata-tracker.js";
 import { LifecycleLoadingTracker } from "./lifecycle-loading-tracker.js";
 import { RootMessageProjection } from "./root-message-projection.js";
+import { prepareOptimisticInput } from "./optimistic-input.js";
 import { EMPTY_QUEUE, SubmitCoordinator } from "./submit-coordinator.js";
-import { reconcileToolCallsFromMessages, upsertToolCall } from "./tool-calls.js";
+import { reconcileToolCallsFromMessages, seedToolCallsFromMessages, upsertToolCall } from "./tool-calls.js";
+import { v7 } from "uuid";
 import "@langchain/core/messages";
 //#region src/stream/controller.ts
+/**
+* Framework-agnostic controller for the experimental v2 stream.
+*
+* Responsibilities:
+*  - Owns at most one {@link ThreadStream} at a time (swapped on
+*    `hydrate(newThreadId)` or `dispose`).
+*  - Exposes three always-on observable surfaces via {@link StreamStore}:
+*      - `rootStore`      : root values/messages/toolCalls/interrupts/…
+*      - `subagentStore`  : discovery map of subagents (no content)
+*      - `subgraphStore`  : discovery map of subgraphs  (no content)
+*  - Owns a {@link ChannelRegistry} that framework selector hooks
+*    (`useMessages`, `useToolCalls`, `useExtension`, `useChannel`)
+*    use to lazily open per-namespace subscriptions.
+*  - Imperative run surface: `submit`, `stop`, `respond`, `joinStream`.
+*
+* A single multi-channel subscription (`values`, `lifecycle`, `input`,
+* `messages`, `tools`) powers every always-on projection and both
+* discovery runners. Selector hooks add their own (deduped)
+* subscriptions on top — so even a UI with many subagents only opens
+* one extra subscription per `(channels, namespace)` actually
+* rendered on screen.
+*/
 function isAbortLikeError(error) {
 	if (error == null || typeof error !== "object") return false;
 	const maybeError = error;
@@ -26,6 +53,43 @@ function lifecycleReason(event) {
 	if (event === "interrupted") return "interrupt";
 	return null;
 }
+/**
+* Decide whether a hydrated thread is *active* (a run is executing or
+* paused awaiting resume) from the `getState()` snapshot alone — no
+* extra request.
+*
+* Why this gate exists: a finished thread does not need either of the
+* always-on SSE pumps. Subagent/subgraph cards are already seeded from
+* the `getState()` messages and a single bounded `getHistory()` page, so
+* opening the depth-1 content pump + the wildcard lifecycle watcher only
+* to replay a completed run and then idle forever is pure waste. We open
+* the pumps eagerly only when the thread is active; otherwise they come
+* up on the first local `submit()` (the existing deferred-pump path) or
+* a thread swap that lands on an active thread.
+*
+* The gate is deliberately conservative: we only conclude *idle* when
+* the state proves it. A thread is treated as active unless `next` is a
+* present, empty array AND no task carries a pending interrupt:
+*  - `next` missing / not an array: unknown shape (a server or custom
+*    client may omit it). Treat as active so an already-running
+*    server-side run is still observed on reconnect — never silently
+*    disable streaming on an unfamiliar `getState` shape.
+*  - `next.length > 0`: the checkpoint still has nodes to execute, i.e.
+*    a run is mid-flight or paused at an interrupt.
+*  - `next` is `[]` but a `tasks[].interrupts` is non-empty: the thread
+*    is interrupted and a resume (which starts a run) must be observable.
+*  - `next` is `[]` and no pending interrupts: a completed run → idle.
+*/
+function isThreadStateActive(state) {
+	if (state == null) return true;
+	if (!Array.isArray(state.next)) return true;
+	if (state.next.length > 0) return true;
+	if (Array.isArray(state.tasks)) for (const task of state.tasks) {
+		const interrupts = task?.interrupts;
+		if (Array.isArray(interrupts) && interrupts.length > 0) return true;
+	}
+	return false;
+}
 const ROOT_NAMESPACE = [];
 /**
 * Channel set covered by the always-on root subscription. Exported so
@@ -111,11 +175,37 @@ var StreamController = class {
 	* request would 404 and surface a spurious error to the UI).
 	*/
 	#selfCreatedThreadIds = /* @__PURE__ */ new Set();
+	/**
+	* In-flight per-subagent namespace resolutions, keyed by tool-call
+	* id. De-dupes concurrent {@link resolveSubagentNamespace} calls so
+	* re-renders / multiple consumers of the same subagent don't issue
+	* parallel `getHistory` walks.
+	*/
+	#namespaceResolves = /* @__PURE__ */ new Map();
+	/**
+	* In-flight hydrate-time discovery seed ({@link #seedDiscoveryFromHistory}):
+	* a single bounded `getHistory` page that bulk-promotes every
+	* still-default subagent namespace and seeds subgraph hosts. Per-card
+	* {@link resolveSubagentNamespace} calls await this shared promise
+	* instead of each firing their own `getHistory` walk, so opening N
+	* cards right after reconnect costs one history read, not N. Re-armed
+	* per hydrate cycle and cleared once it settles.
+	*/
+	#discoverySeedPromise;
+	#scopedHistorySeeds = /* @__PURE__ */ new Map();
 	#rootEventListeners = /* @__PURE__ */ new Set();
 	#rootBus;
 	#activeRunId;
 	#localRunDepth = 0;
 	/**
+	* `true` once a root `values` event has been applied for the current
+	* optimistic run. Reset to `false` in {@link #beginOptimistic} and
+	* read in {@link #settleOptimistic}: when a run terminates without
+	* the server ever echoing a `values` snapshot, optimistically-merged
+	* non-message keys are rolled back to their pre-submit values.
+	*/
+	#sawValuesForRun = false;
+	/**
 	* Single-shot hydration promise. Exposed via `hydrationPromise`
 	* so Suspense wrappers can throw it until the first hydrate
 	* completes (resolve) or fails (reject). Reset whenever a new
@@ -150,7 +240,8 @@ var StreamController = class {
 				return () => {
 					this.#rootEventListeners.delete(listener);
 				};
-			}
+			},
+			trySeedFromHistory: (params) => this.#trySeedProjectionFromHistory(params)
 		};
 		this.registry = new ChannelRegistry(this.#rootBus);
 		this.subagentStore = this.#subagents.store;
@@ -188,6 +279,7 @@ var StreamController = class {
 			},
 			waitForRootPumpReady: () => this.#rootPumpReady,
 			awaitNextTerminal: (signal) => this.#awaitNextTerminal(signal),
+			awaitResumedRunTerminal: (signal) => this.#awaitResumedRunTerminal(signal),
 			onSubmitStart: () => {
 				this.#hydratedActiveInterruptIds = null;
 				this.#submitGeneration += 1;
@@ -195,7 +287,9 @@ var StreamController = class {
 			onRunStart: () => this.#markLocalRunStart(),
 			onRunCreated: (runId) => this.#notifyCreated(runId),
 			onRunCompleted: (reason, runId) => this.#notifyCompleted(reason, runId),
-			onRunEnd: () => this.#markLocalRunEnd()
+			onRunEnd: () => this.#markLocalRunEnd(),
+			beginOptimistic: (input) => this.#beginOptimistic(input),
+			settleOptimistic: (handle, event) => this.#settleOptimistic(handle, event)
 		});
 		this.#hydrationPromise = this.#createHydrationPromise();
 		/**
@@ -262,6 +356,8 @@ var StreamController = class {
 		const target = threadId === void 0 ? this.#currentThreadId : threadId;
 		const changed = target !== this.#currentThreadId;
 		this.#currentThreadId = target ?? null;
+		this.#discoverySeedPromise = void 0;
+		this.#scopedHistorySeeds.clear();
 		this.rootStore.setState((s) => ({
 			...s,
 			threadId: this.#currentThreadId
@@ -318,9 +414,11 @@ var StreamController = class {
 		}));
 		let hydrationError;
 		let threadExists = false;
+		let threadActive = true;
 		try {
 			const state = await this.#options.client.threads.getState(this.#currentThreadId);
 			threadExists = state != null;
+			threadActive = isThreadStateActive(state);
 			if (state?.values != null) {
 				/**
 				* `threads.getState()` returns the legacy `ThreadState` shape
@@ -332,11 +430,43 @@ var StreamController = class {
 				*/
 				const checkpointId = state.checkpoint?.checkpoint_id;
 				const parentCheckpointId = state.parent_checkpoint?.checkpoint_id ?? void 0;
+				/**
+				* Carry the checkpoint `step` from `getState()` metadata so the
+				* root message projection treats this seed as the authoritative
+				* latest superstep. The content pump's reconnect replay emits
+				* older checkpoints (lower step); marking the seed's step lets
+				* the projection reject those as stale instead of letting them
+				* remove the seeded message tail (the final assistant turn).
+				*/
+				const seedStep = state.metadata?.step;
 				const syntheticCheckpoint = typeof checkpointId === "string" ? {
 					id: checkpointId,
-					...parentCheckpointId != null ? { parent_id: parentCheckpointId } : {}
+					...parentCheckpointId != null ? { parent_id: parentCheckpointId } : {},
+					...typeof seedStep === "number" ? { step: seedStep } : {}
 				} : void 0;
 				this.#applyValues(state.values, syntheticCheckpoint);
+				/**
+				* Seed subagent discovery from checkpoint messages so deep-agent
+				* cards render on refresh without waiting for SSE replay. Zero
+				* extra HTTP (reuses the `getState` payload); mirrors the
+				* interrupt-seeding below. `#subagents` was cleared in
+				* `#teardownThread`, and `seedFromCheckpointMessages` is
+				* idempotent, so this is safe on re-hydrate.
+				*/
+				const seedMessages = state.values[this.#messagesKey];
+				if (Array.isArray(seedMessages)) this.#subagents.seedFromCheckpointMessages(seedMessages);
+			}
+			/**
+			* Converge to server truth: drop any optimistic messages the
+			* server state does not contain (`pending` / `failed` that were
+			* never persisted — e.g. a failed run's user message). Echoed
+			* ids were flipped to `"sent"` by `#applyValues` above and so are
+			* excluded from `unpersistedOptimisticIds()`.
+			*/
+			const unpersisted = this.#messageMetadata.unpersistedOptimisticIds();
+			if (unpersisted.size > 0) {
+				this.#rootMessages.dropOptimisticMessages(unpersisted);
+				this.#messageMetadata.forget(unpersisted);
 			}
 			/**
 			* Sync the visible interrupt list to the server's authoritative
@@ -390,27 +520,253 @@ var StreamController = class {
 			else this.#resolveHydration();
 		}
 		/**
-		* P0 fix: open the shared subscription on mount so in-flight
-		* server-side runs are observed even when no local `submit()` is
-		* active. The transport replays the run from `seq=0` on a rotating
-		* subscribe, so late-joining is free once the subscription exists.
-		* `isLoading` transitions are driven by the persistent root
-		* lifecycle listener registered in `#startRootPump`.
+		* Open the shared subscription on mount so in-flight server-side
+		* runs are observed even when no local `submit()` is active — BUT
+		* only when the thread is actually active (see
+		* {@link isThreadStateActive}). A finished thread's cards are seeded
+		* from `getState()` + the bounded `getHistory()` below, so opening
+		* the depth-1 content pump just to replay a completed run and idle
+		* forever is pure waste. When idle we take the deferred path: the
+		* pump (and watcher) come up on the first local `submit()` via
+		* {@link #startDeferredRootPump}, exactly like a self-created thread.
+		* The transport replays from `seq=0` on the deferred subscribe, so
+		* nothing is missed.
 		*/
-		const thread = this.#ensureThread(this.#currentThreadId);
+		const thread = this.#ensureThread(this.#currentThreadId, !threadActive);
 		/**
-		* Start the wildcard lifecycle watcher up-front for existing
-		* threads. The root content pump runs at `depth: 1`, which covers
-		* root-namespace and one-deep events but not arbitrarily-nested
-		* subagent / subgraph lifecycle — the dedicated watcher handles
-		* those.
+		* Start the wildcard lifecycle watcher up-front for existing,
+		* active threads. The root content pump runs at `depth: 1`, which
+		* covers root-namespace and one-deep events but not arbitrarily-
+		* nested subagent / subgraph lifecycle — the dedicated watcher
+		* handles those.
 		*
-		* For self-created (new) threads we skip — the watcher would 404
-		* against a not-yet-existent thread. `submitRun` / `respondInput`
-		* call `startLifecycleWatcher` on first submission to cover that
-		* case.
+		* Skipped when:
+		*  - the thread is idle/finished — there are no live events to
+		*    watch; discovery is seeded from history below, and the watcher
+		*    starts with the deferred pump on the first `submit()`.
+		*  - the thread is self-created (new) — the watcher would 404
+		*    against a not-yet-existent thread; `submitRun` / `respondInput`
+		*    call `startLifecycleWatcher` on first submission instead.
 		*/
-		if (threadExists) thread.startLifecycleWatcher();
+		if (threadExists && threadActive) thread.startLifecycleWatcher();
+		if (threadExists) {
+			/**
+			* Seed subgraph discovery and promote subagent execution
+			* namespaces from a single bounded `getHistory` page. Subgraph
+			* structure is not present in the root checkpoint messages
+			* (unlike subagents), so it can only be reconstructed from
+			* history. Fire-and-forget — not awaited into the hydration
+			* promise, so Suspense / first paint stay unblocked; cards fill
+			* in progressively when it resolves.
+			*
+			* Held in `#discoverySeedPromise` so lazy per-card
+			* {@link resolveSubagentNamespace} calls coalesce onto this single
+			* read instead of each firing their own `getHistory` walk.
+			*/
+			const seed = this.#seedDiscoveryFromHistory(this.#currentThreadId).finally(() => {
+				if (this.#discoverySeedPromise === seed) this.#discoverySeedPromise = void 0;
+			});
+			this.#discoverySeedPromise = seed;
+		}
+	}
+	/**
+	* One bounded, non-blocking `getHistory` read at hydrate that seeds
+	* subgraph hosts and bulk-promotes still-default subagent execution
+	* namespaces. O(1) in requests regardless of subagent/subgraph count.
+	*/
+	async #seedDiscoveryFromHistory(threadId) {
+		try {
+			const history = await getHistoryPage(this.#options.client, threadId, { limit: 20 });
+			if (this.#disposed || this.#currentThreadId !== threadId) return;
+			this.#primeScopedHistorySeedsFromHistory(threadId, history);
+			const hosts = collectSubgraphHostNamespaces(history);
+			this.#subgraphs.seedFromHistory(hosts);
+			const defaultOnlyIds = [...this.#subagents.snapshot.values()].filter(namespaceIsDefaultOnly).map((entry) => entry.id);
+			if (defaultOnlyIds.length > 0) {
+				const map = mapSubagentNamespaces(history, defaultOnlyIds, this.#messagesKey);
+				for (const [id, segment] of map) this.#subagents.applyExecutionNamespace(id, segment);
+			}
+		} catch {}
+	}
+	/**
+	* Lazily resolve a single subagent's execution namespace from
+	* checkpoint history. Intended call site: the first scoped
+	* `useMessages` / `useToolCalls` mount for a subagent whose namespace
+	* is still the default `tools:<toolCallId>`. A fallback for the
+	* hydrate-time bulk seed ({@link #seedDiscoveryFromHistory}) — most
+	* subagents are already promoted by the time a panel opens.
+	*
+	* Skips ids already promoted past default-only (SSE replay or a prior
+	* resolve). Concurrent calls for the same id share one `getHistory`
+	* walk via {@link #namespaceResolves}.
+	*
+	* @param toolCallId - Parent `task` tool-call id (the subagent's discovery key).
+	*/
+	async resolveSubagentNamespace(toolCallId) {
+		if (this.#disposed) return;
+		const threadId = this.#currentThreadId;
+		if (threadId == null) return;
+		if (!namespaceIsDefaultOnly(this.#subagents.snapshot.get(toolCallId))) return;
+		const inflight = this.#namespaceResolves.get(toolCallId);
+		if (inflight != null) return inflight;
+		const run = (async () => {
+			try {
+				/**
+				* Coalesce onto the hydrate-time discovery seed. That single
+				* bounded `getHistory` page bulk-promotes every default-only
+				* subagent, so when many cards mount at once (the common
+				* reconnect case) they all await this one read instead of each
+				* firing their own walk. Re-check after it settles: usually the
+				* bulk seed already promoted us and no further fetch is needed.
+				*/
+				const seed = this.#discoverySeedPromise;
+				if (seed != null) {
+					await seed;
+					if (this.#disposed || this.#currentThreadId !== threadId) return;
+					if (!namespaceIsDefaultOnly(this.#subagents.snapshot.get(toolCallId))) return;
+				}
+				const map = await resolveSubagentNamespaces(this.#options.client, threadId, [toolCallId], { messagesKey: this.#messagesKey });
+				if (this.#disposed || this.#currentThreadId !== threadId) return;
+				const segment = map.get(toolCallId);
+				if (segment != null) this.#subagents.applyExecutionNamespace(toolCallId, segment);
+			} catch {} finally {
+				this.#namespaceResolves.delete(toolCallId);
+			}
+		})();
+		this.#namespaceResolves.set(toolCallId, run);
+		return run;
+	}
+	/**
+	* Try to satisfy a scoped selector projection from checkpoint history
+	* instead of opening a scoped `/events` replay.
+	*
+	* This is only valid while the root pump is deferred, which means hydrate
+	* has classified the thread as idle/stale. Active and interrupted threads
+	* must keep using SSE so ongoing work and resumes are observed. For an idle
+	* thread, though, a late-mounted subagent card only needs the latest scoped
+	* checkpoint snapshot; opening `/events` just asks the server to replay work
+	* that already finished and can be slow for namespaces discovered from
+	* history.
+	*
+	* Returns `true` when the projection was handled without `/events`. That can
+	* mean either the store was seeded from namespace-specific history, or the
+	* projection targeted a default subagent namespace that should be skipped
+	* because hydrate promoted it to its execution namespace. Returns `false`
+	* when the caller should fall back to the normal subscription path.
+	*/
+	async #trySeedProjectionFromHistory(params) {
+		const threadId = this.#currentThreadId;
+		if (this.#disposed || threadId == null || params.namespace.length === 0 || !this.#rootPumpDeferred || this.#selfCreatedThreadIds.has(threadId)) return false;
+		if (await this.#skipDefaultSubagentProjection(params.namespace, threadId)) return true;
+		if (this.#disposed || this.#currentThreadId !== threadId || !this.#rootPumpDeferred) return false;
+		const seed = await this.#getScopedHistorySeed(threadId, params.namespace);
+		if (seed == null || this.#disposed || this.#currentThreadId !== threadId || !this.#rootPumpDeferred) return false;
+		if (await this.#skipDefaultSubagentProjection(params.namespace, threadId)) return true;
+		if (params.kind === "messages") {
+			params.store.setValue(seed.messages);
+			return true;
+		}
+		params.store.setValue(seed.toolCalls);
+		return true;
+	}
+	/**
+	* Suppress subscriptions for placeholder subagent namespaces once hydrate has
+	* resolved the real execution namespace.
+	*
+	* Deep-agent discovery first creates cards at `tools:<toolCallId>`. The
+	* actual worker history usually lives under a different checkpoint namespace
+	* such as `tools:<uuid>`, and hydrate resolves that mapping from the bounded
+	* root history seed. React/Vue/Svelte/Angular selector effects can mount
+	* while that seed is still in flight, so this helper waits for it and then
+	* returns `true` when the original placeholder namespace is stale. Returning
+	* `true` tells the projection runtime not to open an `/events` subscription
+	* for the wrong namespace; the framework will re-render with the promoted
+	* card namespace and acquire the real projection.
+	*/
+	async #skipDefaultSubagentProjection(namespace, threadId) {
+		const toolCallId = defaultSubagentToolCallId(namespace);
+		if (toolCallId == null) return false;
+		if (!namespaceIsDefaultOnly(this.#subagents.snapshot.get(toolCallId))) return false;
+		const seed = this.#discoverySeedPromise;
+		if (seed != null) await seed;
+		if (this.#disposed || this.#currentThreadId !== threadId) return true;
+		return !namespaceIsDefaultOnly(this.#subagents.snapshot.get(toolCallId));
+	}
+	/**
+	* Load and cache the latest checkpoint snapshot for one scoped namespace.
+	*
+	* `useMessages(stream, subagent)` and `useToolCalls(stream, subagent)` often
+	* mount together. Both need the same namespace-specific history page, so the
+	* controller keeps an in-flight promise per `threadId + checkpoint_ns`.
+	* The cache may already be primed by the hydrate-time discovery history page;
+	* otherwise this method performs a narrow `checkpoint_ns` read and derives
+	* both projection snapshots from that one response:
+	*
+	* - `messages` are coerced with the stream-local message coercion rules, so
+	*   serialized `content_blocks` and tool-call metadata hydrate correctly.
+	* - `toolCalls` are reconstructed from AI tool calls plus matching
+	*   ToolMessages, enough for finished/stale card panels without replaying
+	*   the `tools` channel.
+	*
+	* Returns `null` when history does not contain usable values, or the request
+	* fails. Callers treat that as a signal to fall back to `/events` so custom
+	* servers or unusual state shapes still work.
+	*/
+	#getScopedHistorySeed(threadId, namespace) {
+		const checkpointNs = namespaceKey(namespace);
+		const key = `${threadId}|${checkpointNs}`;
+		const existing = this.#scopedHistorySeeds.get(key);
+		if (existing != null) return existing;
+		const seed = (async () => {
+			try {
+				const values = (await getHistoryPage(this.#options.client, threadId, {
+					limit: 1,
+					checkpoint: { checkpoint_ns: checkpointNs }
+				}))[0]?.values;
+				if (values == null || typeof values !== "object") return null;
+				const messages = extractAndCoerceMessagesWithFallback(values, this.#messagesKey);
+				if (messages == null) return null;
+				return {
+					messages,
+					toolCalls: seedToolCallsFromMessages(namespace, messages)
+				};
+			} catch {
+				return null;
+			}
+		})();
+		this.#scopedHistorySeeds.set(key, seed);
+		return seed;
+	}
+	/**
+	* Reuse the hydrate-time discovery history page as scoped projection data
+	* when it already contains checkpoint values for a namespace.
+	*
+	* The discovery read is required to resolve subagent execution namespaces and
+	* subgraph hosts. That same page often includes the latest values for those
+	* namespaces, so priming `#scopedHistorySeeds` here lets later
+	* `useMessages(stream, subagent)` / `useToolCalls(stream, subagent)` mounts
+	* hydrate from memory instead of issuing an immediate second `getHistory`
+	* request. If a namespace is not present in the bounded page,
+	* `#getScopedHistorySeed` still falls back to a targeted `checkpoint_ns`
+	* history read.
+	*/
+	#primeScopedHistorySeedsFromHistory(threadId, history) {
+		for (const state of history) {
+			const checkpointNs = state.checkpoint?.checkpoint_ns;
+			if (typeof checkpointNs !== "string" || checkpointNs.length === 0) continue;
+			const namespace = checkpointNs.split("\0").filter((segment) => segment.length > 0);
+			if (namespace.length === 0) continue;
+			const key = `${threadId}|${namespaceKey(namespace)}`;
+			if (this.#scopedHistorySeeds.has(key)) continue;
+			const values = state.values;
+			if (values == null || typeof values !== "object") continue;
+			const messages = extractAndCoerceMessagesWithFallback(values, this.#messagesKey);
+			if (messages == null) continue;
+			this.#scopedHistorySeeds.set(key, Promise.resolve({
+				messages,
+				toolCalls: seedToolCallsFromMessages(namespace, messages)
+			}));
+		}
 	}
 	/**
 	* Submit input to the active thread.
@@ -575,15 +931,18 @@ var StreamController = class {
 			namespace: options.namespace ?? [...ROOT_NAMESPACE]
 		} : this.#resolveInterruptForResume();
 		if (resolved == null) throw new Error("No pending interrupt to respond to.");
+		const thread = this.#thread;
 		try {
-			await this.#thread.respondInput({
-				namespace: resolved.namespace,
-				interrupt_id: resolved.interruptId,
-				response: normalizeHitlResponseForServer(response),
-				config: options?.config,
-				metadata: options?.metadata
+			await this.#submitter.dispatchResume(async () => {
+				await thread.respondInput({
+					namespace: resolved.namespace,
+					interrupt_id: resolved.interruptId,
+					response: normalizeHitlResponseForServer(response),
+					config: options?.config,
+					metadata: options?.metadata
+				});
+				this.#markInterruptResolvedInRootStore(resolved.interruptId);
 			});
-			this.#markInterruptResolvedInRootStore(resolved.interruptId);
 		} catch (error) {
 			if (this.#disposed && isAbortLikeError(error)) return;
 			throw error;
@@ -634,19 +993,22 @@ var StreamController = class {
 		if (this.#disposed || this.#thread == null) throw new Error("No active thread to respond to.");
 		const entries = Object.entries(responsesById);
 		if (entries.length === 0) throw new Error("respondAll() requires at least one response.");
-		const pending = this.#thread.interrupts;
+		const thread = this.#thread;
+		const pending = thread.interrupts;
 		const responses = entries.map(([interruptId, response]) => ({
 			interrupt_id: interruptId,
 			response: normalizeHitlResponseForServer(response),
 			namespace: pending.find((entry) => entry.interruptId === interruptId)?.namespace ?? [...ROOT_NAMESPACE]
 		}));
 		try {
-			await this.#thread.respondInput({
-				responses,
-				config: options?.config,
-				metadata: options?.metadata
+			await this.#submitter.dispatchResume(async () => {
+				await thread.respondInput({
+					responses,
+					config: options?.config,
+					metadata: options?.metadata
+				});
+				for (const { interrupt_id: interruptId } of responses) this.#markInterruptResolvedInRootStore(interruptId);
 			});
-			for (const { interrupt_id: interruptId } of responses) this.#markInterruptResolvedInRootStore(interruptId);
 		} catch (error) {
 			if (this.#disposed && isAbortLikeError(error)) return;
 			throw error;
@@ -843,6 +1205,7 @@ var StreamController = class {
 		this.#lifecycleLoading.reset();
 		this.#subagents.reset();
 		this.#subgraphs.reset();
+		this.#scopedHistorySeeds.clear();
 		this.#activeRunId = void 0;
 		this.#localRunDepth = 0;
 		this.#messageMetadata.reset();
@@ -1119,9 +1482,67 @@ var StreamController = class {
 	* @param raw - Raw `values` channel payload.
 	* @param checkpoint - Optional checkpoint envelope paired with the values event.
 	*/
+	/**
+	* Apply a submit input optimistically to the root projection before
+	* the server responds. Mints stable ids for id-less messages (so the
+	* server echo reconciles by id), appends them to the projection, and
+	* shallow-merges non-message input keys into `values`.
+	*
+	* Returns the dispatch payload (id-injected) for the coordinator to
+	* send, plus an {@link OptimisticHandle} for terminal reconciliation.
+	* Returns `undefined` when optimistic UI is disabled or there is
+	* nothing to echo, in which case the coordinator dispatches the raw
+	* input unchanged.
+	*
+	* @param input - Raw input passed to `submit()`.
+	*/
+	#beginOptimistic(input) {
+		if (this.#options.optimistic === false) return void 0;
+		if (input == null || typeof input !== "object" || Array.isArray(input)) return;
+		const prepared = prepareOptimisticInput(input, this.#messagesKey, () => v7());
+		const extraKeys = Object.keys(prepared.extraValues);
+		if (prepared.echoedIds.length === 0 && extraKeys.length === 0) return;
+		const currentValues = this.rootStore.getSnapshot().values;
+		const restoreKeys = extraKeys.map((key) => ({
+			key,
+			hadKey: Object.prototype.hasOwnProperty.call(currentValues, key),
+			prevValue: currentValues[key]
+		}));
+		this.#sawValuesForRun = false;
+		this.#rootMessages.appendOptimistic(prepared.optimisticMessages, prepared.extraValues);
+		if (prepared.echoedIds.length > 0) this.#messageMetadata.markPending(prepared.echoedIds);
+		return {
+			dispatchInput: prepared.dispatchInput,
+			handle: {
+				echoedIds: prepared.echoedIds,
+				restoreKeys
+			}
+		};
+	}
+	/**
+	* Reconcile optimistic state when a run terminates.
+	*
+	*   - Messages: any echoed id still `"pending"` (never echoed by the
+	*     server) is flipped to `"sent"` on success/interrupt, or
+	*     `"failed"` on failure/abort. Ids the server already echoed were
+	*     flipped to `"sent"` in {@link #applyValues} and are untouched.
+	*   - Non-message keys: rolled back to their pre-submit values when no
+	*     server `values` event landed during the run (otherwise the
+	*     server snapshot already reconciled them). Skipped on abort,
+	*     where a superseding run (or `stop()`) owns subsequent state.
+	*
+	* @param handle - Handle returned by {@link #beginOptimistic}.
+	* @param event  - Terminal lifecycle event for the run.
+	*/
+	#settleOptimistic(handle, event) {
+		const failed = event === "failed" || event === "aborted";
+		this.#messageMetadata.resolvePending(handle.echoedIds, failed ? "failed" : "sent");
+		if (event !== "aborted" && !this.#sawValuesForRun) this.#rootMessages.restoreValueKeys(handle.restoreKeys);
+	}
 	#applyValues(raw, checkpoint) {
 		if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return;
 		const state = raw;
+		this.#sawValuesForRun = true;
 		/**
 		* Surface parent_checkpoint per-message when the values event
 		* carries the lightweight checkpoint envelope (populated by
@@ -1146,15 +1567,18 @@ var StreamController = class {
 			nextValues = state;
 			nextMessages = [];
 		}
-		this.#rootMessages.applyValues(nextValues, nextMessages);
-		if (nextMessages.length > 0) this.rootStore.setState((s) => {
-			const toolCalls = reconcileToolCallsFromMessages(s.toolCalls, nextMessages);
-			if (toolCalls === s.toolCalls) return s;
-			return {
-				...s,
-				toolCalls
-			};
-		});
+		this.#rootMessages.applyValues(nextValues, nextMessages, { step: checkpoint?.step });
+		if (nextMessages.length > 0) {
+			this.#messageMetadata.resolvePending(nextMessages.map((m) => m.id).filter((id) => typeof id === "string"), "sent");
+			this.rootStore.setState((s) => {
+				const toolCalls = reconcileToolCallsFromMessages(s.toolCalls, nextMessages);
+				if (toolCalls === s.toolCalls) return s;
+				return {
+					...s,
+					toolCalls
+				};
+			});
+		}
 	}
 	/**
 	* Mirror root protocol interrupts into the root snapshot.
@@ -1213,8 +1637,25 @@ var StreamController = class {
 	* @param signal - Abort signal for the local submit lifecycle.
 	*/
 	#awaitNextTerminal(signal) {
+		return this.#awaitRootTerminal(signal, { skipInterruptedUntilRunning: false });
+	}
+	/**
+	* Resolve on the resumed run's root terminal lifecycle.
+	*
+	* Unlike {@link #awaitNextTerminal}, ignores `interrupted` events until a
+	* root `running` lifecycle has been observed. Headless-tool flows can emit
+	* a stale `interrupted` for the run being resumed after `input.requested`
+	* but before `respondInput` calls `#prepareForNextRun`; accepting that
+	* terminal would unsubscribe the watcher before the resumed run's `failed`
+	* terminal arrives.
+	*/
+	#awaitResumedRunTerminal(signal) {
+		return this.#awaitRootTerminal(signal, { skipInterruptedUntilRunning: true });
+	}
+	#awaitRootTerminal(signal, options) {
 		return new Promise((resolve) => {
 			let settled = false;
+			let sawRunning = false;
 			function finish(result) {
 				if (settled) return;
 				settled = true;
@@ -1229,12 +1670,19 @@ var StreamController = class {
 				if (event.method !== "lifecycle") return;
 				if (!isRootNamespace(event.params.namespace)) return;
 				const lifecycle = event.params.data;
+				if (lifecycle?.event === "running") {
+					sawRunning = true;
+					return;
+				}
 				if (lifecycle?.event === "completed") setTimeout(() => finish({ event: "completed" }), 0);
 				else if (lifecycle?.event === "failed") setTimeout(() => finish({
 					event: "failed",
 					error: lifecycle.error
 				}), 0);
-				else if (lifecycle?.event === "interrupted") setTimeout(() => finish({ event: "interrupted" }), 0);
+				else if (lifecycle?.event === "interrupted") {
+					if (options.skipInterruptedUntilRunning && !sawRunning) return;
+					setTimeout(() => finish({ event: "interrupted" }), 0);
+				}
 			};
 			const unsubscribeRoot = this.#rootBus.subscribe(onEvent);
 			const unsubscribeThread = this.#thread?.onEvent(onEvent);
@@ -1261,6 +1709,23 @@ var StreamController = class {
 	}
 };
 /**
+* True when a subagent still sits on its default `tools:<toolCallId>`
+* namespace — i.e. no execution namespace has been observed (via SSE
+* replay) or resolved (via history) yet. Used to gate lazy namespace
+* resolution so already-promoted subagents aren't re-fetched.
+*/
+function namespaceIsDefaultOnly(entry) {
+	if (entry == null) return false;
+	return entry.namespace.length === 1 && entry.namespace[0] === `tools:${entry.id}`;
+}
+function defaultSubagentToolCallId(namespace) {
+	if (namespace.length !== 1) return void 0;
+	const segment = namespace[0];
+	if (!segment.startsWith("tools:")) return void 0;
+	const id = segment.slice(6);
+	return id.length > 0 ? id : void 0;
+}
+/**
 * Extract and coerce the configured messages key from a values object.
 *
 * @param values - State values object to read from.
@@ -1271,6 +1736,12 @@ function extractAndCoerceMessages(values, messagesKey) {
 	if (!Array.isArray(raw)) return [];
 	return ensureMessageInstances(raw);
 }
+function extractAndCoerceMessagesWithFallback(values, messagesKey) {
+	let raw = values[messagesKey];
+	if (!Array.isArray(raw) && messagesKey !== "messages") raw = values.messages;
+	if (!Array.isArray(raw)) return null;
+	return ensureMessageInstances(raw);
+}
 //#endregion
 export { ROOT_PUMP_CHANNELS, StreamController };