@langchain/langgraph-api 1.5.8 → 1.6.0

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.
@@ -50,7 +50,6 @@ export default function createProtocolApi(upgradeWebSocket, ops) {
50
50
  const record = protocolService.ensureThread({
51
51
  threadId: thread_id,
52
52
  transport: "websocket",
53
- auth: c.var.auth,
54
53
  });
55
54
  return {
56
55
  async onOpen(_event, ws) {
@@ -84,7 +83,7 @@ export default function createProtocolApi(upgradeWebSocket, ops) {
84
83
  }));
85
84
  return;
86
85
  }
87
- const response = await protocolService.handleCommand(record.threadId, payload);
86
+ const response = await protocolService.handleCommand(record.threadId, payload, c.var.auth);
88
87
  // `null` means the session already wrote the response through
89
88
  // the shared transport queue (see
90
89
  // `ProtocolSession.handleSubscribeForResponse`). Sending again
@@ -106,17 +105,15 @@ export default function createProtocolApi(upgradeWebSocket, ops) {
106
105
  protocolService.ensureThread({
107
106
  threadId: thread_id,
108
107
  transport: "sse-http",
109
- auth: c.var.auth,
110
108
  });
111
109
  const payload = c.req.valid("json");
112
- return jsonExtra(c, await protocolService.handleCommand(thread_id, payload));
110
+ return jsonExtra(c, await protocolService.handleCommand(thread_id, payload, c.var.auth));
113
111
  });
114
112
  api.post("/threads/:thread_id/stream/events", zValidator("param", ThreadIdSchema), zValidator("json", EventsFilterSchema), async (c) => {
115
113
  const { thread_id } = c.req.valid("param");
116
114
  protocolService.ensureThread({
117
115
  threadId: thread_id,
118
116
  transport: "sse-http",
119
- auth: c.var.auth,
120
117
  });
121
118
  const body = c.req.valid("json");
122
119
  const sinkId = uuid7();
package/dist/api/runs.mjs CHANGED
@@ -13,6 +13,19 @@ import { getDisconnectAbortSignal, jsonExtra, waitKeepAlive, } from "../utils/ho
13
13
  import { applyAuthToRunConfig, applyRequestHeadersToRunConfig, } from "../utils/run-auth.mjs";
14
14
  import { serialiseAsDict } from "../utils/serde.mjs";
15
15
  const api = new Hono();
16
+ // Ends a run stream with `end` and the run's final status. A stateless run's
17
+ // worker sends its own `end`, since the run is deleted with its thread.
18
+ async function* joinWithEnd(...[runId, threadId, options, auth]) {
19
+ for await (const event of runs().stream.join(runId, threadId, options, auth)) {
20
+ yield event;
21
+ if (event.event === "end")
22
+ return;
23
+ }
24
+ const run = await runs().get(runId, threadId, auth);
25
+ if (run != null && run.status !== "pending" && run.status !== "running") {
26
+ yield { event: "end", data: { run_id: run.run_id, status: run.status } };
27
+ }
28
+ }
16
29
  const createValidRun = async (threadId, payload, kwargs) => {
17
30
  const { assistant_id: assistantId, ...run } = payload;
18
31
  const { auth, headers } = kwargs ?? {};
@@ -129,10 +142,10 @@ api.post("/runs/stream", zValidator("json", schemas.RunCreate), async (c) => {
129
142
  ? getDisconnectAbortSignal(c, stream)
130
143
  : undefined;
131
144
  try {
132
- for await (const { event, data } of runs().stream.join(run.run_id, undefined, {
145
+ for await (const { event, data } of joinWithEnd(run.run_id, undefined, {
133
146
  signal: cancelOnDisconnect,
134
147
  cancelOnDisconnect: cancelOnDisconnect != null,
135
- lastEventId: run.kwargs.resumable ? "-1" : undefined,
148
+ lastEventId: "-1",
136
149
  ignore404: true,
137
150
  }, c.var.auth)) {
138
151
  await stream.writeSSE({ data: serialiseAsDict(data), event });
@@ -154,11 +167,12 @@ api.get("/runs/:run_id/stream", zValidator("param", z.object({ run_id: z.string(
154
167
  ? getDisconnectAbortSignal(c, stream)
155
168
  : undefined;
156
169
  try {
157
- for await (const { id, event, data } of runs().stream.join(run_id, undefined, {
170
+ for await (const { id, event, data } of joinWithEnd(run_id, undefined, {
158
171
  signal: cancelOnDisconnect,
159
172
  cancelOnDisconnect: cancelOnDisconnect != null,
160
173
  lastEventId,
161
174
  ignore404: true,
175
+ checkRunAccess: true,
162
176
  }, c.var.auth)) {
163
177
  if (!matchesStreamMode(event, query.stream_mode))
164
178
  continue;
@@ -239,10 +253,10 @@ api.post("/threads/:thread_id/runs/stream", zValidator("param", z.object({ threa
239
253
  ? getDisconnectAbortSignal(c, stream)
240
254
  : undefined;
241
255
  try {
242
- for await (const { id, event, data } of runs().stream.join(run.run_id, thread_id, {
256
+ for await (const { id, event, data } of joinWithEnd(run.run_id, thread_id, {
243
257
  signal: cancelOnDisconnect,
244
258
  cancelOnDisconnect: cancelOnDisconnect != null,
245
- lastEventId: run.kwargs.resumable ? "-1" : undefined,
259
+ lastEventId: "-1",
246
260
  }, c.var.auth)) {
247
261
  await stream.writeSSE({ id, data: serialiseAsDict(data), event });
248
262
  }
@@ -293,7 +307,7 @@ api.get("/threads/:thread_id/runs/:run_id/stream", zValidator("param", z.object(
293
307
  const signal = cancel_on_disconnect
294
308
  ? getDisconnectAbortSignal(c, stream)
295
309
  : undefined;
296
- for await (const { id, event, data } of runs().stream.join(run_id, thread_id, {
310
+ for await (const { id, event, data } of joinWithEnd(run_id, thread_id, {
297
311
  signal,
298
312
  cancelOnDisconnect: signal != null,
299
313
  lastEventId,
@@ -39,6 +39,36 @@ export function registerRunRoutes(api, context) {
39
39
  }
40
40
  return run;
41
41
  }
42
+ // Runs the run inside the request and writes its events, then its error if
43
+ // it fails, then `end` with how it ended. `onSettled` runs before `end`.
44
+ async function streamRun(stream, run, options) {
45
+ let status = "success";
46
+ try {
47
+ for await (const { event, data } of streamState(run, {
48
+ attempt: 1,
49
+ getGraph: context.getGraph,
50
+ signal: options.signal,
51
+ })) {
52
+ if (!matchesStreamMode(event, options.streamMode ?? []))
53
+ continue;
54
+ await stream.writeSSE({ data: serialiseAsDict(data), event });
55
+ }
56
+ }
57
+ catch (error) {
58
+ status = "error";
59
+ await stream.writeSSE({
60
+ data: serialiseAsDict(serializeError(error)),
61
+ event: "error",
62
+ });
63
+ }
64
+ finally {
65
+ options.onSettled?.();
66
+ }
67
+ await stream.writeSSE({
68
+ data: serialiseAsDict({ run_id: run.run_id, status }),
69
+ event: "end",
70
+ });
71
+ }
42
72
  api.post("/threads/:thread_id/runs", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.RunCreate), async (c) => {
43
73
  const { thread_id } = c.req.valid("param");
44
74
  const payload = c.req.valid("json");
@@ -82,28 +112,14 @@ export function registerRunRoutes(api, context) {
82
112
  state.pendingRuns.splice(idx, 1);
83
113
  state.activeRunId = run_id;
84
114
  run.status = "running";
85
- try {
86
- for await (const { event, data } of streamState(run, {
87
- attempt: 1,
88
- getGraph: context.getGraph,
89
- signal,
90
- })) {
91
- if (!matchesStreamMode(event, stream_mode))
92
- continue;
93
- await stream.writeSSE({ data: serialiseAsDict(data), event });
94
- }
95
- }
96
- catch (error) {
97
- await stream.writeSSE({
98
- data: serialiseAsDict(serializeError(error)),
99
- event: "error",
100
- });
101
- }
102
- finally {
103
- if (state.activeRunId === run_id) {
104
- state.activeRunId = null;
105
- }
106
- }
115
+ await streamRun(stream, run, {
116
+ signal,
117
+ streamMode: stream_mode,
118
+ onSettled: () => {
119
+ if (state.activeRunId === run_id)
120
+ state.activeRunId = null;
121
+ },
122
+ });
107
123
  }
108
124
  catch (err) {
109
125
  if (err instanceof DOMException && err.name === "AbortError") {
@@ -144,26 +160,13 @@ export function registerRunRoutes(api, context) {
144
160
  assistant_id: payload.assistant_id,
145
161
  },
146
162
  });
147
- try {
148
- for await (const { event, data } of streamState(run, {
149
- attempt: 1,
150
- getGraph: context.getGraph,
151
- signal,
152
- })) {
153
- await stream.writeSSE({ data: serialiseAsDict(data), event });
154
- }
155
- }
156
- catch (error) {
157
- await stream.writeSSE({
158
- data: serialiseAsDict(serializeError(error)),
159
- event: "error",
160
- });
161
- }
162
- finally {
163
- if (state.activeRunId === run.run_id) {
164
- state.activeRunId = null;
165
- }
166
- }
163
+ await streamRun(stream, run, {
164
+ signal,
165
+ onSettled: () => {
166
+ if (state.activeRunId === run.run_id)
167
+ state.activeRunId = null;
168
+ },
169
+ });
167
170
  });
168
171
  });
169
172
  api.post("/runs/stream", zValidator("json", schemas.RunCreate), async (c) => {
@@ -181,21 +184,7 @@ export function registerRunRoutes(api, context) {
181
184
  },
182
185
  });
183
186
  try {
184
- try {
185
- for await (const { event, data } of streamState(run, {
186
- attempt: 1,
187
- getGraph: context.getGraph,
188
- signal,
189
- })) {
190
- await stream.writeSSE({ data: serialiseAsDict(data), event });
191
- }
192
- }
193
- catch (error) {
194
- await stream.writeSSE({
195
- data: serialiseAsDict(serializeError(error)),
196
- event: "error",
197
- });
198
- }
187
+ await streamRun(stream, run, { signal });
199
188
  }
200
189
  finally {
201
190
  await context.threads.delete(threadId);
@@ -1,3 +1,4 @@
1
+ import type { AuthContext } from "../auth/index.mjs";
1
2
  import type { RunsRepo, ThreadsRepo, MultitaskStrategy } from "../storage/types.mjs";
2
3
  import type { EventSinkEntry, EventSinkFilter, ProtocolCommand, ProtocolError, ProtocolEvent, ProtocolSuccess, ThreadRecord, ProtocolTransportName } from "./types.mjs";
3
4
  type ServiceBindings = {
@@ -43,7 +44,6 @@ export declare class ProtocolService {
43
44
  ensureThread(options: {
44
45
  threadId: string;
45
46
  transport: ProtocolTransportName;
46
- auth?: ThreadRecord["auth"];
47
47
  sendEvent?: EventSink;
48
48
  }): ThreadRecord;
49
49
  /**
@@ -74,7 +74,7 @@ export declare class ProtocolService {
74
74
  * Callers must treat `null` as "response already sent on the wire"
75
75
  * and skip any additional send.
76
76
  */
77
- handleCommand(threadId: string, command: ProtocolCommand): Promise<ProtocolSuccess | ProtocolError | null>;
77
+ handleCommand(threadId: string, command: ProtocolCommand, auth: AuthContext | undefined): Promise<ProtocolSuccess | ProtocolError | null>;
78
78
  /**
79
79
  * Start a new run, resume an interrupted run, or continue on the
80
80
  * thread depending on its current state.
@@ -98,7 +98,6 @@ export class ProtocolService {
98
98
  record = {
99
99
  threadId: options.threadId,
100
100
  transport: options.transport,
101
- auth: options.auth,
102
101
  seq: 0,
103
102
  session: undefined,
104
103
  currentRunId: undefined,
@@ -191,15 +190,15 @@ export class ProtocolService {
191
190
  * Callers must treat `null` as "response already sent on the wire"
192
191
  * and skip any additional send.
193
192
  */
194
- async handleCommand(threadId, command) {
193
+ async handleCommand(threadId, command, auth) {
195
194
  const record = this.requireThread(threadId);
196
195
  switch (command.method) {
197
196
  case "run.start":
198
- return await this.handleRunStart(record, command);
197
+ return await this.handleRunStart(record, command, auth);
199
198
  case "input.respond":
200
- return await this.handleInputRespond(record, command);
199
+ return await this.handleInputRespond(record, command, auth);
201
200
  case "state.get":
202
- return await this.handleStateGet(record, command);
201
+ return await this.handleStateGet(record, command, auth);
203
202
  default:
204
203
  return await this.forwardToRunSession(record, command);
205
204
  }
@@ -208,7 +207,7 @@ export class ProtocolService {
208
207
  * Start a new run, resume an interrupted run, or continue on the
209
208
  * thread depending on its current state.
210
209
  */
211
- async handleRunStart(record, command) {
210
+ async handleRunStart(record, command, auth) {
212
211
  const params = normalizeRunStart(command.params);
213
212
  if (!params.assistant_id) {
214
213
  return this.error(command.id, "invalid_argument", "run.start requires an assistant_id.");
@@ -217,14 +216,14 @@ export class ProtocolService {
217
216
  record.assistantId !== params.assistant_id) {
218
217
  return this.error(command.id, "invalid_argument", `Thread ${record.threadId} is bound to assistant ${record.assistantId}; cannot run ${params.assistant_id}.`);
219
218
  }
220
- const pendingInterrupts = params.input != null ? await this.pendingInterruptCount(record) : 0;
219
+ const pendingInterrupts = params.input != null ? await this.pendingInterruptCount(record, auth) : 0;
221
220
  // One answer can't say which of several pending interrupts it is for:
222
221
  // LangGraph fails the run, or picks one when they share a subgraph task.
223
222
  // While a run is in flight the count can still change, so it keeps
224
223
  // resuming as before.
225
224
  if (pendingInterrupts > 1 &&
226
225
  !isKeyedByInterruptId(params.input) &&
227
- !(await this.hasRunInFlight(record))) {
226
+ !(await this.hasRunInFlight(record, auth))) {
228
227
  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
228
  }
230
229
  record.assistantId = params.assistant_id;
@@ -234,7 +233,7 @@ export class ProtocolService {
234
233
  // input into `Command(resume)` there would silently drop the user's
235
234
  // message; a cancelled thread must get plain input (a fresh run from
236
235
  // the checkpoint that applies the input to state).
237
- const run = await this.createOrResumeRun(record, params, pendingInterrupts > 0);
236
+ const run = await this.createOrResumeRun(record, params, pendingInterrupts > 0, auth);
238
237
  return {
239
238
  type: "success",
240
239
  id: command.id,
@@ -245,7 +244,7 @@ export class ProtocolService {
245
244
  },
246
245
  };
247
246
  }
248
- async handleInputRespond(record, command) {
247
+ async handleInputRespond(record, command, auth) {
249
248
  // Build the resume input map (`{ [interrupt_id]: response }`). The
250
249
  // SDK sends either a single `interrupt_id` / `response` or a
251
250
  // `responses` batch (several interrupts at the same checkpoint, which
@@ -277,9 +276,9 @@ export class ProtocolService {
277
276
  return this.error(command.id, "no_such_run", "Thread has no active assistant; call run.start first.");
278
277
  }
279
278
  const currentRun = record.currentRunId != null
280
- ? await this.bindings.runs.get(record.currentRunId, record.threadId, record.auth)
279
+ ? await this.bindings.runs.get(record.currentRunId, record.threadId, auth)
281
280
  : null;
282
- const hasPendingInterrupts = (await this.pendingInterruptCount(record)) > 0;
281
+ const hasPendingInterrupts = (await this.pendingInterruptCount(record, auth)) > 0;
283
282
  if (currentRun == null && !hasPendingInterrupts) {
284
283
  return this.error(command.id, "no_such_run", "No interrupted run is bound to this thread.");
285
284
  }
@@ -315,7 +314,7 @@ export class ProtocolService {
315
314
  goto,
316
315
  config: isRecord(rawParams.config) ? rawParams.config : undefined,
317
316
  metadata: isRecord(rawParams.metadata) ? rawParams.metadata : undefined,
318
- }, true);
317
+ }, true, auth);
319
318
  return {
320
319
  type: "success",
321
320
  id: command.id,
@@ -326,7 +325,7 @@ export class ProtocolService {
326
325
  },
327
326
  };
328
327
  }
329
- async createOrResumeRun(record, params, isResume) {
328
+ async createOrResumeRun(record, params, isResume, auth) {
330
329
  const assistantId = getAssistantId(params.assistant_id);
331
330
  /**
332
331
  * Fork/time-travel replays from `config.configurable.checkpoint_id`
@@ -342,7 +341,7 @@ export class ProtocolService {
342
341
  thread_id: record.threadId,
343
342
  },
344
343
  };
345
- const userId = applyAuthToRunConfig(runConfig, record.auth);
344
+ const userId = applyAuthToRunConfig(runConfig, auth);
346
345
  const runPayload = {
347
346
  assistant_id: assistantId,
348
347
  input: isResume ? null : params.input,
@@ -389,8 +388,8 @@ export class ProtocolService {
389
388
  multitaskStrategy: runPayload.multitask_strategy,
390
389
  preventInsertInInflight: false,
391
390
  ifNotExists: runPayload.if_not_exists,
392
- }, record.auth);
393
- await this.ensureRunSession(record, run);
391
+ }, auth);
392
+ await this.ensureRunSession(record, run, auth);
394
393
  record.currentRunId = run.run_id;
395
394
  // For WebSocket transports, register subscriptions on the session
396
395
  // BEFORE starting it so the success responses for parked and sticky
@@ -422,9 +421,9 @@ export class ProtocolService {
422
421
  await record.session?.start();
423
422
  return run;
424
423
  }
425
- async hasRunInFlight(record) {
424
+ async hasRunInFlight(record, auth) {
426
425
  try {
427
- const thread = await this.bindings.threads.get(record.threadId, record.auth);
426
+ const thread = await this.bindings.threads.get(record.threadId, auth);
428
427
  return thread.status === "busy";
429
428
  }
430
429
  catch {
@@ -432,20 +431,20 @@ export class ProtocolService {
432
431
  return true;
433
432
  }
434
433
  }
435
- async pendingInterruptCount(record) {
434
+ async pendingInterruptCount(record, auth) {
436
435
  try {
437
- const state = await this.bindings.threads.state.get({ configurable: { thread_id: record.threadId } }, { subgraphs: true }, record.auth);
436
+ const state = await this.bindings.threads.state.get({ configurable: { thread_id: record.threadId } }, { subgraphs: true }, auth);
438
437
  return (state.tasks ?? []).reduce((count, task) => count + (Array.isArray(task.interrupts) ? task.interrupts.length : 0), 0);
439
438
  }
440
439
  catch {
441
440
  return 0;
442
441
  }
443
442
  }
444
- async handleStateGet(record, command) {
443
+ async handleStateGet(record, command, auth) {
445
444
  const params = isRecord(command.params)
446
445
  ? command.params
447
446
  : {};
448
- const values = await this.bindings.threads.state.get({ configurable: { thread_id: record.threadId } }, { subgraphs: true }, record.auth);
447
+ const values = await this.bindings.threads.state.get({ configurable: { thread_id: record.threadId } }, { subgraphs: true }, auth);
449
448
  const checkpointConfig = isRecord(values.config?.configurable)
450
449
  ? values.config.configurable
451
450
  : undefined;
@@ -544,7 +543,7 @@ export class ProtocolService {
544
543
  * Bind the thread record to a concrete LangGraph run and forward
545
544
  * normalized protocol events to attached sinks.
546
545
  */
547
- async ensureRunSession(record, run) {
546
+ async ensureRunSession(record, run, auth) {
548
547
  if (record.session != null && record.currentRunId === run.run_id)
549
548
  return;
550
549
  await record.session?.close();
@@ -552,15 +551,14 @@ export class ProtocolService {
552
551
  signal: undefined,
553
552
  cancelOnDisconnect: false,
554
553
  lastEventId: run.kwargs.resumable ? "-1" : undefined,
555
- }, record.auth);
554
+ }, auth);
556
555
  const isSSE = record.transport === "sse-http";
557
556
  const session = new RunProtocolSession({
558
557
  runId: run.run_id,
559
558
  threadId: run.thread_id,
560
- auth: record.auth,
561
559
  initialRun: run,
562
- getRun: () => this.bindings.runs.get(run.run_id, run.thread_id, record.auth),
563
- getThreadState: async () => await this.bindings.threads.state.get({ configurable: { thread_id: run.thread_id } }, { subgraphs: true }, record.auth),
560
+ getRun: () => this.bindings.runs.get(run.run_id, run.thread_id, auth),
561
+ getThreadState: async () => await this.bindings.threads.state.get({ configurable: { thread_id: run.thread_id } }, { subgraphs: true }, auth),
564
562
  source,
565
563
  startSeq: record.seq,
566
564
  passthrough: isSSE,
@@ -1,4 +1,3 @@
1
- import type { AuthContext } from "../../auth/index.mjs";
2
1
  import type { Run } from "../../storage/types.mjs";
3
2
  import type { ProtocolCommand, ProtocolError, ProtocolResponseMeta, ProtocolSuccess, SourceStreamEvent } from "../types.mjs";
4
3
  /**
@@ -40,7 +39,6 @@ export declare class RunProtocolSession {
40
39
  constructor(options: {
41
40
  runId: string;
42
41
  threadId?: string;
43
- auth?: AuthContext;
44
42
  initialRun: Run;
45
43
  getRun: () => Promise<Run | null>;
46
44
  getThreadState?: () => Promise<{
@@ -1,6 +1,5 @@
1
1
  import type { AgentResult, AgentStatus, AgentTreeNode, Channel, Checkpoint, CheckpointSource, Command, CommandResponse, ContentBlockDeltaData, ContentBlockFinishData, ContentBlockStartData, CustomData, ErrorCode, ErrorResponse, Event, LifecycleCause, MessageErrorData, MessageFinishData, MessageMetadata, MessageStartData, MessagesData, Namespace, ResponseMeta, RunStartParams, RunResult, StateGetResult, SubscribeParams, SubscribeResult, ToolErrorData, ToolFinishedData, ToolOutputDeltaData, ToolStartedData, ToolsData, UnsubscribeParams, UpdatesEvent } from "@langchain/protocol";
2
2
  export type { LifecycleCause };
3
- import type { AuthContext } from "../auth/index.mjs";
4
3
  import type { RunProtocolSession } from "./session/index.mjs";
5
4
  /**
6
5
  * Raw events emitted by the existing LangGraph run stream implementation
@@ -90,7 +89,6 @@ export type EventSinkEntry = {
90
89
  export type ThreadRecord = {
91
90
  threadId: string;
92
91
  transport: ProtocolTransportName;
93
- auth?: AuthContext;
94
92
  assistantId?: string;
95
93
  seq: number;
96
94
  session?: RunProtocolSession;
package/dist/queue.mjs CHANGED
@@ -5,6 +5,26 @@ import { serializeError } from "./utils/serde.mjs";
5
5
  import { callWebhook } from "./webhook.mjs";
6
6
  import { getGraph } from "./graph/load.mjs";
7
7
  const MAX_RETRY_ATTEMPTS = 3;
8
+ // Strict resume refuses an answer to an interrupt that isn't pending. A retry
9
+ // sends its answer again, and an `interrupt` or `rollback` run that found one
10
+ // in flight has already cancelled it, so refusing either would stop the agent
11
+ // mid-turn: those resume as before.
12
+ function withStrictResume(run, attempt) {
13
+ const strict = attempt === 1 && !run.kwargs.cancels_inflight;
14
+ return {
15
+ ...run,
16
+ kwargs: {
17
+ ...run.kwargs,
18
+ config: {
19
+ ...run.kwargs.config,
20
+ configurable: {
21
+ ...run.kwargs.config?.configurable,
22
+ __pregel_strict_resume: strict,
23
+ },
24
+ },
25
+ },
26
+ };
27
+ }
8
28
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
9
29
  export const queue = async (ops) => {
10
30
  while (true) {
@@ -26,7 +46,16 @@ const worker = async (ops, run, attempt, signal) => {
26
46
  let exception = undefined;
27
47
  let status = undefined;
28
48
  const temporary = run.kwargs.temporary;
49
+ const resumable = run.kwargs?.resumable ?? false;
29
50
  const webhook = run.kwargs.webhook;
51
+ // A stateless run is deleted as soon as it ends, so its streams can no
52
+ // longer read how it ended: the worker sends their `end` before the delete.
53
+ const publishEnd = (status) => ops.runs.stream.publish({
54
+ runId: run.run_id,
55
+ resumable,
56
+ event: "end",
57
+ data: { run_id: run.run_id, status },
58
+ });
30
59
  logger.info("Starting background run", {
31
60
  run_id: run.run_id,
32
61
  run_attempt: attempt,
@@ -70,9 +99,8 @@ const worker = async (ops, run, attempt, signal) => {
70
99
  throw new Error(`Run ${run.run_id} exceeded max attempts`);
71
100
  }
72
101
  const runId = run.run_id;
73
- const resumable = run.kwargs?.resumable ?? false;
74
102
  try {
75
- const stream = streamState(run, {
103
+ const stream = streamState(withStrictResume(run, attempt), {
76
104
  getGraph,
77
105
  attempt,
78
106
  signal,
@@ -117,6 +145,8 @@ const worker = async (ops, run, attempt, signal) => {
117
145
  checkpoint = undefined;
118
146
  if (signal.reason === "rollback") {
119
147
  status = "rollback";
148
+ if (temporary)
149
+ await publishEnd(status);
120
150
  await unlessGone(ops.runs.delete(run.run_id, run.thread_id, undefined), runGone);
121
151
  }
122
152
  else {
@@ -144,8 +174,23 @@ const worker = async (ops, run, attempt, signal) => {
144
174
  }
145
175
  finally {
146
176
  if (temporary) {
177
+ if (status != null && status !== "rollback")
178
+ await publishEnd(status);
147
179
  await unlessGone(ops.threads.delete(run.thread_id, undefined), threadGone);
148
180
  }
181
+ else if (exception?.name === "UnknownInterruptError") {
182
+ // A refused resume ran nothing, so the thread is set from the state it
183
+ // already had. A task that failed in an earlier run leaves the thread
184
+ // `error`, as that run did.
185
+ await unlessGone(ops.threads.state
186
+ .get({ configurable: { thread_id: run.thread_id } }, { subgraphs: false }, undefined)
187
+ .then((state) => ops.threads.setStatus(run.thread_id, {
188
+ checkpoint: state,
189
+ exception: state.tasks.some((task) => task.error != null)
190
+ ? exception
191
+ : undefined,
192
+ })), threadGone);
193
+ }
149
194
  else {
150
195
  await unlessGone(ops.threads.setStatus(run.thread_id, { checkpoint, exception }), threadGone);
151
196
  }
@@ -18,11 +18,6 @@ export declare class FileSystemOps implements Ops {
18
18
  declare class Queue {
19
19
  private log;
20
20
  private listeners;
21
- private nextId;
22
- private resumable;
23
- constructor(options: {
24
- resumable: boolean;
25
- });
26
21
  push(item: Message): void;
27
22
  get(options: {
28
23
  timeout: number;
@@ -33,13 +28,14 @@ declare class Queue {
33
28
  declare class CancellationAbortController extends AbortController {
34
29
  abort(reason: "rollback" | "interrupt"): void;
35
30
  }
31
+ export declare const RUN_LOG_GRACE_MS = 120000;
36
32
  declare class StreamManagerImpl {
37
- readers: Record<string, Queue>;
33
+ readers: Map<string, Queue>;
38
34
  control: Record<string, CancellationAbortController>;
39
- getQueue(runId: string, options: {
40
- ifNotFound: "create";
41
- resumable: boolean;
42
- }): Queue;
35
+ private expiry;
36
+ getQueue(runId: string): Queue;
37
+ freeLater(runId: string): void;
38
+ free(runId: string): void;
43
39
  getControl(runId: string): CancellationAbortController | undefined;
44
40
  isLocked(runId: string): boolean;
45
41
  lock(runId: string): AbortSignal;
@@ -40,40 +40,25 @@ class TimeoutError extends Error {
40
40
  class AbortError extends Error {
41
41
  }
42
42
  class Queue {
43
+ // Never trimmed: each reader of a run reads it from its own cursor.
43
44
  log = [];
44
45
  listeners = [];
45
- nextId = 0;
46
- resumable = false;
47
- constructor(options) {
48
- this.resumable = options.resumable;
49
- }
50
46
  push(item) {
51
47
  this.log.push(item);
52
48
  for (const listener of this.listeners)
53
- listener(this.nextId);
54
- this.nextId += 1;
49
+ listener(this.log.length - 1);
55
50
  }
56
51
  async get(options) {
57
- if (this.resumable) {
58
- const lastEventId = options.lastEventId;
59
- // Generator stores internal state of the read head index,
60
- let targetId = lastEventId != null ? +lastEventId + 1 : null;
61
- if (targetId == null ||
62
- isNaN(targetId) ||
63
- targetId < 0 ||
64
- targetId >= this.log.length) {
65
- targetId = null;
66
- }
67
- if (targetId != null)
68
- return [String(targetId), this.log[targetId]];
69
- }
70
- else {
71
- if (this.log.length) {
72
- const nextId = this.nextId - this.log.length;
73
- const nextItem = this.log.shift();
74
- return [String(nextId), nextItem];
75
- }
52
+ const lastEventId = options.lastEventId;
53
+ let targetId = lastEventId != null ? +lastEventId + 1 : null;
54
+ if (targetId == null ||
55
+ isNaN(targetId) ||
56
+ targetId < 0 ||
57
+ targetId >= this.log.length) {
58
+ targetId = null;
76
59
  }
60
+ if (targetId != null)
61
+ return [String(targetId), this.log[targetId]];
77
62
  let timeout = undefined;
78
63
  let resolver = undefined;
79
64
  const clean = new AbortController();
@@ -84,14 +69,7 @@ class Queue {
84
69
  options.signal?.addEventListener("abort", () => reject(new AbortError()), { signal: clean.signal });
85
70
  this.listeners.push(resolver);
86
71
  })
87
- .then((idx) => {
88
- if (this.resumable) {
89
- return [String(idx), this.log[idx]];
90
- }
91
- const nextId = this.nextId - this.log.length;
92
- const nextItem = this.log.shift();
93
- return [String(nextId), nextItem];
94
- })
72
+ .then((idx) => [String(idx), this.log[idx]])
95
73
  .finally(() => {
96
74
  this.listeners = this.listeners.filter((l) => l !== resolver);
97
75
  clearTimeout(timeout);
@@ -104,14 +82,33 @@ class CancellationAbortController extends AbortController {
104
82
  super.abort(reason);
105
83
  }
106
84
  }
85
+ // Long enough for a client that lost a finished run's stream, or reloaded its
86
+ // page, to rejoin with Last-Event-ID and replay the rest.
87
+ export const RUN_LOG_GRACE_MS = 120_000;
107
88
  class StreamManagerImpl {
108
- readers = {};
89
+ readers = new Map();
109
90
  control = {};
110
- getQueue(runId, options) {
111
- if (this.readers[runId] == null) {
112
- this.readers[runId] = new Queue(options);
91
+ expiry = new Map();
92
+ getQueue(runId) {
93
+ let queue = this.readers.get(runId);
94
+ if (queue == null) {
95
+ queue = new Queue();
96
+ this.readers.set(runId, queue);
113
97
  }
114
- return this.readers[runId];
98
+ return queue;
99
+ }
100
+ freeLater(runId) {
101
+ clearTimeout(this.expiry.get(runId));
102
+ this.expiry.set(runId, setTimeout(() => this.free(runId), RUN_LOG_GRACE_MS).unref());
103
+ }
104
+ free(runId) {
105
+ // A worker that still holds the run keeps publishing to its log, which is
106
+ // freed a grace period after the worker lets the run go.
107
+ if (this.isLocked(runId))
108
+ return;
109
+ clearTimeout(this.expiry.get(runId));
110
+ this.expiry.delete(runId);
111
+ this.readers.delete(runId);
115
112
  }
116
113
  getControl(runId) {
117
114
  if (this.control[runId] == null)
@@ -631,6 +628,7 @@ export class FileSystemThreads {
631
628
  for (const run of Object.values(STORE.runs)) {
632
629
  if (run["thread_id"] === thread_id) {
633
630
  delete STORE.runs[run["run_id"]];
631
+ StreamManager.free(run["run_id"]);
634
632
  }
635
633
  }
636
634
  checkpointer.delete(thread_id, null);
@@ -930,6 +928,8 @@ export class FileSystemRuns {
930
928
  STORE.retry_counter[runId] += 1;
931
929
  STORE.runs[runId].status = "running";
932
930
  yield { run, attempt: STORE.retry_counter[runId], signal };
931
+ // The worker is done with the run when it asks for the next one.
932
+ StreamManager.freeLater(runId);
933
933
  }
934
934
  finally {
935
935
  StreamManager.unlock(runId);
@@ -1035,6 +1035,9 @@ export class FileSystemRuns {
1035
1035
  context: typeof assistant.context !== "object" && assistant.context != null
1036
1036
  ? (assistant.context ?? kwargs.context)
1037
1037
  : Object.assign({}, assistant.context, kwargs.context),
1038
+ cancels_inflight: (multitaskStrategy === "interrupt" ||
1039
+ multitaskStrategy === "rollback") &&
1040
+ inflightRuns.length > 0,
1038
1041
  }),
1039
1042
  multitask_strategy: multitaskStrategy,
1040
1043
  created_at: new Date(now.valueOf() + afterSeconds * 1000),
@@ -1079,10 +1082,11 @@ export class FileSystemRuns {
1079
1082
  }
1080
1083
  // Ends the run's open streams, which would otherwise wait out their
1081
1084
  // timeout and report the run as not found.
1082
- StreamManager.readers[run_id]?.push({
1085
+ StreamManager.readers.get(run_id)?.push({
1083
1086
  topic: `run:${run_id}:control`,
1084
1087
  data: "done",
1085
1088
  });
1089
+ StreamManager.free(run_id);
1086
1090
  if (thread_id != null)
1087
1091
  checkpointer.delete(thread_id, run_id);
1088
1092
  delete STORE.runs[run_id];
@@ -1090,7 +1094,7 @@ export class FileSystemRuns {
1090
1094
  });
1091
1095
  }
1092
1096
  async wait(runId, threadId, auth) {
1093
- const runStream = this.stream.join(runId, threadId, { ignore404: threadId == null, lastEventId: undefined }, auth);
1097
+ const runStream = this.stream.join(runId, threadId, { ignore404: threadId == null, lastEventId: "-1" }, auth);
1094
1098
  const lastChunk = new Promise(async (resolve, reject) => {
1095
1099
  try {
1096
1100
  let lastChunk = null;
@@ -1143,6 +1147,9 @@ export class FileSystemRuns {
1143
1147
  const control = StreamManager.getControl(runId);
1144
1148
  control?.abort(options.action ?? "interrupt");
1145
1149
  if (run.status === "pending") {
1150
+ // No worker will run it now, so free the log a join may have made.
1151
+ if (control == null)
1152
+ StreamManager.freeLater(runId);
1146
1153
  if (control == null && run.kwargs.temporary) {
1147
1154
  // No worker will run it now, so nothing else deletes it, or its
1148
1155
  // temporary thread once no other run is left on it.
@@ -1234,19 +1241,13 @@ export class FileSystemRuns {
1234
1241
  const conn = this.conn;
1235
1242
  const runs = this.runs;
1236
1243
  yield* conn.withGenerator(async function* (STORE) {
1237
- // TODO: what if we're joining an already completed run? Should we check before?
1238
1244
  const signal = options?.signal;
1239
- const queue = StreamManager.getQueue(runId, {
1240
- ifNotFound: "create",
1241
- resumable: options.lastEventId != null,
1242
- });
1243
1245
  const [filters] = await handleAuthEvent(auth, "threads:read", {
1244
1246
  thread_id: threadId,
1245
1247
  });
1246
1248
  // TODO: consolidate into a single function
1247
1249
  if (filters != null && threadId != null) {
1248
- const thread = STORE.threads[threadId];
1249
- if (!isAuthMatching(thread["metadata"], filters)) {
1250
+ if (!isAuthMatching(STORE.threads[threadId]?.metadata, filters)) {
1250
1251
  yield {
1251
1252
  event: "error",
1252
1253
  data: { error: "Error", message: "404: Thread not found" },
@@ -1254,6 +1255,31 @@ export class FileSystemRuns {
1254
1255
  return;
1255
1256
  }
1256
1257
  }
1258
+ if (threadId != null && STORE.runs[runId]?.thread_id !== threadId) {
1259
+ if (!options?.ignore404)
1260
+ yield { event: "error", data: "Run not found" };
1261
+ return;
1262
+ }
1263
+ // The requests that create a stateless run don't pass this: the run
1264
+ // and its temporary thread can be deleted before their first read, and
1265
+ // that thread's metadata comes from `threads:create_run`, which
1266
+ // `threads:read` filters may not match.
1267
+ if (options.checkRunAccess && filters != null) {
1268
+ const run = STORE.runs[runId];
1269
+ if (run == null ||
1270
+ !isAuthMatching(STORE.threads[run.thread_id]?.metadata, filters)) {
1271
+ return;
1272
+ }
1273
+ }
1274
+ // A run that has ended or is gone has nothing more for a join to
1275
+ // read, and a log created for it might never be freed.
1276
+ const status = STORE.runs[runId]?.status;
1277
+ if (!StreamManager.readers.has(runId) &&
1278
+ status !== "pending" &&
1279
+ status !== "running") {
1280
+ return;
1281
+ }
1282
+ const queue = StreamManager.getQueue(runId);
1257
1283
  let lastEventId = options?.lastEventId;
1258
1284
  while (!signal?.aborted) {
1259
1285
  try {
@@ -1305,10 +1331,7 @@ export class FileSystemRuns {
1305
1331
  });
1306
1332
  }
1307
1333
  async publish(payload) {
1308
- const queue = StreamManager.getQueue(payload.runId, {
1309
- ifNotFound: "create",
1310
- resumable: payload.resumable,
1311
- });
1334
+ const queue = StreamManager.getQueue(payload.runId);
1312
1335
  queue.push({
1313
1336
  topic: `run:${payload.runId}:stream:${payload.event}`,
1314
1337
  data: payload.data,
@@ -60,6 +60,7 @@ export interface RunKwargs {
60
60
  subgraphs?: boolean;
61
61
  resumable?: boolean;
62
62
  temporary?: boolean;
63
+ cancels_inflight?: boolean;
63
64
  webhook?: unknown;
64
65
  feedback_keys?: string[] | undefined;
65
66
  [key: string]: unknown;
@@ -181,6 +182,7 @@ export interface RunsStreamRepo {
181
182
  signal?: AbortSignal;
182
183
  cancelOnDisconnect?: boolean;
183
184
  lastEventId: string | undefined;
185
+ checkRunAccess?: boolean;
184
186
  }, auth: AuthContext | undefined): AsyncGenerator<{
185
187
  id?: string;
186
188
  event: string;
package/dist/stream.mjs CHANGED
@@ -278,8 +278,8 @@ export async function* streamState(run, options) {
278
278
  }
279
279
  }
280
280
  export const matchesStreamMode = (event, streamMode) => {
281
- // A run's error is its outcome, not a mode, so no filter drops it.
282
- if (streamMode.length === 0 || event === "error")
281
+ // A run's error and end are its outcome, not modes, so no filter drops them.
282
+ if (streamMode.length === 0 || event === "error" || event === "end")
283
283
  return true;
284
284
  const mode = event.split("|")[0];
285
285
  if (streamMode.includes(mode))
@@ -2,4 +2,13 @@ export declare const serialiseAsDict: (obj: unknown) => string;
2
2
  export declare const serializeError: (error: unknown) => {
3
3
  error: string;
4
4
  message: string;
5
+ reason: string | undefined;
6
+ interrupt_ids: string[] | undefined;
7
+ pending_ids: string[] | undefined;
8
+ } | {
9
+ error: string;
10
+ message: string;
11
+ reason?: undefined;
12
+ interrupt_ids?: undefined;
13
+ pending_ids?: undefined;
5
14
  };
@@ -13,6 +13,17 @@ export const serialiseAsDict = (obj) => {
13
13
  });
14
14
  };
15
15
  export const serializeError = (error) => {
16
+ // Matched by name: the graph may load its own copy of @langchain/langgraph.
17
+ if (error instanceof Error && error.name === "UnknownInterruptError") {
18
+ const { reason, interruptIds, pendingIds } = error;
19
+ return {
20
+ error: error.name,
21
+ message: error.message,
22
+ reason,
23
+ interrupt_ids: interruptIds,
24
+ pending_ids: pendingIds,
25
+ };
26
+ }
16
27
  if (error instanceof Error) {
17
28
  return { error: error.name, message: error.message };
18
29
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@langchain/langgraph-api",
3
- "version": "1.5.8",
3
+ "version": "1.6.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": "^18.19.0 || >=20.16.0"
@@ -71,7 +71,7 @@
71
71
  "winston": "^3.17.0",
72
72
  "winston-console-format": "^1.0.8",
73
73
  "zod": "^4.6.6",
74
- "@langchain/langgraph-ui": "1.5.8"
74
+ "@langchain/langgraph-ui": "1.6.0"
75
75
  },
76
76
  "peerDependencies": {
77
77
  "@langchain/core": "^1.1.48",
@@ -104,9 +104,9 @@
104
104
  "typescript": "^4.9.5 || ^5.4.5",
105
105
  "vitest": "^4.1.12",
106
106
  "wait-port": "^1.1.0",
107
- "@langchain/langgraph": "1.6.1",
108
- "@langchain/langgraph-sdk": "1.12.10",
109
- "@langchain/langgraph-checkpoint": "1.2.2"
107
+ "@langchain/langgraph": "1.7.0",
108
+ "@langchain/langgraph-checkpoint": "1.2.2",
109
+ "@langchain/langgraph-sdk": "1.13.0"
110
110
  },
111
111
  "scripts": {
112
112
  "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",