@langchain/langgraph-sdk 1.9.9 → 1.9.10

package/dist/stream/controller.d.ts

@@ -1,6 +1,6 @@
 import { ThreadStream } from "../client/stream/index.js";
 import { StreamStore } from "./store.js";
-import { RootSnapshot, StreamControllerOptions, StreamStopOptions, StreamSubmitOptions } from "./types.js";
+import { RootSnapshot, StreamControllerOptions, StreamRespondAllOptions, StreamRespondOptions, StreamStopOptions, StreamSubmitOptions } from "./types.js";
 import { ChannelRegistry } from "./channel-registry.js";
 import { SubagentMap } from "./discovery/subagents.js";
 import { SubgraphByNodeMap, SubgraphMap } from "./discovery/subgraphs.js";
@@ -61,9 +61,11 @@ declare class StreamController<StateType extends object = Record<string, unknown
    */
   hydrate(threadId?: string | null): Promise<void>;
   /**
-   * Submit input or a resume command to the active thread.
+   * Submit input to the active thread.
    *
-   * @param input - Input payload for a new run; `null`/`undefined` submits no input.
+   * To resume a pending interrupt, use {@link respond} instead.
+   *
+   * @param input - Input payload for a new run.
    * @param options - Per-run config, metadata, multitask behavior, and callbacks.
    */
   submit(input: unknown, options?: StreamSubmitOptions<StateType, ConfigurableType>): Promise<void>;
@@ -96,15 +98,116 @@ declare class StreamController<StateType extends object = Record<string, unknown
    */
   clearQueue(): Promise<void>;
   /**
-   * Respond to a pending protocol interrupt.
+   * Respond to a single pending protocol interrupt.
+   *
+   * When `options.interruptId` is omitted, resolution walks
+   * {@link ThreadStream.interrupts `thread.interrupts`} from newest to
+   * 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.
+   *
+   * 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.
+   *
+   * To resume several interrupts pending at the same checkpoint in one
+   * command, use {@link respondAll} — sequential single `respond()` calls
+   * would not work, since the first resume starts a run, leaving the
+   * 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.
+   *
+   * @param response - Payload sent back to the interrupted namespace.
+   * @param options - Optional target (`interruptId` / `namespace`) and
+   *   run-level `config` / `metadata` folded into the run that services
+   *   the resume (model/user config, trigger source, test flags, …).
+   *   Equivalent to the same fields on {@link StreamSubmitOptions}.
+   *
+   * @example Single pending interrupt (safe to omit a target)
+   * ```ts
+   * await controller.respond({ approved: true });
+   * ```
+   *
+   * @example Carry run config / metadata onto the resume
+   * ```ts
+   * await controller.respond(
+   *   { approved: true },
+   *   { config: { configurable: { model: "gpt-4o" } }, metadata: { source: "ui" } },
+   * );
+   * ```
+   *
+   * @example Multiple root 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`.
+   */
+  respond(response: unknown, options?: StreamRespondOptions<ConfigurableType>): Promise<void>;
+  /**
+   * Resume several pending interrupts at the same checkpoint in a single
+   * command.
+   *
+   * Required when a run pauses on multiple interrupts simultaneously
+   * (e.g. parallel tool-authorization prompts): a single
+   * `Command({ resume })` carrying every interrupt's payload resumes them
+   * together. Sequential {@link respond} calls would fail because the
+   * first resume starts a run, leaving the rest with no interrupted run to
+   * respond to.
+   *
+   * `responsesById` maps each pending `interruptId` to the payload sent
+   * back to it, so different interrupts can receive different responses
+   * (approve one, deny another). To send the *same* payload to several
+   * interrupts, build the map with that value for each id, e.g.
+   * `Object.fromEntries(ids.map((id) => [id, response]))`.
+   *
+   * The server resumes by `interruptId`, so namespaces are resolved
+   * internally from `getThread()?.interrupts` and need not be supplied.
+   *
+   * @param responsesById - Map of pending `interruptId` to its response
+   *   payload. Must contain at least one entry.
+   * @param options - Optional run-level `config` / `metadata` folded into
+   *   the single run that services the batched resume. Equivalent to the
+   *   same fields on {@link StreamSubmitOptions}.
+   *
+   * @example Distinct payloads per interrupt
+   * ```tsx
+   * await stream.respondAll({
+   *   [interruptA.id]: { approved: true },
+   *   [interruptB.id]: { approved: false },
+   * });
+   * ```
    *
-   * @param response - Payload to send back to the interrupted namespace.
-   * @param target - Optional explicit interrupt id and namespace; defaults to the latest unresolved interrupt.
+   * @example Same payload to every pending interrupt
+   * ```tsx
+   * await stream.respondAll(
+   *   Object.fromEntries(stream.interrupts.map((i) => [i.id!, { approved: true }])),
+   * );
+   * ```
    */
-  respond(response: unknown, target?: {
-    interruptId: string;
-    namespace?: string[];
-  }): Promise<void>;
+  respondAll(responsesById: Record<string, unknown>, options?: StreamRespondAllOptions<ConfigurableType>): Promise<void>;
   /**
    * Dispose the active thread, subscriptions, registry entries, and listeners.
    */

package/dist/stream/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","names":[],"sources":["../../src/stream/controller.ts"],"mappings":";;;;;;;;;;;;;;;AA0GA;cAAa,kBAAA,WAA6B,OAAA;;;AAkC1C;;;;;;;;;;;cAAa,gBAAA,4BACgB,MAAA,8EAEO,MAAA;EAAA;WAEzB,SAAA,EAAW,WAAA,CAAY,YAAA,CAAa,SAAA,EAAW,aAAA;EAAA,SAC/C,aAAA,EAAe,WAAA,CAAY,WAAA;EAAA,SAC3B,aAAA,EAAe,WAAA,CAAY,WAAA;EAAA,SAC3B,mBAAA,EAAqB,WAAA,CAAY,iBAAA;EAAA,SACjC,oBAAA,EAAsB,WAAA,CAAY,kBAAA;EAAA,SAClC,UAAA,EAAY,WAAA,CAAY,uBAAA,CAAwB,SAAA;EAAA,SAChD,QAAA,EAAU,eAAA;EAAA;;;;;EAyFnB,WAAA,CAAY,OAAA,EAAS,uBAAA,CAAwB,SAAA;EA6UF;;;;;;;EAAA,IA9NvC,gBAAA,CAAA,GAAoB,OAAA;EAiVrB;;;;;;;;EA5SG,OAAA,CAAQ,QAAA,mBAA2B,OAAA;EArPzC;;;;;;EA4aM,MAAA,CACJ,KAAA,WACA,OAAA,GAAU,mBAAA,CAAoB,SAAA,EAAW,gBAAA,IACxC,OAAA;EA7aqD;;;;;;EAublD,IAAA,CAAK,OAAA,GAAU,iBAAA,GAAoB,OAAA;EApbhC;;;;EAwcH,UAAA,CAAA,GAAc,OAAA;EAvcuB;;;;;;;;;;;EAugBrC,YAAA,CAAa,EAAA,WAAa,OAAA;EA7TR;;;EAoUlB,UAAA,CAAA,GAAc,OAAA;EAxGd;;;;;;EAkHA,OAAA,CACJ,QAAA,WACA,MAAA;IAAW,WAAA;IAAqB,SAAA;EAAA,IAC/B,OAAA;EAxGsC;;;EAwInC,OAAA,CAAA,GAAW,OAAA;EApDE;;;;;;;;;;;;;;;EA6EnB,QAAA,CAAA;EAwCqB;;;;;EAZrB,SAAA,CAAA,GAAa,YAAA;;;;;;;;EAWb,eAAA,CACE,QAAA,GAAW,MAAA,EAAQ,YAAA;AAAA"}
+{"version":3,"file":"controller.d.ts","names":[],"sources":["../../src/stream/controller.ts"],"mappings":";;;;;;;;;;;;;;;AAyGA;cAAa,kBAAA,WAA6B,OAAA;;;AAkC1C;;;;;;;;;;;cAAa,gBAAA,4BACgB,MAAA,8EAEO,MAAA;EAAA;WAEzB,SAAA,EAAW,WAAA,CAAY,YAAA,CAAa,SAAA,EAAW,aAAA;EAAA,SAC/C,aAAA,EAAe,WAAA,CAAY,WAAA;EAAA,SAC3B,aAAA,EAAe,WAAA,CAAY,WAAA;EAAA,SAC3B,mBAAA,EAAqB,WAAA,CAAY,iBAAA;EAAA,SACjC,oBAAA,EAAsB,WAAA,CAAY,kBAAA;EAAA,SAClC,UAAA,EAAY,WAAA,CAAY,uBAAA,CAAwB,SAAA;EAAA,SAChD,QAAA,EAAU,eAAA;EAAA;;;;;EAyFnB,WAAA,CAAY,OAAA,EAAS,uBAAA,CAAwB,SAAA;EAmUF;;;;;;;EAAA,IAhOvC,gBAAA,CAAA,GAAoB,OAAA;EAgZS;;;;;;;;EA3W3B,OAAA,CAAQ,QAAA,mBAA2B,OAAA;EA4hBpB;;;;;;;;EAnWf,MAAA,CACJ,KAAA,WACA,OAAA,GAAU,mBAAA,CAAoB,SAAA,EAAW,gBAAA,IACxC,OAAA;EAnaM;;;;;;EA6aH,IAAA,CAAK,OAAA,GAAU,iBAAA,GAAoB,OAAA;EA5aL;;;;EAgc9B,UAAA,CAAA,GAAc,OAAA;EA9bU;;;;;;;;;;;EA8fxB,YAAA,CAAa,EAAA,WAAa,OAAA;EAlaX;;;EAyaf,UAAA,CAAA,GAAc,OAAA;EAtUI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8YlB,OAAA,CACJ,QAAA,WACA,OAAA,GAAU,oBAAA,CAAqB,gBAAA,IAC9B,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyEG,UAAA,CACJ,aAAA,EAAe,MAAA,mBACf,OAAA,GAAU,uBAAA,CAAwB,gBAAA,IACjC,OAAA;;;;EAmCG,OAAA,CAAA,GAAW,OAAA;;;;;;;;;;;;;;;;EAyBjB,QAAA,CAAA;;;;;;EA4BA,SAAA,CAAA,GAAa,YAAA;;;;;;;;EAWb,eAAA,CACE,QAAA,GAAW,MAAA,EAAQ,YAAA;AAAA"}

package/dist/stream/controller.js

@@ -1,6 +1,6 @@
 import { ensureMessageInstances } from "../ui/messages.js";
 import { ToolCallAssembler } from "../client/stream/handles/tools.js";
-import { buildResumeRunInput, resolveInterruptTargetForHeadlessResume } from "../headless-tools.js";
+import { resolveInterruptTargetForHeadlessResume } from "../headless-tools.js";
 import { StreamStore } from "./store.js";
 import { ChannelRegistry } from "./channel-registry.js";
 import { isInternalWorkNamespace, isLegacySubagentNamespace, isRootNamespace } from "./namespace.js";
@@ -186,14 +186,6 @@ var StreamController = class {
 			},
 			waitForRootPumpReady: () => this.#rootPumpReady,
 			awaitNextTerminal: (signal) => this.#awaitNextTerminal(signal),
-			buildResumeRunInput: (resume) => {
-				const thread = this.#thread;
-				if (thread == null) return null;
-				return buildResumeRunInput(resume, thread.interrupts, this.#resolvedInterrupts);
-			},
-			markInterruptResolved: (interruptId) => {
-				this.#resolvedInterrupts.add(interruptId);
-			},
 			onSubmitStart: () => {
 				this.#hydratedActiveInterruptIds = null;
 				this.#submitGeneration += 1;
@@ -419,9 +411,11 @@ var StreamController = class {
 		if (threadExists) thread.startLifecycleWatcher();
 	}
 	/**
-	* Submit input or a resume command to the active thread.
+	* Submit input to the active thread.
+	*
+	* To resume a pending interrupt, use {@link respond} instead.
 	*
-	* @param input - Input payload for a new run; `null`/`undefined` submits no input.
+	* @param input - Input payload for a new run.
 	* @param options - Per-run config, metadata, multitask behavior, and callbacks.
 	*/
 	async submit(input, options) {
@@ -505,25 +499,152 @@ var StreamController = class {
 		await this.#submitter.clearQueue();
 	}
 	/**
-	* Respond to a pending protocol interrupt.
+	* Respond to a single pending protocol interrupt.
+	*
+	* When `options.interruptId` is omitted, resolution walks
+	* {@link ThreadStream.interrupts `thread.interrupts`} from newest to
+	* 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.
+	*
+	* 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.
+	*
+	* To resume several interrupts pending at the same checkpoint in one
+	* command, use {@link respondAll} — sequential single `respond()` calls
+	* would not work, since the first resume starts a run, leaving the
+	* 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.
+	*
+	* @param response - Payload sent back to the interrupted namespace.
+	* @param options - Optional target (`interruptId` / `namespace`) and
+	*   run-level `config` / `metadata` folded into the run that services
+	*   the resume (model/user config, trigger source, test flags, …).
+	*   Equivalent to the same fields on {@link StreamSubmitOptions}.
+	*
+	* @example Single pending interrupt (safe to omit a target)
+	* ```ts
+	* await controller.respond({ approved: true });
+	* ```
+	*
+	* @example Carry run config / metadata onto the resume
+	* ```ts
+	* await controller.respond(
+	*   { approved: true },
+	*   { config: { configurable: { model: "gpt-4o" } }, metadata: { source: "ui" } },
+	* );
+	* ```
 	*
-	* @param response - Payload to send back to the interrupted namespace.
-	* @param target - Optional explicit interrupt id and namespace; defaults to the latest unresolved interrupt.
+	* @example Multiple root 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`.
 	*/
-	async respond(response, target) {
+	async respond(response, options) {
 		if (this.#disposed || this.#thread == null) throw new Error("No active thread to respond to.");
-		const resolved = target != null ? {
-			interruptId: target.interruptId,
-			namespace: target.namespace ?? [...ROOT_NAMESPACE]
+		const resolved = options?.interruptId != null ? {
+			interruptId: options.interruptId,
+			namespace: options.namespace ?? [...ROOT_NAMESPACE]
 		} : this.#resolveInterruptForResume();
 		if (resolved == null) throw new Error("No pending interrupt to respond to.");
 		try {
 			await this.#thread.respondInput({
 				namespace: resolved.namespace,
 				interrupt_id: resolved.interruptId,
-				response
+				response,
+				config: options?.config,
+				metadata: options?.metadata
+			});
+			this.#markInterruptResolvedInRootStore(resolved.interruptId);
+		} catch (error) {
+			if (this.#disposed && isAbortLikeError(error)) return;
+			throw error;
+		}
+	}
+	/**
+	* Resume several pending interrupts at the same checkpoint in a single
+	* command.
+	*
+	* Required when a run pauses on multiple interrupts simultaneously
+	* (e.g. parallel tool-authorization prompts): a single
+	* `Command({ resume })` carrying every interrupt's payload resumes them
+	* together. Sequential {@link respond} calls would fail because the
+	* first resume starts a run, leaving the rest with no interrupted run to
+	* respond to.
+	*
+	* `responsesById` maps each pending `interruptId` to the payload sent
+	* back to it, so different interrupts can receive different responses
+	* (approve one, deny another). To send the *same* payload to several
+	* interrupts, build the map with that value for each id, e.g.
+	* `Object.fromEntries(ids.map((id) => [id, response]))`.
+	*
+	* The server resumes by `interruptId`, so namespaces are resolved
+	* internally from `getThread()?.interrupts` and need not be supplied.
+	*
+	* @param responsesById - Map of pending `interruptId` to its response
+	*   payload. Must contain at least one entry.
+	* @param options - Optional run-level `config` / `metadata` folded into
+	*   the single run that services the batched resume. Equivalent to the
+	*   same fields on {@link StreamSubmitOptions}.
+	*
+	* @example Distinct payloads per interrupt
+	* ```tsx
+	* await stream.respondAll({
+	*   [interruptA.id]: { approved: true },
+	*   [interruptB.id]: { approved: false },
+	* });
+	* ```
+	*
+	* @example Same payload to every pending interrupt
+	* ```tsx
+	* await stream.respondAll(
+	*   Object.fromEntries(stream.interrupts.map((i) => [i.id!, { approved: true }])),
+	* );
+	* ```
+	*/
+	async respondAll(responsesById, options) {
+		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 responses = entries.map(([interruptId, response]) => ({
+			interrupt_id: interruptId,
+			response,
+			namespace: pending.find((entry) => entry.interruptId === interruptId)?.namespace ?? [...ROOT_NAMESPACE]
+		}));
+		try {
+			await this.#thread.respondInput({
+				responses,
+				config: options?.config,
+				metadata: options?.metadata
 			});
-			this.#resolvedInterrupts.add(resolved.interruptId);
+			for (const { interrupt_id: interruptId } of responses) this.#markInterruptResolvedInRootStore(interruptId);
 		} catch (error) {
 			if (this.#disposed && isAbortLikeError(error)) return;
 			throw error;
@@ -1061,6 +1182,22 @@ var StreamController = class {
 		});
 	}
 	/**
+	* Mark an interrupt resolved for replay filtering and mirror the
+	* removal into the root snapshot the framework hooks read.
+	*/
+	#markInterruptResolvedInRootStore(interruptId) {
+		this.#resolvedInterrupts.add(interruptId);
+		this.rootStore.setState((s) => {
+			const interrupts = s.interrupts.filter((entry) => entry.id !== interruptId);
+			if (interrupts.length === s.interrupts.length && s.interrupt?.id !== interruptId) return s;
+			return {
+				...s,
+				interrupts,
+				interrupt: interrupts[0]
+			};
+		});
+	}
+	/**
 	* Resolve on the next root-namespace terminal lifecycle event
 	* (`completed` / `failed` / `interrupted`) or on abort.
 	*