@langchain/langgraph-api 1.5.2 → 1.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,7 +7,7 @@ import { serialiseAsDict } from "../../utils/serde.mjs";
7
7
  import { jsonExtra } from "../../utils/hono.mjs";
8
8
  import { RunProtocolSession } from "../../protocol/session/index.mjs";
9
9
  import { PROTOCOL_STREAM_RUN_KEY } from "../../protocol/constants.mjs";
10
- import { matchesSinkFilter, normalizeMultitaskStrategy, DEFAULT_MULTITASK_STRATEGY, } from "../../protocol/service.mjs";
10
+ import { isKeyedByInterruptId, matchesSinkFilter, normalizeMultitaskStrategy, DEFAULT_MULTITASK_STRATEGY, } from "../../protocol/service.mjs";
11
11
  import { ProtocolCommandSchema, ThreadIdSchema, isRecord, createStubRun, } from "./utils.mjs";
12
12
  import { DEFAULT_PROTOCOL_STREAM_MODES } from "./constants.mjs";
13
13
  const EventsFilterSchema = z
@@ -112,17 +112,17 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
112
112
  thread.currentRun = run;
113
113
  return protocolSession;
114
114
  }
115
- async function hasPendingInterruptsForThread(thread) {
115
+ async function pendingInterruptCount(thread) {
116
116
  const assistantId = thread.assistantId;
117
117
  if (assistantId == null)
118
- return false;
118
+ return 0;
119
119
  try {
120
120
  const graph = await context.getGraph(assistantId);
121
121
  const snapshot = await graph.getState({ configurable: { thread_id: thread.threadId } }, { subgraphs: true });
122
- return (snapshot.tasks ?? []).some((task) => Array.isArray(task.interrupts) && task.interrupts.length > 0);
122
+ return (snapshot.tasks ?? []).reduce((count, task) => count + (Array.isArray(task.interrupts) ? task.interrupts.length : 0), 0);
123
123
  }
124
124
  catch {
125
- return false;
125
+ return 0;
126
126
  }
127
127
  }
128
128
  async function handleRunStart(thread, command) {
@@ -146,6 +146,23 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
146
146
  message: `Thread ${thread.threadId} is bound to assistant ${thread.assistantId}; cannot run ${assistantId}.`,
147
147
  });
148
148
  }
149
+ const pendingInterrupts = params.input != null ? await pendingInterruptCount(thread) : 0;
150
+ // One answer can't say which of several pending interrupts it is for:
151
+ // LangGraph fails the run, or picks one when they share a subgraph task.
152
+ // While a run is in flight the count can still change, so it keeps
153
+ // resuming as before.
154
+ const runInFlight = thread.currentRun?.status === "pending" ||
155
+ thread.currentRun?.status === "running";
156
+ if (pendingInterrupts > 1 &&
157
+ !isKeyedByInterruptId(params.input) &&
158
+ !runInFlight) {
159
+ return jsonResponse({
160
+ type: "error",
161
+ id: command.id,
162
+ error: "invalid_argument",
163
+ message: `run.start input can't say which of the ${pendingInterrupts} pending interrupts it answers; answer them with input.respond.`,
164
+ });
165
+ }
149
166
  thread.assistantId = assistantId;
150
167
  const runMetadata = isRecord(params.metadata)
151
168
  ? params.metadata
@@ -193,16 +210,13 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
193
210
  ? checkpointId
194
211
  : undefined;
195
212
  })();
196
- const hasPendingInterrupts = params.input != null
197
- ? await hasPendingInterruptsForThread(thread)
198
- : false;
199
213
  // Resume only when the thread actually has a pending `interrupt()`.
200
214
  // A cancelled run also ends with status "interrupted" but has no
201
215
  // pending interrupt to consume the resume value, so folding the
202
216
  // input into `Command(resume)` there would silently drop the user's
203
217
  // message; a cancelled thread must get plain input (a fresh run from
204
218
  // the checkpoint that applies the input to state).
205
- const isResume = params.input != null && hasPendingInterrupts;
219
+ const isResume = pendingInterrupts > 0;
206
220
  if (isResume) {
207
221
  // Drop stale lifecycle events from the paused run so late-attaching
208
222
  // sinks do not replay `lifecycle.interrupted` after resume.
@@ -9,6 +9,10 @@ type ServiceBindings = {
9
9
  * concrete delivery mechanism such as WebSocket or SSE.
10
10
  */
11
11
  type EventSink = (message: ProtocolEvent) => Promise<void> | void;
12
+ /**
13
+ * Whether LangGraph resumes `value` per interrupt rather than as one answer.
14
+ */
15
+ export declare const isKeyedByInterruptId: (value: unknown) => boolean;
12
16
  export declare const DEFAULT_MULTITASK_STRATEGY: MultitaskStrategy;
13
17
  /**
14
18
  * Resolve the per-run `multitaskStrategy`. Honor it when it is one of the
@@ -78,8 +82,8 @@ export declare class ProtocolService {
78
82
  private handleRunStart;
79
83
  private handleInputRespond;
80
84
  private createOrResumeRun;
81
- private hasPendingInterrupts;
82
- private hasPendingInterruptsForThread;
85
+ private hasRunInFlight;
86
+ private pendingInterruptCount;
83
87
  private handleStateGet;
84
88
  private forwardToRunSession;
85
89
  /**
@@ -13,6 +13,15 @@ const DEFAULT_RUN_STREAM_MODES = [
13
13
  "tasks",
14
14
  ];
15
15
  const isRecord = (value) => typeof value === "object" && value !== null;
16
+ // LangGraph resumes interrupts by id only when every key of the resume map
17
+ // has this shape; any other key makes the whole map one answer.
18
+ const INTERRUPT_ID_RE = /^[0-9a-f]{32}$/;
19
+ /**
20
+ * Whether LangGraph resumes `value` per interrupt rather than as one answer.
21
+ */
22
+ export const isKeyedByInterruptId = (value) => isRecord(value) &&
23
+ Object.keys(value).length > 0 &&
24
+ Object.keys(value).every((key) => INTERRUPT_ID_RE.test(key));
16
25
  // Concurrency strategies accepted on `run.start`, matching the four values
17
26
  // the SDK's `multitaskStrategy` option can take.
18
27
  const VALID_MULTITASK_STRATEGIES = [
@@ -208,8 +217,24 @@ export class ProtocolService {
208
217
  record.assistantId !== params.assistant_id) {
209
218
  return this.error(command.id, "invalid_argument", `Thread ${record.threadId} is bound to assistant ${record.assistantId}; cannot run ${params.assistant_id}.`);
210
219
  }
220
+ const pendingInterrupts = params.input != null ? await this.pendingInterruptCount(record) : 0;
221
+ // One answer can't say which of several pending interrupts it is for:
222
+ // LangGraph fails the run, or picks one when they share a subgraph task.
223
+ // While a run is in flight the count can still change, so it keeps
224
+ // resuming as before.
225
+ if (pendingInterrupts > 1 &&
226
+ !isKeyedByInterruptId(params.input) &&
227
+ !(await this.hasRunInFlight(record))) {
228
+ return this.error(command.id, "invalid_argument", `run.start input can't say which of the ${pendingInterrupts} pending interrupts it answers; answer them with input.respond.`);
229
+ }
211
230
  record.assistantId = params.assistant_id;
212
- const run = await this.createOrResumeRun(record, params);
231
+ // Resume only when the thread actually has a pending `interrupt()`.
232
+ // A cancelled run also ends with status "interrupted" but has no
233
+ // pending interrupt to consume the resume value, so folding the
234
+ // input into `Command(resume)` there would silently drop the user's
235
+ // message; a cancelled thread must get plain input (a fresh run from
236
+ // the checkpoint that applies the input to state).
237
+ const run = await this.createOrResumeRun(record, params, pendingInterrupts > 0);
213
238
  return {
214
239
  type: "success",
215
240
  id: command.id,
@@ -254,7 +279,7 @@ export class ProtocolService {
254
279
  const currentRun = record.currentRunId != null
255
280
  ? await this.bindings.runs.get(record.currentRunId, record.threadId, record.auth)
256
281
  : null;
257
- const hasPendingInterrupts = await this.hasPendingInterrupts(record);
282
+ const hasPendingInterrupts = (await this.pendingInterruptCount(record)) > 0;
258
283
  if (currentRun == null && !hasPendingInterrupts) {
259
284
  return this.error(command.id, "no_such_run", "No interrupted run is bound to this thread.");
260
285
  }
@@ -290,7 +315,7 @@ export class ProtocolService {
290
315
  goto,
291
316
  config: isRecord(rawParams.config) ? rawParams.config : undefined,
292
317
  metadata: isRecord(rawParams.metadata) ? rawParams.metadata : undefined,
293
- });
318
+ }, true);
294
319
  return {
295
320
  type: "success",
296
321
  id: command.id,
@@ -301,18 +326,8 @@ export class ProtocolService {
301
326
  },
302
327
  };
303
328
  }
304
- async createOrResumeRun(record, params) {
329
+ async createOrResumeRun(record, params, isResume) {
305
330
  const assistantId = getAssistantId(params.assistant_id);
306
- const hasPendingInterrupts = params.input != null
307
- ? await this.hasPendingInterruptsForThread(record.threadId, record.auth)
308
- : false;
309
- // Resume only when the thread actually has a pending `interrupt()`.
310
- // A cancelled run also ends with status "interrupted" but has no
311
- // pending interrupt to consume the resume value, so folding the
312
- // input into `Command(resume)` there would silently drop the user's
313
- // message; a cancelled thread must get plain input (a fresh run from
314
- // the checkpoint that applies the input to state).
315
- const isResume = params.input != null && hasPendingInterrupts;
316
331
  /**
317
332
  * Fork/time-travel replays from `config.configurable.checkpoint_id`
318
333
  * when the caller supplies it (the SDK folds its `forkFrom`
@@ -407,16 +422,23 @@ export class ProtocolService {
407
422
  await record.session?.start();
408
423
  return run;
409
424
  }
410
- async hasPendingInterrupts(record) {
411
- return this.hasPendingInterruptsForThread(record.threadId, record.auth);
425
+ async hasRunInFlight(record) {
426
+ try {
427
+ const thread = await this.bindings.threads.get(record.threadId, record.auth);
428
+ return thread.status === "busy";
429
+ }
430
+ catch {
431
+ // Unknown, so don't refuse on a guess.
432
+ return true;
433
+ }
412
434
  }
413
- async hasPendingInterruptsForThread(threadId, auth) {
435
+ async pendingInterruptCount(record) {
414
436
  try {
415
- const state = await this.bindings.threads.state.get({ configurable: { thread_id: threadId } }, { subgraphs: true }, auth);
416
- return (state.tasks ?? []).some((task) => Array.isArray(task.interrupts) && task.interrupts.length > 0);
437
+ const state = await this.bindings.threads.state.get({ configurable: { thread_id: record.threadId } }, { subgraphs: true }, record.auth);
438
+ return (state.tasks ?? []).reduce((count, task) => count + (Array.isArray(task.interrupts) ? task.interrupts.length : 0), 0);
417
439
  }
418
440
  catch {
419
- return false;
441
+ return 0;
420
442
  }
421
443
  }
422
444
  async handleStateGet(record, command) {
@@ -1,7 +1,7 @@
1
1
  import type { RunnableConfig } from "@langchain/core/runnables";
2
2
  import { type Checkpoint, type CheckpointMetadata, MemorySaver } from "@langchain/langgraph";
3
3
  import { FileSystemPersistence } from "./persist.mjs";
4
- declare class InMemorySaver extends MemorySaver {
4
+ export declare class InMemorySaver extends MemorySaver {
5
5
  initialize(cwd: string): Promise<FileSystemPersistence<{
6
6
  storage: typeof MemorySaver.prototype.storage;
7
7
  writes: typeof MemorySaver.prototype.writes;
@@ -16,4 +16,3 @@ declare class InMemorySaver extends MemorySaver {
16
16
  toJSON(): string;
17
17
  }
18
18
  export declare const checkpointer: InMemorySaver;
19
- export {};
@@ -16,7 +16,7 @@ const conn = new FileSystemPersistence(".langgraphjs_api.checkpointer.json", ()
16
16
  storage: {},
17
17
  writes: {},
18
18
  }));
19
- class InMemorySaver extends MemorySaver {
19
+ export class InMemorySaver extends MemorySaver {
20
20
  async initialize(cwd) {
21
21
  await conn.initialize(cwd);
22
22
  await conn.with(({ storage, writes }) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@langchain/langgraph-api",
3
- "version": "1.5.2",
3
+ "version": "1.5.4",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": "^18.19.0 || >=20.16.0"
@@ -71,12 +71,12 @@
71
71
  "winston": "^3.17.0",
72
72
  "winston-console-format": "^1.0.8",
73
73
  "zod": "^3.25.76 || ^4",
74
- "@langchain/langgraph-ui": "1.5.2"
74
+ "@langchain/langgraph-ui": "1.5.4"
75
75
  },
76
76
  "peerDependencies": {
77
77
  "@langchain/core": "^1.1.48",
78
78
  "@langchain/langgraph": "^1.4.18-rc.0",
79
- "@langchain/langgraph-checkpoint": "^1.1.4",
79
+ "@langchain/langgraph-checkpoint": "^1.2.0",
80
80
  "@langchain/langgraph-sdk": "^1.12.0-rc.0",
81
81
  "ts-node": "^10.9.2",
82
82
  "typescript": "^5.5.4"
@@ -104,9 +104,9 @@
104
104
  "typescript": "^4.9.5 || ^5.4.5",
105
105
  "vitest": "^4.1.11",
106
106
  "wait-port": "^1.1.0",
107
- "@langchain/langgraph-checkpoint": "1.1.5",
108
- "@langchain/langgraph-sdk": "1.12.1",
109
- "@langchain/langgraph": "1.4.19"
107
+ "@langchain/langgraph": "1.5.1",
108
+ "@langchain/langgraph-checkpoint": "1.2.0",
109
+ "@langchain/langgraph-sdk": "1.12.5"
110
110
  },
111
111
  "scripts": {
112
112
  "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",