@langchain/langgraph-api 1.2.2-rc.0 → 1.2.3

package/dist/experimental/embed/protocol.mjs

@@ -7,7 +7,7 @@ import { serialiseAsDict } from "../../utils/serde.mjs";
 import { jsonExtra } from "../../utils/hono.mjs";
 import { RunProtocolSession } from "../../protocol/session/index.mjs";
 import { PROTOCOL_STREAM_RUN_KEY } from "../../protocol/constants.mjs";
-import { matchesSinkFilter } from "../../protocol/service.mjs";
+import { matchesSinkFilter, normalizeMultitaskStrategy, DEFAULT_MULTITASK_STRATEGY, } from "../../protocol/service.mjs";
 import { ProtocolCommandSchema, ThreadIdSchema, isRecord, createStubRun, } from "./utils.mjs";
 import { DEFAULT_PROTOCOL_STREAM_MODES } from "./constants.mjs";
 const EventsFilterSchema = z
@@ -112,6 +112,19 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
         thread.currentRun = run;
         return protocolSession;
     }
+    async function hasPendingInterruptsForThread(thread) {
+        const assistantId = thread.assistantId;
+        if (assistantId == null)
+            return false;
+        try {
+            const graph = await context.getGraph(assistantId);
+            const snapshot = await graph.getState({ configurable: { thread_id: thread.threadId } }, { subgraphs: true });
+            return (snapshot.tasks ?? []).some((task) => Array.isArray(task.interrupts) && task.interrupts.length > 0);
+        }
+        catch {
+            return false;
+        }
+    }
     async function handleRunStart(thread, command) {
         const params = isRecord(command.params)
             ? command.params
@@ -165,21 +178,39 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
                 },
             });
         }
-        // Promote SDK-side `forkFrom: { checkpointId }` into
-        // `configurable.checkpoint_id` so the engine replays from the
-        // requested fork target. This mirrors the promotion performed by
-        // `ProtocolService.createOrResumeRun` in the non-embed path and
-        // closes the "client sends forkFrom, server drops it" gap.
+        // Fork/time-travel replays from `config.configurable.checkpoint_id`
+        // — the single legacy-compliant fork field. The SDK folds its
+        // `forkFrom` convenience option into this field client-side, so the
+        // server reads it from there rather than a top-level `forkFrom`.
+        // `createStubRun` only reliably forwards a fork target via the
+        // top-level `checkpoint_id`, so lift it out of `configurable` below.
         const forkCheckpointId = (() => {
-            if (!isRecord(params.forkFrom))
-                return undefined;
-            const id = params.forkFrom.checkpointId;
-            return typeof id === "string" && id.length > 0 ? id : undefined;
+            const configurable = isRecord(params.config) && isRecord(params.config.configurable)
+                ? params.config.configurable
+                : undefined;
+            const checkpointId = configurable?.checkpoint_id;
+            return typeof checkpointId === "string" && checkpointId.length > 0
+                ? checkpointId
+                : undefined;
         })();
+        const currentRun = thread.currentRun;
+        const currentStatus = currentRun?.status;
+        const hasPendingInterrupts = params.input != null
+            ? await hasPendingInterruptsForThread(thread)
+            : false;
+        const isResume = params.input != null &&
+            ((currentRun != null && currentStatus === "interrupted") ||
+                hasPendingInterrupts);
+        if (isResume) {
+            // Drop stale lifecycle events from the paused run so late-attaching
+            // sinks do not replay `lifecycle.interrupted` after resume.
+            thread.queuedEvents.length = 0;
+        }
         const run = createStubRun(thread.threadId, {
             assistant_id: assistantId,
             on_disconnect: "cancel",
-            input: params.input ?? null,
+            input: isResume ? null : (params.input ?? null),
+            command: isResume ? { resume: params.input } : undefined,
             config: {
                 configurable: {
                     ...(isRecord(params.config) && isRecord(params.config.configurable)
@@ -192,7 +223,13 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
             // fact, *replaces* any inline configurable the caller passed),
             // so this is the only reliable way to reach the engine with a
             // fork target.
-            ...(forkCheckpointId != null ? { checkpoint_id: forkCheckpointId } : {}),
+            ...(forkCheckpointId != null && !isResume
+                ? { checkpoint_id: forkCheckpointId }
+                : {}),
+            // Honor the caller's `multitaskStrategy`, falling back to `enqueue`
+            // to match the non-embed protocol-v2 server and the Python default.
+            multitask_strategy: normalizeMultitaskStrategy(params.multitaskStrategy) ??
+                DEFAULT_MULTITASK_STRATEGY,
             metadata: Object.keys(runMetadata).length > 0 ? runMetadata : undefined,
             stream_mode: DEFAULT_PROTOCOL_STREAM_MODES,
             stream_subgraphs: true,
@@ -214,8 +251,37 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
         const params = isRecord(command.params)
             ? command.params
             : {};
-        const interruptId = params.interrupt_id;
-        if (typeof interruptId !== "string") {
+        // Build the resume input map. The SDK sends either a single
+        // `interrupt_id` / `response` or a `responses` batch (several
+        // interrupts at the same checkpoint, resumed in one command) — the
+        // protocol's `InputRespondOne` / `InputRespondMany` variants. Read
+        // leniently to tolerate clients pinned to older bindings.
+        const resumeInput = {};
+        if (Array.isArray(params.responses)) {
+            for (const entry of params.responses) {
+                if (!isRecord(entry) || typeof entry.interrupt_id !== "string") {
+                    return jsonResponse({
+                        type: "error",
+                        id: command.id,
+                        error: "invalid_argument",
+                        message: "input.respond responses entries require an interrupt_id.",
+                    });
+                }
+                resumeInput[entry.interrupt_id] = entry.response;
+            }
+            if (Object.keys(resumeInput).length === 0) {
+                return jsonResponse({
+                    type: "error",
+                    id: command.id,
+                    error: "invalid_argument",
+                    message: "input.respond requires at least one response.",
+                });
+            }
+        }
+        else if (typeof params.interrupt_id === "string") {
+            resumeInput[params.interrupt_id] = params.response;
+        }
+        else {
             return jsonResponse({
                 type: "error",
                 id: command.id,
@@ -236,7 +302,12 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
             assistant_id: assistantId,
             on_disconnect: "cancel",
             input: null,
-            command: { resume: { [interruptId]: params.response } },
+            command: { resume: resumeInput },
+            // Carry the SDK's `respond({ config, metadata })` onto the resumed
+            // run so it applies the same run config / metadata a fresh
+            // `run.start` would (both are part of the `input.respond` params).
+            config: isRecord(params.config) ? params.config : undefined,
+            metadata: isRecord(params.metadata) ? params.metadata : undefined,
             stream_mode: DEFAULT_PROTOCOL_STREAM_MODES,
             stream_subgraphs: true,
         });

package/dist/protocol/service.d.mts

@@ -1,4 +1,4 @@
-import type { RunsRepo, ThreadsRepo } from "../storage/types.mjs";
+import type { RunsRepo, ThreadsRepo, MultitaskStrategy } from "../storage/types.mjs";
 import type { EventSinkEntry, EventSinkFilter, ProtocolCommand, ProtocolError, ProtocolEvent, ProtocolSuccess, ThreadRecord, ProtocolTransportName } from "./types.mjs";
 type ServiceBindings = {
     runs: RunsRepo;
@@ -9,6 +9,14 @@ type ServiceBindings = {
  * concrete delivery mechanism such as WebSocket or SSE.
  */
 type EventSink = (message: ProtocolEvent) => Promise<void> | void;
+export declare const DEFAULT_MULTITASK_STRATEGY: MultitaskStrategy;
+/**
+ * Resolve the per-run `multitaskStrategy`. Honor it when it is one of the
+ * recognized strategies, otherwise return `undefined` so the caller falls
+ * back to {@link DEFAULT_MULTITASK_STRATEGY}. Lenient by design (matches
+ * the rest of `normalizeRunStart` and the Python reference server).
+ */
+export declare const normalizeMultitaskStrategy: (value: unknown) => MultitaskStrategy | undefined;
 /**
  * Thread-scoped connection registry and command dispatcher.
  *

package/dist/protocol/service.mjs

@@ -12,14 +12,28 @@ const DEFAULT_RUN_STREAM_MODES = [
     "tasks",
 ];
 const isRecord = (value) => typeof value === "object" && value !== null;
-const normalizeForkFrom = (value) => {
-    if (!isRecord(value))
-        return undefined;
-    const checkpointId = value.checkpointId;
-    if (typeof checkpointId !== "string" || checkpointId.length === 0) {
-        return undefined;
-    }
-    return { checkpointId };
+// Concurrency strategies accepted on `run.start`, matching the four values
+// the SDK's `multitaskStrategy` option can take.
+const VALID_MULTITASK_STRATEGIES = [
+    "reject",
+    "rollback",
+    "interrupt",
+    "enqueue",
+];
+// Legacy stream-endpoint default: queue new runs behind active ones instead
+// of interrupting. Used when the caller omits `multitaskStrategy`.
+export const DEFAULT_MULTITASK_STRATEGY = "enqueue";
+/**
+ * Resolve the per-run `multitaskStrategy`. Honor it when it is one of the
+ * recognized strategies, otherwise return `undefined` so the caller falls
+ * back to {@link DEFAULT_MULTITASK_STRATEGY}. Lenient by design (matches
+ * the rest of `normalizeRunStart` and the Python reference server).
+ */
+export const normalizeMultitaskStrategy = (value) => {
+    return typeof value === "string" &&
+        VALID_MULTITASK_STRATEGIES.includes(value)
+        ? value
+        : undefined;
 };
 const normalizeRunStart = (value) => {
     if (isRecord(value)) {
@@ -28,7 +42,7 @@ const normalizeRunStart = (value) => {
             input: value.input,
             config: isRecord(value.config) ? value.config : undefined,
             metadata: isRecord(value.metadata) ? value.metadata : undefined,
-            forkFrom: normalizeForkFrom(value.forkFrom),
+            multitaskStrategy: normalizeMultitaskStrategy(value.multitaskStrategy),
         };
     }
     return {
@@ -206,10 +220,31 @@ export class ProtocolService {
         };
     }
     async handleInputRespond(record, command) {
-        const params = isRecord(command.params)
+        // Build the resume input map (`{ [interrupt_id]: response }`). The
+        // SDK sends either a single `interrupt_id` / `response` or a
+        // `responses` batch (several interrupts at the same checkpoint, which
+        // must be resumed in one command) — the `InputRespondOne` /
+        // `InputRespondMany` variants of `InputRespondParams`. Read leniently
+        // to tolerate clients pinned to older bindings.
+        const rawParams = isRecord(command.params)
             ? command.params
             : {};
-        if (typeof params.interrupt_id !== "string") {
+        const resumeInput = {};
+        if (Array.isArray(rawParams.responses)) {
+            for (const entry of rawParams.responses) {
+                if (!isRecord(entry) || typeof entry.interrupt_id !== "string") {
+                    return this.error(command.id, "invalid_argument", "input.respond responses entries require an interrupt_id.");
+                }
+                resumeInput[entry.interrupt_id] = entry.response;
+            }
+            if (Object.keys(resumeInput).length === 0) {
+                return this.error(command.id, "invalid_argument", "input.respond requires at least one response.");
+            }
+        }
+        else if (typeof rawParams.interrupt_id === "string") {
+            resumeInput[rawParams.interrupt_id] = rawParams.response;
+        }
+        else {
             return this.error(command.id, "invalid_argument", "input.respond requires an interrupt_id.");
         }
         if (record.assistantId == null) {
@@ -225,11 +260,18 @@ export class ProtocolService {
         if (!hasPendingInterrupts) {
             return this.error(command.id, "invalid_argument", "input.respond can only be used while the run is interrupted.");
         }
+        // `config` / `metadata` are part of `InputRespondParams` (both the
+        // `InputRespondOne` and `InputRespondMany` variants). The SDK's
+        // `respond({ config, metadata })` forwards them on the `input.respond`
+        // command so a resumed run can carry the same run config (model, user
+        // context, …) and metadata (trigger source, test flags, …) a fresh
+        // `run.start` would. Read them leniently — same posture as
+        // `normalizeRunStart`.
         await this.createOrResumeRun(record, {
             assistant_id: record.assistantId,
-            input: { [params.interrupt_id]: params.response },
-            config: undefined,
-            metadata: undefined,
+            input: resumeInput,
+            config: isRecord(rawParams.config) ? rawParams.config : undefined,
+            metadata: isRecord(rawParams.metadata) ? rawParams.metadata : undefined,
         });
         return {
             type: "success",
@@ -254,22 +296,17 @@ export class ProtocolService {
             ((currentRun != null && currentStatus === "interrupted") ||
                 hasPendingInterrupts);
         /**
-         * When `forkFrom: { checkpointId }` is present, promote it to
-         * `configurable.checkpoint_id` so the engine replays from the
-         * requested fork target. `forkFrom` is merged last so it wins over
-         * any `checkpoint_id` the caller may have pre-baked into
-         * `config.configurable`; in resume flows we intentionally skip the
-         * promotion because a resume must follow the thread's active
-         * checkpoint, not a historical fork.
+         * Fork/time-travel replays from `config.configurable.checkpoint_id`
+         * when the caller supplies it (the SDK folds its `forkFrom`
+         * convenience option into this field client-side). Forwarded as-is so
+         * the engine starts from the requested checkpoint instead of the
+         * thread's latest state.
          */
         const runConfig = {
             ...params.config,
             configurable: {
                 ...params.config?.configurable,
                 thread_id: record.threadId,
-                ...(!isResume && params.forkFrom?.checkpointId != null
-                    ? { checkpoint_id: params.forkFrom.checkpointId }
-                    : {}),
             },
         };
         const runPayload = {
@@ -284,7 +321,10 @@ export class ProtocolService {
             stream_subgraphs: true,
             stream_resumable: true,
             if_not_exists: "create",
-            multitask_strategy: "interrupt",
+            // Honor the caller's `multitaskStrategy` (the SDK sends it on every
+            // run.start), falling back to `enqueue` — the legacy stream-endpoint
+            // default — when omitted. Matches the Python protocol-v2 server.
+            multitask_strategy: params.multitaskStrategy ?? DEFAULT_MULTITASK_STRATEGY,
         };
         const [run] = await this.bindings.runs.put(uuid7(), assistantId, {
             input: runPayload.input,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "1.2.2-rc.0",
+  "version": "1.2.3",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -55,7 +55,7 @@
     "@hono/node-server": "^1.19.13",
     "@hono/node-ws": "^1.3.0",
     "@hono/zod-validator": "^0.7.6",
-    "@langchain/protocol": "^0.0.15",
+    "@langchain/protocol": "^0.0.16",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
@@ -72,7 +72,7 @@
     "winston": "^3.17.0",
     "winston-console-format": "^1.0.8",
     "zod": "^3.25.76 || ^4",
-    "@langchain/langgraph-ui": "1.2.2-rc.0"
+    "@langchain/langgraph-ui": "1.2.3"
   },
   "peerDependencies": {
     "@langchain/core": "^1.1.44",
@@ -101,9 +101,9 @@
     "typescript": "^4.9.5 || ^5.4.5",
     "vitest": "^3.2.4",
     "wait-port": "^1.1.0",
-    "@langchain/langgraph": "1.3.1-rc.0",
-    "@langchain/langgraph-checkpoint": "1.0.2",
-    "@langchain/langgraph-sdk": "1.9.3-rc.0"
+    "@langchain/langgraph": "1.3.2",
+    "@langchain/langgraph-checkpoint": "1.0.3",
+    "@langchain/langgraph-sdk": "1.9.10"
   },
   "scripts": {
     "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",