@langchain/langgraph-api 1.4.0 → 1.4.2

package/dist/api/runs.mjs

@@ -9,6 +9,7 @@ import { logError, logger } from "../logging.mjs";
 import * as schemas from "../schemas.mjs";
 import { runs, threads } from "../storage/context.mjs";
 import { getDisconnectAbortSignal, jsonExtra, waitKeepAlive, } from "../utils/hono.mjs";
+import { applyAuthToRunConfig, applyRequestHeadersToRunConfig, } from "../utils/run-auth.mjs";
 import { serialiseAsDict } from "../utils/serde.mjs";
 const api = new Hono();
 const createValidRun = async (threadId, payload, kwargs) => {
@@ -40,30 +41,8 @@ const createValidRun = async (threadId, payload, kwargs) => {
             langsmith_example_id: run.langsmith_tracer.example_id,
         });
     }
-    if (headers) {
-        for (const [rawKey, value] of headers.entries()) {
-            const key = rawKey.toLowerCase();
-            if (key.startsWith("x-")) {
-                if (["x-api-key", "x-tenant-id", "x-service-key"].includes(key)) {
-                    continue;
-                }
-                config.configurable ??= {};
-                config.configurable[key] = value;
-            }
-            else if (key === "user-agent") {
-                config.configurable ??= {};
-                config.configurable[key] = value;
-            }
-        }
-    }
-    let userId;
-    if (auth) {
-        userId = auth.user.identity ?? auth.user.id;
-        config.configurable ??= {};
-        config.configurable["langgraph_auth_user"] = auth.user;
-        config.configurable["langgraph_auth_user_id"] = userId;
-        config.configurable["langgraph_auth_permissions"] = auth.scopes;
-    }
+    applyRequestHeadersToRunConfig(config, headers);
+    const userId = applyAuthToRunConfig(config, auth);
     let feedbackKeys = run.feedback_keys != null
         ? Array.isArray(run.feedback_keys)
             ? run.feedback_keys

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/protocol/service.mjs

@@ -1,6 +1,7 @@
 import { inferChannel, isPrefixMatch } from "@langchain/langgraph/stream";
 import { v7 as uuid7 } from "@langchain/core/utils/uuid";
 import { getAssistantId } from "../graph/load.mjs";
+import { applyAuthToRunConfig } from "../utils/run-auth.mjs";
 import { PROTOCOL_STREAM_RUN_KEY } from "./constants.mjs";
 import { RunProtocolSession } from "./session/index.mjs";
 const DEFAULT_RUN_STREAM_MODES = [
@@ -326,6 +327,7 @@ export class ProtocolService {
                 thread_id: record.threadId,
             },
         };
+        const userId = applyAuthToRunConfig(runConfig, record.auth);
         const runPayload = {
             assistant_id: assistantId,
             input: isResume ? null : params.input,
@@ -366,6 +368,7 @@ export class ProtocolService {
             [PROTOCOL_STREAM_RUN_KEY]: true,
         }, {
             threadId: record.threadId,
+            userId,
             metadata: runPayload.metadata,
             status: "pending",
             multitaskStrategy: runPayload.multitask_strategy,

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/dist/utils/run-auth.d.mts

@@ -0,0 +1,13 @@
+import type { AuthContext } from "../auth/index.mjs";
+import type { RunnableConfig } from "../storage/types.mjs";
+/**
+ * Copy allowed request headers into `config.configurable`, matching the REST
+ * runs API (`createValidRun`). Used by both REST and protocol-v2 run creation.
+ */
+export declare function applyRequestHeadersToRunConfig(config: RunnableConfig, headers: Headers | undefined): void;
+/**
+ * Stamp the authenticated user onto `config.configurable` so graph nodes and
+ * tools can read `langgraph_auth_user`. Returns the resolved user id for run
+ * metadata when auth is present.
+ */
+export declare function applyAuthToRunConfig(config: RunnableConfig, auth: AuthContext | undefined): string | undefined;

package/dist/utils/run-auth.mjs

@@ -0,0 +1,42 @@
+const BLOCKED_CONFIGURABLE_HEADERS = new Set([
+    "x-api-key",
+    "x-tenant-id",
+    "x-service-key",
+]);
+/**
+ * Copy allowed request headers into `config.configurable`, matching the REST
+ * runs API (`createValidRun`). Used by both REST and protocol-v2 run creation.
+ */
+export function applyRequestHeadersToRunConfig(config, headers) {
+    if (!headers)
+        return;
+    for (const [rawKey, value] of headers.entries()) {
+        const key = rawKey.toLowerCase();
+        if (key.startsWith("x-")) {
+            if (BLOCKED_CONFIGURABLE_HEADERS.has(key))
+                continue;
+            config.configurable ??= {};
+            config.configurable[key] = value;
+        }
+        else if (key === "user-agent") {
+            config.configurable ??= {};
+            config.configurable[key] = value;
+        }
+    }
+}
+/**
+ * Stamp the authenticated user onto `config.configurable` so graph nodes and
+ * tools can read `langgraph_auth_user`. Returns the resolved user id for run
+ * metadata when auth is present.
+ */
+export function applyAuthToRunConfig(config, auth) {
+    if (!auth)
+        return undefined;
+    const userId = auth.user.identity ??
+        (typeof auth.user.id === "string" ? auth.user.id : undefined);
+    config.configurable ??= {};
+    config.configurable.langgraph_auth_user = auth.user;
+    config.configurable.langgraph_auth_user_id = userId;
+    config.configurable.langgraph_auth_permissions = auth.scopes;
+    return userId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -71,37 +71,42 @@
     "winston": "^3.17.0",
     "winston-console-format": "^1.0.8",
     "zod": "^3.25.76 || ^4",
-    "@langchain/langgraph-ui": "1.4.0"
+    "@langchain/langgraph-ui": "1.4.2"
   },
   "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.2.1",
     "@types/babel__code-frame": "^7.0.6",
     "@types/node": "^18.15.11",
-    "@types/react": "^19.2.16",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.0.3",
     "@types/semver": "^7.7.0",
     "deepagents": "^1.10.5",
     "jose": "^6.0.10",
-    "langchain": "^1.5.1",
+    "langchain": "^1.5.2",
     "postgres": "^3.4.5",
+    "ts-node": "^10.9.2",
     "typescript": "^4.9.5 || ^5.4.5",
-    "vitest": "^4.1.0",
+    "vitest": "^4.1.9",
     "wait-port": "^1.1.0",
-    "@langchain/langgraph": "1.4.5",
-    "@langchain/langgraph-checkpoint": "1.1.2",
-    "@langchain/langgraph-sdk": "1.9.24"
+    "@langchain/langgraph": "1.4.7",
+    "@langchain/langgraph-sdk": "1.9.25",
+    "@langchain/langgraph-checkpoint": "1.1.3"
   },
   "scripts": {
     "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",