@langchain/langgraph-sdk 1.9.27 → 1.9.29

package/dist/stream/controller.cjs

@@ -170,13 +170,23 @@ var StreamController = class {
 	*/
 	#submitGeneration = 0;
 	/**
-	* Thread ids we minted client-side on first `submit()`. Keeping them
-	* here lets `hydrate()` skip the `threads.getState()` round-trip —
-	* we know there is nothing checkpointed server-side yet (and the
-	* request would 404 and surface a spurious error to the UI).
+	* Thread ids this controller minted client-side on first `submit()`.
+	* `hydrate()` skips `threads.getState()` for these — we know there
+	* is nothing checkpointed yet. Cleared once dispatch commits the
+	* thread server-side.
 	*/
 	#selfCreatedThreadIds = /* @__PURE__ */ new Set();
 	/**
+	* Caller-supplied thread ids that 404'd on hydrate. Unlike
+	* {@link #selfCreatedThreadIds}, these are revalidated on every
+	* hydrate: another client may create the same id between visits.
+	* While marked missing, `submit()` still defers the root SSE pump
+	* until `run.start` / `commands` commits the row — joining
+	* `/stream/events` beforehand leaves a dead subscription on
+	* langgraph_api's in-mem runtime.
+	*/
+	#missingThreadIds = /* @__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
@@ -271,12 +281,14 @@ var StreamController = class {
 			rememberSelfCreatedThreadId: (threadId) => {
 				this.#selfCreatedThreadIds.add(threadId);
 			},
+			isSelfCreatedThreadId: (threadId) => this.#selfCreatedThreadIds.has(threadId) || this.#missingThreadIds.has(threadId),
 			hydrate: (threadId) => this.hydrate(threadId),
 			ensureThread: (threadId, deferRootPump) => this.#ensureThread(threadId, deferRootPump),
 			startDeferredRootPump: () => this.#startDeferredRootPump(),
 			abandonDeferredRootPump: () => this.#abandonDeferredRootPump(),
 			forgetSelfCreatedThreadId: (threadId) => {
 				this.#selfCreatedThreadIds.delete(threadId);
+				this.#missingThreadIds.delete(threadId);
 			},
 			waitForRootPumpReady: () => this.#rootPumpReady,
 			awaitNextTerminal: (signal) => this.#awaitNextTerminal(signal),
@@ -424,13 +436,17 @@ var StreamController = class {
 			...s,
 			isThreadLoading: true
 		}));
+		const hydratedThreadId = this.#currentThreadId;
 		let hydrationError;
 		let threadExists = false;
+		let threadMissing = false;
 		let threadActive = true;
 		try {
 			const state = await this.#fetchHydrationState();
+			if (this.#disposed || this.#currentThreadId !== hydratedThreadId) return;
 			threadExists = state != null;
 			threadActive = isThreadStateActive(state);
+			this.#missingThreadIds.delete(hydratedThreadId);
 			if (state?.values != null) {
 				/**
 				* `threads.getState()` returns the legacy `ThreadState` shape
@@ -515,6 +531,8 @@ var StreamController = class {
 				const activeIds = /* @__PURE__ */ new Set();
 				for (const task of state.tasks) {
 					if (!Array.isArray(task?.interrupts)) continue;
+					const checkpointNs = task?.checkpoint?.checkpoint_ns;
+					const namespace = typeof checkpointNs === "string" && checkpointNs.length > 0 ? checkpointNs.split("|").filter((segment) => segment.length > 0) : [...ROOT_NAMESPACE];
 					for (const interrupt of task.interrupts) {
 						const typed = interrupt;
 						const id = typed?.id;
@@ -522,7 +540,8 @@ var StreamController = class {
 						activeIds.add(id);
 						activeInterrupts.push(require_interrupts.normalizeInterruptForClient({
 							id,
-							value: typed?.value
+							value: typed?.value,
+							namespace: Array.isArray(typed?.namespace) ? [...typed.namespace] : namespace
 						}));
 					}
 				}
@@ -540,7 +559,7 @@ var StreamController = class {
 					...s,
 					error
 				}));
-			}
+			} else threadMissing = true;
 		} finally {
 			this.rootStore.setState((s) => ({
 				...s,
@@ -550,6 +569,20 @@ var StreamController = class {
 			else this.#resolveHydration();
 		}
 		/**
+		* Missing threads must not open `/stream/events`. The in-mem
+		* runtime accepts the join against a not-yet-created id but the
+		* subscription never attaches to the live channel — the first run
+		* then delivers 0 bytes until idle reconnect. Park the pump until
+		* `submit()`'s `run.start` creates the row (see
+		* {@link #startDeferredRootPump}). Tracked in `#missingThreadIds`
+		* (not `#selfCreatedThreadIds`) so a later hydrate revalidates —
+		* another client may create the same id between visits.
+		*/
+		if (threadMissing) {
+			this.#missingThreadIds.add(hydratedThreadId);
+			return;
+		}
+		/**
 		* 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
@@ -562,7 +595,7 @@ var StreamController = class {
 		* The transport replays from `seq=0` on the deferred subscribe, so
 		* nothing is missed.
 		*/
-		const thread = this.#ensureThread(this.#currentThreadId, !threadActive);
+		const thread = this.#ensureThread(hydratedThreadId, !threadActive);
 		/**
 		* Start the wildcard lifecycle watcher up-front for existing,
 		* active threads. The root content pump runs at `depth: 1`, which
@@ -686,7 +719,7 @@ var StreamController = class {
 	*/
 	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 (this.#disposed || threadId == null || params.namespace.length === 0 || !this.#rootPumpDeferred || this.#selfCreatedThreadIds.has(threadId) || this.#missingThreadIds.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);
@@ -894,14 +927,15 @@ var StreamController = class {
 	* oldest and picks the first entry whose `interruptId` has not already
 	* been resolved by a prior `respond()` call. That entry may be at the
 	* root (`namespace: []`) or inside a subgraph (non-empty `namespace`).
-	* This is **not** the same as {@link RootSnapshot.interrupts
-	* `rootStore.interrupts[0]`} / framework `stream.interrupt`, which only
-	* mirrors root-namespace interrupts for UI convenience.
+	* {@link RootSnapshot.interrupts `rootStore.interrupts`} /
+	* framework `stream.interrupts` mirrors the same pending interrupts
+	* (including nested namespaces) for UI rendering.
 	*
 	* Omitting `interruptId` is fine when exactly one interrupt is pending.
 	* When several can be active (parallel subagents, fan-out, nested
-	* graphs), pass an explicit `interruptId` (and `namespace` for subgraph
-	* interrupts) so you resume the interrupt the user acted on.
+	* graphs), pass an explicit `interruptId` so you resume the interrupt
+	* the user acted on. `namespace` is resolved automatically from
+	* `thread.interrupts` / `stream.interrupts` when omitted.
 	*
 	* To resume several interrupts pending at the same checkpoint in one
 	* command, use {@link respondAll} — sequential single `respond()` calls
@@ -909,9 +943,8 @@ var StreamController = class {
 	* others with no interrupted run to respond to.
 	*
 	* The server validates `namespace` against the pending interrupt. Root
-	* interrupts use `namespace: []` (the default when `namespace` is
-	* omitted). Subgraph interrupts require the exact tuple from
-	* `getThread()?.interrupts` — see the example below.
+	* interrupts use `namespace: []`. Subgraph interrupts carry the exact
+	* tuple on each {@link Interrupt} / {@link InterruptPayload} entry.
 	*
 	* @param response - Payload sent back to the interrupted namespace.
 	* @param options - Optional target (`interruptId` / `namespace`) and
@@ -932,33 +965,22 @@ var StreamController = class {
 	* );
 	* ```
 	*
-	* @example Multiple root interrupts — target by id
+	* @example Multiple / nested interrupts — target by id
 	* ```tsx
 	* for (const intr of stream.interrupts) {
 	*   await stream.respond(decide(intr.value), { interruptId: intr.id! });
 	* }
 	* ```
 	*
-	* @example Subgraph interrupt — read `namespace` from the thread stream
-	* ```tsx
-	* const thread = stream.getThread();
-	* for (const entry of thread?.interrupts ?? []) {
-	*   await stream.respond(buildResponse(entry.payload), {
-	*     interruptId: entry.interruptId,
-	*     namespace: entry.namespace,
-	*   });
-	* }
-	* ```
-	*
-	* Each {@link InterruptPayload} on `thread.interrupts` mirrors an
-	* `input.requested` event: `{ interruptId, payload, namespace }`.
-	* Nested interrupts may appear here but not on `stream.interrupts`.
+	* Each {@link InterruptPayload} on `thread.interrupts` and each
+	* {@link Interrupt} on `stream.interrupts` mirrors an
+	* `input.requested` event with its protocol `namespace`.
 	*/
 	async respond(response, options) {
 		if (this.#disposed || this.#thread == null) throw new Error("No active thread to respond to.");
 		const resolved = options?.interruptId != null ? {
 			interruptId: options.interruptId,
-			namespace: options.namespace ?? [...ROOT_NAMESPACE]
+			namespace: this.#resolveNamespaceForInterruptId(options.interruptId, options.namespace)
 		} : this.#resolveInterruptForResume();
 		if (resolved == null) throw new Error("No pending interrupt to respond to.");
 		const thread = this.#thread;
@@ -1028,11 +1050,10 @@ var StreamController = class {
 		const entries = Object.entries(responsesById);
 		if (entries.length === 0) throw new Error("respondAll() requires at least one response.");
 		const thread = this.#thread;
-		const pending = thread.interrupts;
 		const responses = entries.map(([interruptId, response]) => ({
 			interrupt_id: interruptId,
 			response: require_hitl_interrupt_payload.normalizeHitlResponseForServer(response),
-			namespace: pending.find((entry) => entry.interruptId === interruptId)?.namespace ?? [...ROOT_NAMESPACE]
+			namespace: this.#resolveNamespaceForInterruptId(interruptId)
 		}));
 		const prepared = options?.update != null ? this.#beginOptimistic(options.update) : void 0;
 		const dispatchUpdate = this.#resolveDispatchUpdate(options?.update, prepared);
@@ -1199,16 +1220,11 @@ var StreamController = class {
 	* Without this, the controller would be wedged in a state where:
 	*   - `#thread` is wired but no content pump is open
 	*   - `#rootPumpDeferred` stays `true`
-	*   - `selfCreatedThreadIds` still holds the id
 	*
-	* A retry submit on the same controller would see
-	* `wasSelfCreated=false` (because `currentThreadId` is no longer
-	* null), `#ensureThread(id, false)` would early-return because
-	* `#thread != null`, and the pump would never start. The thread
-	* would have an id committed to the URL but no live subscription.
-	*
-	* Tearing down `#thread` so the next submit re-runs `#ensureThread`
-	* from scratch is the simplest recovery — the failed dispatch
+	* A retry submit must re-run `#ensureThread` from scratch (with
+	* `deferRootPump` still true — the id stays in
+	* `#selfCreatedThreadIds` until a successful dispatch). Tearing
+	* down `#thread` is the simplest recovery; the failed dispatch
 	* means there was nothing to subscribe to anyway.
 	*/
 	#abandonDeferredRootPump() {
@@ -1411,16 +1427,14 @@ var StreamController = class {
 		this.#subgraphs.push(event);
 		this.#lifecycleLoading.handle(event);
 		/**
-		* Nested `input.requested` events (HITL inside a subagent /
-		* subgraph) are not observable via the narrow content pump. The
-		* `ThreadStream` itself already records them into
-		* `thread.interrupts`, which `#latestUnresolvedInterrupt()`
-		* consults — so HITL respond() works for any depth. Root-level
-		* interrupts are also mirrored into `rootStore.interrupts` here so
-		* UI state does not depend on the narrower content pump being the
-		* first consumer to see the event.
+		* `input.requested` events (including HITL inside a subagent /
+		* subgraph) are not always observable via the narrow content pump.
+		* Mirror every namespace into `rootStore.interrupts` here so UI
+		* state does not depend on the content pump being the first
+		* consumer. `ThreadStream.interrupts` is updated in parallel for
+		* resume targeting.
 		*/
-		this.#recordRootInterrupt(event);
+		this.#recordInterrupt(event);
 	}
 	/**
 	* Process one root-pump event and update all root projections.
@@ -1513,7 +1527,7 @@ var StreamController = class {
 			return;
 		}
 		if (event.method === "input.requested") {
-			this.#recordRootInterrupt(event);
+			this.#recordInterrupt(event);
 			return;
 		}
 		if (event.method === "lifecycle") event.params.data;
@@ -1641,21 +1655,22 @@ var StreamController = class {
 		}
 	}
 	/**
-	* Mirror root protocol interrupts into the root snapshot.
+	* Mirror protocol interrupts (any namespace) into the root snapshot.
 	*
 	* This can be called from both the wildcard lifecycle/input watcher and the
 	* root content pump. Store-level dedup keeps the user-facing list stable.
 	*/
-	#recordRootInterrupt(event) {
+	#recordInterrupt(event) {
 		if (event.method !== "input.requested") return;
-		if (!require_namespace.isRootNamespace(event.params.namespace)) return;
 		const data = event.params.data;
 		const interruptId = data?.interrupt_id;
 		if (typeof interruptId !== "string" || this.#resolvedInterrupts.has(interruptId)) return;
 		if (this.#hydratedActiveInterruptIds != null && !this.#hydratedActiveInterruptIds.has(interruptId)) return;
+		const namespace = Array.isArray(event.params.namespace) ? [...event.params.namespace] : [...ROOT_NAMESPACE];
 		const interrupt = require_interrupts.normalizeInterruptForClient({
 			id: interruptId,
-			value: data.payload
+			value: data.payload,
+			namespace
 		});
 		this.rootStore.setState((s) => {
 			if (s.interrupts.some((entry) => entry.id === interruptId)) return s;
@@ -1668,6 +1683,21 @@ var StreamController = class {
 		});
 	}
 	/**
+	* Resolve the protocol namespace for a targeted resume.
+	*
+	* Prefer an explicit caller-supplied namespace, then the matching
+	* {@link ThreadStream.interrupts} entry, then the UI mirror on
+	* `rootStore.interrupts`, finally root (`[]`).
+	*/
+	#resolveNamespaceForInterruptId(interruptId, explicitNamespace) {
+		if (explicitNamespace != null) return [...explicitNamespace];
+		const fromThread = this.#thread?.interrupts.find((entry) => entry.interruptId === interruptId)?.namespace;
+		if (fromThread != null) return [...fromThread];
+		const fromRoot = this.rootStore.getSnapshot().interrupts.find((entry) => entry.id === interruptId)?.namespace;
+		if (fromRoot != null) return [...fromRoot];
+		return [...ROOT_NAMESPACE];
+	}
+	/**
 	* Mark an interrupt resolved for replay filtering and mirror the
 	* removal into the root snapshot the framework hooks read.
 	*/