@langchain/langgraph-api 1.3.1 → 1.4.1

package/dist/cli/spawn-args.d.mts

@@ -0,0 +1,35 @@
+import type { StartServerOptions } from "../server.mjs";
+/** Default loader: tsx CLI with built-in watch. */
+export declare const DEFAULT_NODE_LOADER = "tsx";
+type LoaderRegistration = {
+    specifier: string;
+    flag: "--loader" | "--import";
+};
+/**
+ * Shorthand loader names mapped to Node registration hooks.
+ * Use `"tsx"` (not `"tsx/esm"`) to spawn via the tsx CLI instead.
+ *
+ * `ts-node` uses `--loader` (not `--import`) because `ts-node/esm` is a
+ * custom ESM loader hook. Node 20+ deprecates `--loader` in favor of
+ * `module.register()`, but ts-node still documents this entrypoint.
+ */
+export declare const LOADER_REGISTRATIONS: Record<string, LoaderRegistration>;
+export declare function resolveNodeLoader(configLoader: string | undefined, env?: NodeJS.ProcessEnv): string;
+export declare function resolveLoaderRegistration(loader: string, resolve: (specifier: string) => string): LoaderRegistration & {
+    path: string;
+};
+export declare function resolveLoaderPath(specifier: string, loader: string, resolve: (specifier: string) => string): string;
+/** Convert a resolved filesystem path to a Node `--loader`/`--import` URL. */
+export declare function toNodeModuleUrl(path: string): string;
+export declare function usesTsxCli(loader: string): boolean;
+export declare function buildSpawnArgs(options: {
+    nodeLoader: string;
+    reload: boolean;
+    pid: number;
+    payload: StartServerOptions;
+    resolve: (specifier: string) => string;
+}): {
+    command: string;
+    args: string[];
+};
+export {};

package/dist/cli/spawn-args.mjs

@@ -0,0 +1,85 @@
+import { isAbsolute } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+/** Default loader: tsx CLI with built-in watch. */
+export const DEFAULT_NODE_LOADER = "tsx";
+/**
+ * Shorthand loader names mapped to Node registration hooks.
+ * Use `"tsx"` (not `"tsx/esm"`) to spawn via the tsx CLI instead.
+ *
+ * `ts-node` uses `--loader` (not `--import`) because `ts-node/esm` is a
+ * custom ESM loader hook. Node 20+ deprecates `--loader` in favor of
+ * `module.register()`, but ts-node still documents this entrypoint.
+ */
+export const LOADER_REGISTRATIONS = {
+    "ts-node": { specifier: "ts-node/esm", flag: "--loader" },
+    "ts-node/esm": { specifier: "ts-node/esm", flag: "--loader" },
+};
+export function resolveNodeLoader(configLoader, env = process.env) {
+    const envLoader = env.LANGGRAPH_NODE_LOADER?.trim();
+    if (envLoader)
+        return envLoader;
+    return configLoader ?? DEFAULT_NODE_LOADER;
+}
+export function resolveLoaderRegistration(loader, resolve) {
+    const registration = LOADER_REGISTRATIONS[loader] ?? {
+        specifier: loader,
+        flag: "--import",
+    };
+    const path = resolveLoaderPath(registration.specifier, loader, resolve);
+    return { ...registration, path };
+}
+export function resolveLoaderPath(specifier, loader, resolve) {
+    if (specifier.startsWith("file://")) {
+        return fileURLToPath(specifier);
+    }
+    if (isAbsolute(specifier)) {
+        return specifier;
+    }
+    try {
+        return fileURLToPath(new URL(resolve(specifier)));
+    }
+    catch {
+        const hint = loader === "ts-node" || loader.startsWith("ts-node/")
+            ? ' Install "ts-node" and enable "emitDecoratorMetadata" in tsconfig when using reflect-metadata.'
+            : "";
+        throw new Error(`node_loader "${loader}" could not be resolved.${hint} Install the package or provide a valid module specifier, file path, or file:// URL.`);
+    }
+}
+/** Convert a resolved filesystem path to a Node `--loader`/`--import` URL. */
+export function toNodeModuleUrl(path) {
+    if (path.startsWith("file://"))
+        return path;
+    return pathToFileURL(path).href;
+}
+export function usesTsxCli(loader) {
+    return loader === DEFAULT_NODE_LOADER;
+}
+export function buildSpawnArgs(options) {
+    const payloadArg = JSON.stringify(options.payload);
+    const sharedArgs = [options.pid.toString(), payloadArg];
+    const preloadUrl = new URL(options.resolve("../preload.mjs")).toString();
+    const entrypointPath = fileURLToPath(new URL(options.resolve("./entrypoint.mjs")));
+    if (usesTsxCli(options.nodeLoader)) {
+        const args = [
+            fileURLToPath(new URL("../../cli.mjs", options.resolve("tsx/esm/api"))),
+            ...(options.reload ? ["watch"] : []),
+            "--clear-screen=false",
+            "--import",
+            preloadUrl,
+            entrypointPath,
+            ...sharedArgs,
+        ];
+        return { command: process.execPath, args };
+    }
+    const loader = resolveLoaderRegistration(options.nodeLoader, options.resolve);
+    const args = [
+        ...(options.reload ? ["--watch"] : []),
+        loader.flag,
+        toNodeModuleUrl(loader.path),
+        "--import",
+        preloadUrl,
+        entrypointPath,
+        ...sharedArgs,
+    ];
+    return { command: process.execPath, args };
+}

package/dist/cli/spawn.d.mts

@@ -1,7 +1,9 @@
+import { type StartServerOptions } from "../server.mjs";
 export declare function spawnServer(args: {
     host: string;
     port: string;
     nJobsPerWorker: string;
+    reload?: boolean;
 }, context: {
     config: {
         graphs: Record<string, string | {
@@ -16,23 +18,8 @@ export declare function spawnServer(args: {
             path?: string;
             disable_studio_auth?: boolean;
         };
-        http?: {
-            app?: string;
-            disable_assistants?: boolean;
-            disable_threads?: boolean;
-            disable_runs?: boolean;
-            disable_store?: boolean;
-            disable_meta?: boolean;
-            cors?: {
-                allow_origins?: string[];
-                allow_methods?: string[];
-                allow_headers?: string[];
-                allow_credentials?: boolean;
-                allow_origin_regex?: string;
-                expose_headers?: string[];
-                max_age?: number;
-            };
-        };
+        node_loader?: string;
+        http?: StartServerOptions["http"];
     };
     env: NodeJS.ProcessEnv;
     hostUrl: string;

package/dist/cli/spawn.mjs

@@ -1,5 +1,6 @@
-import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+import { StartServerSchema } from "../server.mjs";
+import { buildSpawnArgs, resolveNodeLoader } from "./spawn-args.mjs";
 export async function spawnServer(args, context, options) {
     const localUrl = `http://${args.host}:${args.port}`;
     const studioUrl = `${context.hostUrl}/studio?baseUrl=${localUrl}`;
@@ -17,26 +18,26 @@ This in-memory server is designed for development and testing.
 For production use, please use LangSmith Deployment.
 
 `);
-    return spawn(process.execPath, [
-        fileURLToPath(new URL("../../cli.mjs", import.meta.resolve("tsx/esm/api"))),
-        "watch",
-        "--clear-screen=false",
-        "--import",
-        new URL(import.meta.resolve("../preload.mjs")).toString(),
-        fileURLToPath(new URL(import.meta.resolve("./entrypoint.mjs"))),
-        options.pid.toString(),
-        JSON.stringify({
-            port: Number.parseInt(args.port, 10),
-            nWorkers: Number.parseInt(args.nJobsPerWorker, 10),
-            host: args.host,
-            graphs: context.config.graphs,
-            auth: context.config.auth,
-            ui: context.config.ui,
-            ui_config: context.config.ui_config,
-            cwd: options.projectCwd,
-            http: context.config.http,
-        }),
-    ], {
+    const nodeLoader = resolveNodeLoader(context.config.node_loader, context.env);
+    const payload = StartServerSchema.parse({
+        port: Number.parseInt(args.port, 10),
+        nWorkers: Number.parseInt(args.nJobsPerWorker, 10),
+        host: args.host,
+        graphs: context.config.graphs,
+        auth: context.config.auth,
+        ui: context.config.ui,
+        ui_config: context.config.ui_config,
+        cwd: options.projectCwd,
+        http: context.config.http,
+    });
+    const { command, args: spawnArgs } = buildSpawnArgs({
+        nodeLoader,
+        reload: args.reload ?? true,
+        pid: options.pid,
+        payload,
+        resolve: (specifier) => import.meta.resolve(specifier),
+    });
+    return spawn(command, spawnArgs, {
         stdio: ["inherit", "inherit", "inherit", "ipc"],
         env: {
             ...context.env,

package/dist/experimental/embed/protocol.mjs

@@ -298,11 +298,31 @@ export function registerProtocolRoutes(api, context, upgradeWebSocket) {
                 message: "Thread has no active assistant; call run.start first.",
             });
         }
+        // `update` / `goto` are the optional state mutation and directed jump
+        // the SDK's `respond({ update, goto })` forwards on `input.respond`
+        // (`InputRespondOne` / `InputRespondMany`). Fold them into the same
+        // `Command(resume, update, goto)` as the resume so the resumed run
+        // produces a single checkpoint reflecting all of them — the HITL
+        // "push card into state + resume" flow. Read leniently (update: object
+        // or `[key, value][]` tuples; goto: node name, Send object, or a list
+        // of either), same posture as `config` / `metadata`.
+        const update = isRecord(params.update) || Array.isArray(params.update)
+            ? params.update
+            : undefined;
+        const goto = typeof params.goto === "string" ||
+            Array.isArray(params.goto) ||
+            isRecord(params.goto)
+            ? params.goto
+            : undefined;
         const run = createStubRun(thread.threadId, {
             assistant_id: assistantId,
             on_disconnect: "cancel",
             input: null,
-            command: { resume: resumeInput },
+            command: {
+                resume: resumeInput,
+                ...(update != null ? { update } : {}),
+                ...(goto != null ? { goto } : {}),
+            },
             // 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).

package/dist/protocol/service.mjs

@@ -267,9 +267,26 @@ export class ProtocolService {
         // context, …) and metadata (trigger source, test flags, …) a fresh
         // `run.start` would. Read them leniently — same posture as
         // `normalizeRunStart`.
+        // `update` / `goto` are the optional state mutation and directed jump
+        // applied in the same superstep as the resume (`InputRespondOne` /
+        // `InputRespondMany`). The SDK's `respond({ update, goto })` forwards them
+        // on the `input.respond` command; they are folded into
+        // `Command(resume, update, goto)` by `createOrResumeRun`. Read leniently
+        // (update: object or [key, value][] tuples; goto: node name, Send object,
+        // or a list of either) — same posture as `config` / `metadata`.
+        const update = isRecord(rawParams.update) || Array.isArray(rawParams.update)
+            ? rawParams.update
+            : undefined;
+        const goto = typeof rawParams.goto === "string" ||
+            Array.isArray(rawParams.goto) ||
+            isRecord(rawParams.goto)
+            ? rawParams.goto
+            : undefined;
         await this.createOrResumeRun(record, {
             assistant_id: record.assistantId,
             input: resumeInput,
+            update,
+            goto,
             config: isRecord(rawParams.config) ? rawParams.config : undefined,
             metadata: isRecord(rawParams.metadata) ? rawParams.metadata : undefined,
         });
@@ -313,7 +330,16 @@ export class ProtocolService {
             assistant_id: assistantId,
             input: isResume ? null : params.input,
             command: isResume
-                ? { resume: params.input }
+                ? {
+                    resume: params.input,
+                    // Apply an optional state update and/or directed jump in the
+                    // same superstep as the resume (HITL "push card into state +
+                    // resume" flows, or resume-and-redirect). Mapped straight onto
+                    // LangGraph's `Command(resume, update, goto)`, so the resumed
+                    // run produces a single checkpoint reflecting all of them.
+                    ...(params.update != null ? { update: params.update } : {}),
+                    ...(params.goto != null ? { goto: params.goto } : {}),
+                }
                 : undefined,
             config: runConfig,
             metadata: params.metadata,

package/dist/protocol/session/state-normalizers.mjs

@@ -357,6 +357,15 @@ export const normalizeProtocolStateMessage = (value) => {
     if (typeof value.name === "string") {
         message.name = value.name;
     }
+    // Preserve `response_metadata` when present. It is a first-class protocol
+    // message field, and HITL flows rely on it: an interrupt's card is carried
+    // on `AIMessage.response_metadata` (e.g. `{ cards: ... }`) and the frontend
+    // pushes that message into state via `respond(decision, { update })`. We
+    // only forward a non-empty record to keep the common (empty) case minimal.
+    if (isRecord(value.response_metadata) &&
+        Object.keys(value.response_metadata).length > 0) {
+        message.response_metadata = value.response_metadata;
+    }
     if ((type === "ai" || type === "human") &&
         typeof value.example === "boolean") {
         message.example = value.example;

package/dist/server.d.mts

@@ -167,7 +167,8 @@ export declare const StartServerSchema: z.ZodObject<{
         disable_meta?: boolean | undefined;
     } | undefined;
 }>;
-export declare function startServer(options: z.infer<typeof StartServerSchema>, storage?: {
+export type StartServerOptions = z.infer<typeof StartServerSchema>;
+export declare function startServer(options: StartServerOptions, storage?: {
     ops?: Ops;
 }): Promise<{
     host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -55,13 +55,13 @@
     "@hono/node-server": "^1.19.13",
     "@hono/node-ws": "^1.3.0",
     "@hono/zod-validator": "^0.7.6",
-    "@langchain/protocol": "^0.0.16",
+    "@langchain/protocol": "^0.0.18",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
     "dotenv": "^16.4.7",
     "exit-hook": "^4.0.0",
-    "hono": "^4.12.21",
+    "hono": "^4.12.25",
     "langsmith": ">=0.5.19 <1.0.0",
     "open": "^10.1.0",
     "semver": "^7.7.1",
@@ -71,37 +71,42 @@
     "winston": "^3.17.0",
     "winston-console-format": "^1.0.8",
     "zod": "^3.25.76 || ^4",
-    "@langchain/langgraph-ui": "1.3.1"
+    "@langchain/langgraph-ui": "1.4.1"
   },
   "peerDependencies": {
     "@langchain/core": "^1.1.48",
     "@langchain/langgraph": "^1.3.6",
     "@langchain/langgraph-checkpoint": "~0.0.16 || ^0.1.0 || ^1.0.0",
     "@langchain/langgraph-sdk": "^1.9.3-rc.0",
+    "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
   },
   "peerDependenciesMeta": {
     "@langchain/langgraph-sdk": {
       "optional": true
+    },
+    "ts-node": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@langchain/core": "^1.1.48",
+    "@langchain/core": "^1.2.1",
     "@types/babel__code-frame": "^7.0.6",
     "@types/node": "^18.15.11",
     "@types/react": "^19.2.16",
     "@types/react-dom": "^19.0.3",
     "@types/semver": "^7.7.0",
-    "deepagents": "^1.9.0",
+    "deepagents": "^1.10.5",
     "jose": "^6.0.10",
-    "langchain": "^1.4.4",
+    "langchain": "^1.5.1",
     "postgres": "^3.4.5",
+    "ts-node": "^10.9.2",
     "typescript": "^4.9.5 || ^5.4.5",
     "vitest": "^4.1.0",
     "wait-port": "^1.1.0",
-    "@langchain/langgraph": "1.4.2",
-    "@langchain/langgraph-checkpoint": "1.1.1",
-    "@langchain/langgraph-sdk": "1.9.22"
+    "@langchain/langgraph": "1.4.6",
+    "@langchain/langgraph-checkpoint": "1.1.3",
+    "@langchain/langgraph-sdk": "1.9.25"
   },
   "scripts": {
     "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",