@langchain/langgraph-api 0.0.55 → 0.0.57

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @langchain/langgraph-api
 
+## 0.0.57
+
+### Patch Changes
+
+- 31cc9f7: support description property for `langgraph.json`
+  - @langchain/langgraph-ui@0.0.57
+
+## 0.0.56
+
+### Patch Changes
+
+- 3c390c9: fix(api): parser: sanitise generated symbol names, honor typescript extension
+  - @langchain/langgraph-ui@0.0.56
+
 ## 0.0.55
 
 ### Patch Changes

package/dist/cli/spawn.d.mts

@@ -4,7 +4,10 @@ export declare function spawnServer(args: {
     nJobsPerWorker: string;
 }, context: {
     config: {
-        graphs: Record<string, string>;
+        graphs: Record<string, string | {
+            path: string;
+            description?: string;
+        }>;
         ui?: Record<string, string>;
         ui_config?: {
             shared?: string[];

package/dist/graph/parser/parser.d.mts

@@ -35,7 +35,9 @@ export declare class SubgraphExtractor {
             node: ts.Node;
         };
     }[];
-    getAugmentedSourceFile: (suffix: string, name: string) => {
+    getAugmentedSourceFile: (sourcePath: string, name: string, options: {
+        allowImportingTsExtensions: boolean;
+    }) => {
         inferFile: {
             fileName: string;
             contents: string;

package/dist/graph/parser/parser.mjs

@@ -12,11 +12,6 @@ const OVERRIDE_RESOLVE = [
     new RegExp(`^@langchain\/langgraph-checkpoint(\/.+)?$`),
 ];
 const INFER_TEMPLATE_PATH = path.resolve(__dirname, "./schema/types.template.mts");
-const compilerOptions = {
-    noEmit: true,
-    strict: true,
-    allowUnusedLabels: true,
-};
 export class SubgraphExtractor {
     program;
     checker;
@@ -145,50 +140,67 @@ export class SubgraphExtractor {
             return this.findSubgraphs(varDecl.initializer, [name]);
         });
     };
-    getAugmentedSourceFile = (suffix, name) => {
+    getAugmentedSourceFile = (sourcePath, name, options) => {
+        function sanitize(input) {
+            return input.replace(/[^a-zA-Z0-9]/g, "_");
+        }
         const vars = this.getSubgraphsVariables(name);
-        const typeSuffix = suffix.replace(/[^a-zA-Z0-9]/g, "_");
-        const typeExports = [
+        const ext = path.extname(sourcePath);
+        const suffix = sourcePath.slice(0, -ext.length);
+        let typeExports = [
             {
-                typeName: `__langgraph__${name}_${typeSuffix}`,
+                typeName: sanitize(`__langgraph__${name}_${suffix}`),
                 valueName: name,
                 graphName: name,
             },
         ];
+        const seenTypeName = new Set();
         for (const { subgraph, node, namespace } of vars) {
+            if (seenTypeName.has(subgraph.name))
+                continue;
+            seenTypeName.add(subgraph.name);
             typeExports.push({
-                typeName: `__langgraph__${namespace.join("_")}_${node}_${typeSuffix}`,
+                typeName: sanitize(`__langgraph__${namespace.join("_")}_${node}_${suffix}`),
                 valueName: subgraph.name,
                 graphName: [...namespace, node].join("|"),
             });
         }
-        const sourceFilePath = `__langgraph__source_${suffix}.mts`;
+        typeExports = typeExports.map(({ typeName, ...rest }) => ({
+            ...rest,
+            typeName: sanitize(typeName),
+        }));
+        const sourceFilePath = `__langgraph__source_${sanitize(suffix)}${ext}`;
         const sourceContents = [
             this.getText(this.sourceFile),
-            ...typeExports.map(({ typeName, valueName }) => `export type ${typeName} = typeof ${valueName}`),
-        ].join("\n\n");
-        const inferFilePath = `__langgraph__infer_${suffix}.mts`;
+            typeExports.map((type) => `export type ${type.typeName} = typeof ${type.valueName}`),
+        ];
+        const inferFilePath = `__langgraph__infer_${sanitize(suffix)}${ext}`;
+        const sourceFileImportPath = options.allowImportingTsExtensions
+            ? sourceFilePath
+            : sourceFilePath.slice(0, -ext.length) + ext.replace("ts", "js");
         const inferContents = [
-            ...typeExports.map(({ typeName }) => `import type { ${typeName}} from "./__langgraph__source_${suffix}.mts"`),
+            typeExports.map((type) => `import type { ${type.typeName} } from "./${sourceFileImportPath}"`),
             this.inferFile.getText(this.inferFile),
-            ...typeExports.flatMap(({ typeName }) => {
-                return [
-                    dedent `
-            type ${typeName}__reflect = Reflect<${typeName}>;
-            export type ${typeName}__state = Inspect<${typeName}__reflect["state"]>;
-            export type ${typeName}__update = Inspect<${typeName}__reflect["update"]>;
+            typeExports.map((type) => dedent `
+          type ${type.typeName}__reflect = Reflect<${type.typeName}>;
+          export type ${type.typeName}__state = Inspect<${type.typeName}__reflect["state"]>;
+          export type ${type.typeName}__update = Inspect<${type.typeName}__reflect["update"]>;
 
-            type ${typeName}__builder = BuilderReflect<${typeName}>;
-            export type ${typeName}__input = Inspect<FilterAny<${typeName}__builder["input"]>>;
-            export type ${typeName}__output = Inspect<FilterAny<${typeName}__builder["output"]>>;
-            export type ${typeName}__config = Inspect<FilterAny<${typeName}__builder["config"]>>;
-          `,
-                ];
-            }),
-        ].join("\n\n");
+          type ${type.typeName}__builder = BuilderReflect<${type.typeName}>;
+          export type ${type.typeName}__input = Inspect<FilterAny<${type.typeName}__builder["input"]>>;
+          export type ${type.typeName}__output = Inspect<FilterAny<${type.typeName}__builder["output"]>>;
+          export type ${type.typeName}__config = Inspect<FilterAny<${type.typeName}__builder["config"]>>;
+        `),
+        ];
         return {
-            inferFile: { fileName: inferFilePath, contents: inferContents },
-            sourceFile: { fileName: sourceFilePath, contents: sourceContents },
+            inferFile: {
+                fileName: inferFilePath,
+                contents: inferContents.flat(1).join("\n\n"),
+            },
+            sourceFile: {
+                fileName: sourceFilePath,
+                contents: sourceContents.flat(1).join("\n\n"),
+            },
             exports: typeExports,
         };
     };
@@ -268,6 +280,19 @@ export class SubgraphExtractor {
                 return inputPath.replace(/\\/g, "/");
             return inputPath;
         };
+        let compilerOptions = {
+            noEmit: true,
+            strict: true,
+            allowUnusedLabels: true,
+        };
+        // Find tsconfig.json file
+        const tsconfigPath = ts.findConfigFile(projectDirname, ts.sys.fileExists, "tsconfig.json");
+        // Read tsconfig.json file
+        if (tsconfigPath != null) {
+            const tsconfigFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+            const parsedTsconfig = ts.parseJsonConfigFileContent(tsconfigFile.config, ts.sys, path.dirname(tsconfigPath));
+            compilerOptions = { ...parsedTsconfig.options, ...compilerOptions };
+        }
         const vfsHost = vfs.createVirtualCompilerHost(system, compilerOptions, ts);
         const host = vfsHost.compilerHost;
         const targetPaths = [];
@@ -313,12 +338,10 @@ export class SubgraphExtractor {
         const researchTargets = [];
         for (const targetPath of targetPaths) {
             const extractor = new SubgraphExtractor(research, research.getSourceFile(targetPath.sourceFile), research.getSourceFile(INFER_TEMPLATE_PATH), options);
-            const suffix = path
-                .relative(projectDirname, targetPath.sourceFile)
-                .split(path.sep)
-                .join("__");
             const graphDirname = path.dirname(targetPath.sourceFile);
-            const { sourceFile, inferFile, exports } = extractor.getAugmentedSourceFile(suffix, targetPath.exportSymbol);
+            const { sourceFile, inferFile, exports } = extractor.getAugmentedSourceFile(path.relative(projectDirname, targetPath.sourceFile), targetPath.exportSymbol, {
+                allowImportingTsExtensions: compilerOptions.allowImportingTsExtensions ?? false,
+            });
             for (const { fileName, contents } of [sourceFile, inferFile]) {
                 system.writeFile(vfsPath(path.resolve(graphDirname, fileName)), contents);
             }
@@ -332,23 +355,70 @@ export class SubgraphExtractor {
             options: compilerOptions,
             host,
         });
+        // Print out any diagnostics file that were detected before emitting
+        // This may explain why sometimes the schema is invalid.
+        const allDiagnostics = ts.getPreEmitDiagnostics(extract);
+        for (const diagnostic of allDiagnostics) {
+            let message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n") + "\n";
+            if (diagnostic.file) {
+                const fileName = diagnostic.file.fileName;
+                const { line, character } = ts.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
+                const fileLoc = `(${line + 1},${character + 1})`;
+                message = `${fileName} ${fileLoc}: ${message}`;
+            }
+            console.log(message);
+        }
         const schemaGenerator = buildGenerator(extract);
-        const trySymbol = (schema, symbol) => {
+        const trySymbol = (symbol) => {
+            let schema = undefined;
             try {
-                return schema?.getSchemaForSymbol(symbol) ?? undefined;
+                schema = schemaGenerator?.getSchemaForSymbol(symbol) ?? undefined;
             }
             catch (e) {
                 console.warn(`Failed to obtain symbol "${symbol}":`, e?.message);
             }
-            return undefined;
+            if (schema == null)
+                return undefined;
+            const definitions = schema.definitions;
+            if (definitions == null)
+                return schema;
+            const toReplace = Object.keys(definitions).flatMap((key) => {
+                const replacedKey = key.includes("import(")
+                    ? key.replace(/import\(.+@langchain[\\/]core.+\)\./, "")
+                    : key;
+                if (key !== replacedKey && definitions[replacedKey] == null) {
+                    return [
+                        {
+                            source: key,
+                            target: replacedKey,
+                            sourceRef: `#/definitions/${key}`,
+                            targetRef: `#/definitions/${replacedKey}`,
+                        },
+                    ];
+                }
+                return [];
+            });
+            for (const { source, target } of toReplace) {
+                definitions[target] = definitions[source];
+                delete definitions[source];
+            }
+            const refMap = toReplace.reduce((acc, item) => {
+                acc[item.sourceRef] = item.targetRef;
+                return acc;
+            }, {});
+            return JSON.parse(JSON.stringify(schema, (_, value) => {
+                if (typeof value === "string" && refMap[value])
+                    return refMap[value];
+                return value;
+            }));
         };
         return researchTargets.map(({ exports }) => Object.fromEntries(exports.map(({ typeName, graphName }) => [
             graphName,
             {
-                state: trySymbol(schemaGenerator, `${typeName}__update`),
-                input: trySymbol(schemaGenerator, `${typeName}__input`),
-                output: trySymbol(schemaGenerator, `${typeName}__output`),
-                config: trySymbol(schemaGenerator, `${typeName}__config`),
+                state: trySymbol(`${typeName}__update`),
+                input: trySymbol(`${typeName}__input`),
+                output: trySymbol(`${typeName}__output`),
+                config: trySymbol(`${typeName}__config`),
             },
         ])));
     }

package/dist/graph/parser/schema/types.template.mts

@@ -5,14 +5,14 @@ import type {
   StateDefinition,
 } from "@langchain/langgraph";
 
-// @ts-expect-error
+// @ts-ignore
 type AnyPregel = {
   lg_is_pregel: boolean;
   stream: (...args: any[]) => any;
   invoke: (...args: any[]) => any;
 };
 
-// @ts-expect-error
+// @ts-ignore
 type AnyGraph = {
   compiled: boolean;
   compile: (...args: any[]) => any;
@@ -30,7 +30,7 @@ type Defactorify<T> = T extends (...args: any[]) => infer R
   ? Awaited<R>
   : Awaited<T>;
 
-// @ts-expect-error
+// @ts-ignore
 type Inspect<T, TDepth extends Array<0> = []> = TDepth extends [0, 0, 0]
   ? any
   : T extends unknown
@@ -51,7 +51,7 @@ type ReflectCompiled<T> = T extends { RunInput: infer S; RunOutput: infer U }
   ? { state: OutputType; update: InputType }
   : never;
 
-// @ts-expect-error
+// @ts-ignore
 type Reflect<T> = Defactorify<T> extends infer DT
   ? DT extends {
       compile(...args: any[]): infer Compiled;
@@ -74,7 +74,7 @@ type BuilderReflectCompiled<T> = T extends {
     }
   : never;
 
-// @ts-expect-error
+// @ts-ignore
 type BuilderReflect<T> = Defactorify<T> extends infer DT
   ? DT extends {
       compile(...args: any[]): infer Compiled;
@@ -83,5 +83,5 @@ type BuilderReflect<T> = Defactorify<T> extends infer DT
     : BuilderReflectCompiled<DT>
   : never;
 
-// @ts-expect-error
+// @ts-ignore
 type FilterAny<T> = 0 extends 1 & T ? never : T;

package/dist/preload.mjs

@@ -8,9 +8,18 @@ const options = JSON.parse(lastArg || "{}");
 // find the first file, as `parentURL` needs to be a valid file URL
 // if no graph found, just assume a dummy default file, which should
 // be working fine as well.
-const firstGraphFile = Object.values(options.graphs)
-    .flatMap((i) => i.split(":").at(0))
-    .at(0) || "index.mts";
+const graphFiles = Object.values(options.graphs)
+    .map((i) => {
+    if (typeof i === "string") {
+        return i.split(":").at(0);
+    }
+    else if (i && typeof i === "object" && i.path) {
+        return i.path.split(":").at(0);
+    }
+    return null;
+})
+    .filter(Boolean);
+const firstGraphFile = graphFiles.at(0) || "index.mts";
 // enforce API @langchain/langgraph resolution
 register("./graph/load.hooks.mjs", import.meta.url, {
     parentURL: "data:",

package/dist/server.d.mts

@@ -4,7 +4,16 @@ export declare const StartServerSchema: z.ZodObject<{
     nWorkers: z.ZodNumber;
     host: z.ZodString;
     cwd: z.ZodString;
-    graphs: z.ZodRecord<z.ZodString, z.ZodString>;
+    graphs: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        description?: string | undefined;
+    }, {
+        path: string;
+        description?: string | undefined;
+    }>]>>;
     auth: z.ZodOptional<z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
         disable_studio_auth: z.ZodDefault<z.ZodBoolean>;
@@ -93,7 +102,10 @@ export declare const StartServerSchema: z.ZodObject<{
     host: string;
     port: number;
     nWorkers: number;
-    graphs: Record<string, string>;
+    graphs: Record<string, string | {
+        path: string;
+        description?: string | undefined;
+    }>;
     auth?: {
         disable_studio_auth: boolean;
         path?: string | undefined;
@@ -124,7 +136,10 @@ export declare const StartServerSchema: z.ZodObject<{
     host: string;
     port: number;
     nWorkers: number;
-    graphs: Record<string, string>;
+    graphs: Record<string, string | {
+        path: string;
+        description?: string | undefined;
+    }>;
     auth?: {
         path?: string | undefined;
         disable_studio_auth?: boolean | undefined;

package/dist/server.mjs

@@ -25,7 +25,10 @@ export const StartServerSchema = z.object({
     nWorkers: z.number(),
     host: z.string(),
     cwd: z.string(),
-    graphs: z.record(z.string()),
+    graphs: z.record(z.union([
+        z.string(),
+        z.object({ path: z.string(), description: z.string().optional() }),
+    ])),
     auth: z
         .object({
         path: z.string().optional(),
@@ -79,7 +82,20 @@ export async function startServer(options) {
     // We need to do this before we load the graphs in-case the logger is obtained at top-level.
     registerSdkLogger();
     logger.info(`Registering graphs from ${options.cwd}`);
-    await registerFromEnv(options.graphs, { cwd: options.cwd });
+    let hasGraphDescriptions = false;
+    const graphPaths = Object.fromEntries(Object.entries(options.graphs).map(([graphId, rawSpec]) => {
+        if (typeof rawSpec === "string") {
+            return [graphId, rawSpec];
+        }
+        if (rawSpec.description) {
+            hasGraphDescriptions = true;
+        }
+        return [graphId, rawSpec.path];
+    }));
+    if (hasGraphDescriptions) {
+        logger.warn("A graph definition in `langgraph.json` has a `description` property. Local MCP features are not yet supported with the JS CLI and will be ignored.");
+    }
+    await registerFromEnv(graphPaths, { cwd: options.cwd });
     registerRuntimeLogFormatter((info) => {
         const config = getConfig();
         if (config == null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -52,7 +52,7 @@
     "@babel/code-frame": "^7.26.2",
     "@hono/node-server": "^1.12.0",
     "@hono/zod-validator": "^0.2.2",
-    "@langchain/langgraph-ui": "0.0.55",
+    "@langchain/langgraph-ui": "0.0.57",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
@@ -84,7 +84,7 @@
   },
   "devDependencies": {
     "@langchain/core": "^0.3.59",
-    "@langchain/langgraph": "0.4.1",
+    "@langchain/langgraph": "0.4.3",
     "@langchain/langgraph-checkpoint": "0.1.0",
     "@langchain/langgraph-sdk": "0.0.105",
     "@types/babel__code-frame": "^7.0.6",