@langchain/langgraph-api 0.0.57 → 0.0.58

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @langchain/langgraph-api
 
+## 0.0.58
+
+### Patch Changes
+
+- f65f619: fix(api): send Content-Location header for stateless runs
+- c857357: feat(api): harden embed server, implement missing endpoints needed for interrupts
+  - @langchain/langgraph-ui@0.0.58
+
 ## 0.0.57
 
 ### Patch Changes

package/dist/api/runs.mjs

@@ -143,6 +143,7 @@ api.post("/runs/stream", zValidator("json", schemas.RunCreate), async (c) => {
         auth: c.var.auth,
         headers: c.req.raw.headers,
     });
+    c.header("Content-Location", `/runs/${run.run_id}`);
     return streamSSE(c, async (stream) => {
         const cancelOnDisconnect = payload.on_disconnect === "cancel"
             ? getDisconnectAbortSignal(c, stream)
@@ -166,6 +167,7 @@ api.get("/runs/:run_id/stream", zValidator("param", z.object({ run_id: z.string(
     const { run_id } = c.req.valid("param");
     const query = c.req.valid("query");
     const lastEventId = c.req.header("Last-Event-ID") || undefined;
+    c.header("Content-Location", `/runs/${run_id}`);
     return streamSSE(c, async (stream) => {
         const cancelOnDisconnect = query.cancel_on_disconnect
             ? getDisconnectAbortSignal(c, stream)
@@ -187,6 +189,7 @@ api.post("/runs/wait", zValidator("json", schemas.RunCreate), async (c) => {
         auth: c.var.auth,
         headers: c.req.raw.headers,
     });
+    c.header("Content-Location", `/runs/${run.run_id}`);
     return waitKeepAlive(c, Runs.wait(run.run_id, undefined, c.var.auth));
 });
 api.post("/runs", zValidator("json", schemas.RunCreate), async (c) => {
@@ -196,6 +199,7 @@ api.post("/runs", zValidator("json", schemas.RunCreate), async (c) => {
         auth: c.var.auth,
         headers: c.req.raw.headers,
     });
+    c.header("Content-Location", `/runs/${run.run_id}`);
     return jsonExtra(c, run);
 });
 api.post("/runs/batch", zValidator("json", schemas.RunBatchCreate), async (c) => {

package/dist/api/threads.mjs

@@ -51,17 +51,7 @@ api.get("/threads/:thread_id/state", zValidator("param", z.object({ thread_id: z
     const state = stateSnapshotToThreadState(await Threads.State.get({ configurable: { thread_id } }, { subgraphs }, c.var.auth));
     return jsonExtra(c, state);
 });
-api.post("/threads/:thread_id/state", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", z.object({
-    values: z
-        .union([
-        z.record(z.string(), z.unknown()),
-        z.array(z.record(z.string(), z.unknown())),
-    ])
-        .nullish(),
-    as_node: z.string().optional(),
-    checkpoint_id: z.string().optional(),
-    checkpoint: schemas.CheckpointSchema.nullish(),
-})), async (c) => {
+api.post("/threads/:thread_id/state", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.ThreadStateUpdate), async (c) => {
     // Update Thread State
     const { thread_id } = c.req.valid("param");
     const payload = c.req.valid("json");

package/dist/experimental/embed.d.mts

@@ -6,15 +6,31 @@ interface Thread {
     thread_id: string;
     metadata: Metadata;
 }
-interface ThreadSaver {
+/**
+ * Interface for storing and retrieving threads used by `createEmbedServer`.
+ * @experimental Does not follow semver.
+ */
+export interface ThreadSaver {
     get: (id: string) => Promise<Thread>;
-    put: (id: string, options: {
+    set: (id: string, options: {
+        kind: "put" | "patch";
         metadata?: Metadata;
-    }) => Promise<void>;
+    }) => Promise<Thread>;
     delete: (id: string) => Promise<void>;
+    search?: (options: {
+        metadata?: Metadata;
+        limit: number;
+        offset: number;
+        sortBy: "created_at" | "updated_at";
+        sortOrder: "asc" | "desc";
+    }) => AsyncGenerator<{
+        thread: Thread;
+        total: number;
+    }>;
 }
 /**
- * Attach LangGraph Platform-esque routes to a given Hono instance.
+ * Create a Hono server with a subset of LangGraph Platform routes.
+ *
  * @experimental Does not follow semver.
  */
 export declare function createEmbedServer(options: {

package/dist/experimental/embed.mjs

@@ -5,18 +5,20 @@ import { v4 as uuidv4 } from "uuid";
 import * as schemas from "../schemas.mjs";
 import { z } from "zod";
 import { streamState } from "../stream.mjs";
-import { serialiseAsDict } from "../utils/serde.mjs";
+import { serialiseAsDict, serializeError } from "../utils/serde.mjs";
 import { getDisconnectAbortSignal, jsonExtra } from "../utils/hono.mjs";
 import { stateSnapshotToThreadState } from "../state.mjs";
 import { ensureContentType } from "../http/middleware.mjs";
 function createStubRun(threadId, payload) {
     const now = new Date();
     const runId = uuidv4();
-    const streamMode = Array.isArray(payload.stream_mode)
+    let streamMode = Array.isArray(payload.stream_mode)
         ? payload.stream_mode
         : payload.stream_mode
             ? [payload.stream_mode]
             : undefined;
+    if (streamMode == null || streamMode.length === 0)
+        streamMode = ["values"];
     const config = Object.assign({}, payload.config ?? {}, {
         configurable: {
             run_id: runId,
@@ -44,6 +46,7 @@ function createStubRun(threadId, payload) {
             input: payload.input,
             command: payload.command,
             config,
+            context: payload.context,
             stream_mode: streamMode,
             interrupt_before: payload.interrupt_before,
             interrupt_after: payload.interrupt_after,
@@ -57,7 +60,8 @@ function createStubRun(threadId, payload) {
     };
 }
 /**
- * Attach LangGraph Platform-esque routes to a given Hono instance.
+ * Create a Hono server with a subset of LangGraph Platform routes.
+ *
  * @experimental Does not follow semver.
  */
 export function createEmbedServer(options) {
@@ -70,23 +74,58 @@ export function createEmbedServer(options) {
     const api = new Hono();
     api.use(ensureContentType());
     api.post("/threads", zValidator("json", schemas.ThreadCreate), async (c) => {
-        // create a new threaad
+        // create a new thread
         const payload = c.req.valid("json");
         const threadId = payload.thread_id || uuidv4();
-        await options.threads.put(threadId, payload);
-        return jsonExtra(c, { thread_id: threadId });
+        return jsonExtra(c, await options.threads.set(threadId, {
+            kind: "put",
+            metadata: payload.metadata,
+        }));
     });
     api.get("/threads/:thread_id", zValidator("param", z.object({ thread_id: z.string().uuid() })), async (c) => {
         // Get Thread
         const { thread_id } = c.req.valid("param");
-        const thread = await options.threads.get(thread_id);
-        return jsonExtra(c, thread);
+        return jsonExtra(c, await options.threads.get(thread_id));
+    });
+    api.patch("/threads/:thread_id", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.ThreadCreate), async (c) => {
+        // Update Thread
+        const { thread_id } = c.req.valid("param");
+        const payload = c.req.valid("json");
+        return jsonExtra(c, await options.threads.set(thread_id, {
+            kind: "patch",
+            metadata: payload.metadata,
+        }));
     });
     api.delete("/threads/:thread_id", zValidator("param", z.object({ thread_id: z.string().uuid() })), async (c) => {
+        // Delete Thread
         const { thread_id } = c.req.valid("param");
         await options.threads.delete(thread_id);
         return new Response(null, { status: 204 });
     });
+    api.post("/threads/search", zValidator("json", schemas.ThreadSearchRequest), async (c) => {
+        const payload = c.req.valid("json");
+        const result = [];
+        if (!options.threads.search)
+            return c.json({ error: "Threads search not implemented" }, 422);
+        const sortBy = payload.sort_by === "created_at" || payload.sort_by === "updated_at"
+            ? payload.sort_by
+            : "created_at";
+        let total = 0;
+        for await (const item of options.threads.search({
+            metadata: payload.metadata,
+            limit: payload.limit ?? 10,
+            offset: payload.offset ?? 0,
+            sortBy,
+            sortOrder: payload.sort_order ?? "desc",
+        })) {
+            result.push(item.thread);
+            // Only set total if it's the first item
+            if (total === 0)
+                total = item.total;
+        }
+        c.res.headers.set("X-Pagination-Total", total.toString());
+        return jsonExtra(c, result);
+    });
     api.get("/threads/:thread_id/state", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("query", z.object({ subgraphs: schemas.coercedBoolean.optional() })), async (c) => {
         // Get Latest Thread State
         const { thread_id } = c.req.valid("param");
@@ -109,6 +148,57 @@ export function createEmbedServer(options) {
         const result = await graph.getState(config, { subgraphs });
         return jsonExtra(c, stateSnapshotToThreadState(result));
     });
+    api.post("/threads/:thread_id/state", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.ThreadStateUpdate), async (c) => {
+        // Update Thread State
+        const { thread_id } = c.req.valid("param");
+        const payload = c.req.valid("json");
+        const config = { configurable: { thread_id } };
+        config.configurable ??= {};
+        if (payload.checkpoint_id) {
+            config.configurable.checkpoint_id = payload.checkpoint_id;
+        }
+        if (payload.checkpoint) {
+            Object.assign(config.configurable, payload.checkpoint);
+        }
+        const thread = await options.threads.get(thread_id);
+        const graphId = thread.metadata?.graph_id;
+        const graph = graphId ? await getGraph(graphId) : undefined;
+        if (graph == null)
+            return c.json({ error: "Graph not found" }, 404);
+        const result = await graph.updateState(config, payload.values, payload.as_node);
+        return jsonExtra(c, { checkpoint: result.configurable });
+    });
+    // get thread state at checkpoint
+    api.get("/threads/:thread_id/state/:checkpoint_id", zValidator("param", z.object({
+        thread_id: z.string().uuid(),
+        checkpoint_id: z.string().uuid(),
+    })), zValidator("query", z.object({ subgraphs: schemas.coercedBoolean.optional() })), async (c) => {
+        // Get Thread State At Checkpoint
+        const { thread_id, checkpoint_id } = c.req.valid("param");
+        const { subgraphs } = c.req.valid("query");
+        const thread = await options.threads.get(thread_id);
+        const graphId = thread.metadata?.graph_id;
+        const graph = graphId ? await getGraph(graphId) : undefined;
+        if (graph == null)
+            return c.json({ error: "Graph not found" }, 404);
+        const result = await graph.getState({ configurable: { thread_id, checkpoint_id } }, { subgraphs });
+        return jsonExtra(c, stateSnapshotToThreadState(result));
+    });
+    api.post("/threads/:thread_id/state/checkpoint", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", z.object({
+        subgraphs: schemas.coercedBoolean.optional(),
+        checkpoint: schemas.CheckpointSchema.nullish(),
+    })), async (c) => {
+        // Get Thread State At Checkpoint post
+        const { thread_id } = c.req.valid("param");
+        const { checkpoint, subgraphs } = c.req.valid("json");
+        const thread = await options.threads.get(thread_id);
+        const graphId = thread.metadata?.graph_id;
+        const graph = graphId ? await getGraph(graphId) : undefined;
+        if (graph == null)
+            return c.json({ error: "Graph not found" }, 404);
+        const result = await graph.getState({ configurable: { thread_id, ...checkpoint } }, { subgraphs });
+        return jsonExtra(c, stateSnapshotToThreadState(result));
+    });
     api.post("/threads/:thread_id/history", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.ThreadHistoryRequest), async (c) => {
         // Get Thread History Post
         const { thread_id } = c.req.valid("param");
@@ -134,26 +224,35 @@ export function createEmbedServer(options) {
     });
     api.post("/threads/:thread_id/runs/stream", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.RunCreate), async (c) => {
         // Stream Run
+        const { thread_id } = c.req.valid("param");
+        const payload = c.req.valid("json");
+        const thread = await options.threads.get(thread_id);
+        if (thread == null)
+            return c.json({ error: "Thread not found" }, 404);
         return streamSSE(c, async (stream) => {
-            const { thread_id } = c.req.valid("param");
-            const payload = c.req.valid("json");
             const signal = getDisconnectAbortSignal(c, stream);
             const run = createStubRun(thread_id, payload);
-            // update thread with new graph_id
-            const thread = await options.threads.get(thread_id);
-            await options.threads.put(thread_id, {
+            await options.threads.set(thread_id, {
+                kind: "patch",
                 metadata: {
-                    ...thread.metadata,
                     graph_id: payload.assistant_id,
                     assistant_id: payload.assistant_id,
                 },
             });
-            for await (const { event, data } of streamState(run, {
-                attempt: 1,
-                getGraph,
-                signal,
-            })) {
-                await stream.writeSSE({ data: serialiseAsDict(data), event });
+            try {
+                for await (const { event, data } of streamState(run, {
+                    attempt: 1,
+                    getGraph,
+                    signal,
+                })) {
+                    await stream.writeSSE({ data: serialiseAsDict(data), event });
+                }
+            }
+            catch (error) {
+                await stream.writeSSE({
+                    data: serialiseAsDict(serializeError(error)),
+                    event: "error",
+                });
             }
         });
     });
@@ -163,7 +262,8 @@ export function createEmbedServer(options) {
             const payload = c.req.valid("json");
             const signal = getDisconnectAbortSignal(c, stream);
             const threadId = uuidv4();
-            await options.threads.put(threadId, {
+            await options.threads.set(threadId, {
+                kind: "put",
                 metadata: {
                     graph_id: payload.assistant_id,
                     assistant_id: payload.assistant_id,
@@ -171,12 +271,20 @@ export function createEmbedServer(options) {
             });
             try {
                 const run = createStubRun(threadId, payload);
-                for await (const { event, data } of streamState(run, {
-                    attempt: 1,
-                    getGraph,
-                    signal,
-                })) {
-                    await stream.writeSSE({ data: serialiseAsDict(data), event });
+                try {
+                    for await (const { event, data } of streamState(run, {
+                        attempt: 1,
+                        getGraph,
+                        signal,
+                    })) {
+                        await stream.writeSSE({ data: serialiseAsDict(data), event });
+                    }
+                }
+                catch (error) {
+                    await stream.writeSSE({
+                        data: serialiseAsDict(serializeError(error)),
+                        event: "error",
+                    });
                 }
             }
             finally {
@@ -184,5 +292,8 @@ export function createEmbedServer(options) {
             }
         });
     });
+    api.notFound((c) => {
+        return c.json({ error: `${c.req.method} ${c.req.path} not implemented` }, 404);
+    });
     return api;
 }

package/dist/graph/load.d.mts

@@ -8,9 +8,9 @@ export declare const NAMESPACE_GRAPH: Uint8Array<ArrayBufferLike>;
 export declare const getAssistantId: (graphId: string) => string;
 export declare function registerFromEnv(specs: Record<string, string>, options: {
     cwd: string;
-}): Promise<(CompiledGraph<string, any, any, Record<string, any>, any, any> | CompiledGraphFactory<string>)[]>;
+}): Promise<(CompiledGraph<string, any, any, Record<string, any>, any, any, unknown> | CompiledGraphFactory<string>)[]>;
 export declare function getGraph(graphId: string, config: LangGraphRunnableConfig | undefined, options?: {
     checkpointer?: BaseCheckpointSaver | null;
     store?: BaseStore;
-}): Promise<CompiledGraph<string, any, any, Record<string, any>, any, any>>;
+}): Promise<CompiledGraph<string, any, any, Record<string, any>, any, any, unknown>>;
 export declare function getCachedStaticGraphSchema(graphId: string): Promise<Record<string, GraphSchema>>;

package/dist/schemas.d.mts

@@ -1343,16 +1343,39 @@ export declare const ThreadStateSearch: z.ZodObject<{
     before?: string | undefined;
 }>;
 export declare const ThreadStateUpdate: z.ZodObject<{
-    values: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>, "many">, z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>, z.ZodNull]>>;
-    checkpoint_id: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">]>>>;
     as_node: z.ZodOptional<z.ZodString>;
+    checkpoint_id: z.ZodOptional<z.ZodString>;
+    checkpoint: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        checkpoint_id: z.ZodOptional<z.ZodString>;
+        checkpoint_ns: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        checkpoint_map: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, "strip", z.ZodTypeAny, {
+        checkpoint_ns?: string | null | undefined;
+        checkpoint_id?: string | undefined;
+        checkpoint_map?: Record<string, unknown> | null | undefined;
+    }, {
+        checkpoint_ns?: string | null | undefined;
+        checkpoint_id?: string | undefined;
+        checkpoint_map?: Record<string, unknown> | null | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
-    values?: z.objectOutputType<{}, z.ZodAny, "strip">[] | z.objectOutputType<{}, z.ZodAny, "strip"> | null | undefined;
+    values?: Record<string, unknown> | Record<string, unknown>[] | null | undefined;
     checkpoint_id?: string | undefined;
+    checkpoint?: {
+        checkpoint_ns?: string | null | undefined;
+        checkpoint_id?: string | undefined;
+        checkpoint_map?: Record<string, unknown> | null | undefined;
+    } | null | undefined;
     as_node?: string | undefined;
 }, {
-    values?: z.objectInputType<{}, z.ZodAny, "strip">[] | z.objectInputType<{}, z.ZodAny, "strip"> | null | undefined;
+    values?: Record<string, unknown> | Record<string, unknown>[] | null | undefined;
     checkpoint_id?: string | undefined;
+    checkpoint?: {
+        checkpoint_ns?: string | null | undefined;
+        checkpoint_id?: string | undefined;
+        checkpoint_map?: Record<string, unknown> | null | undefined;
+    } | null | undefined;
     as_node?: string | undefined;
 }>;
 export declare const ThreadHistoryRequest: z.ZodObject<{

package/dist/schemas.mjs

@@ -387,13 +387,13 @@ export const ThreadStateUpdate = z
     .object({
     values: z
         .union([
-        z.array(z.object({}).catchall(z.any())),
-        z.object({}).catchall(z.any()),
-        z.null(),
+        z.record(z.string(), z.unknown()),
+        z.array(z.record(z.string(), z.unknown())),
     ])
-        .optional(),
-    checkpoint_id: z.string().optional(),
+        .nullish(),
     as_node: z.string().optional(),
+    checkpoint_id: z.string().optional(),
+    checkpoint: CheckpointSchema.nullish(),
 })
     .describe("Payload for adding state to a thread.");
 export const ThreadHistoryRequest = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "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.57",
+    "@langchain/langgraph-ui": "0.0.58",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
@@ -84,9 +84,9 @@
   },
   "devDependencies": {
     "@langchain/core": "^0.3.59",
-    "@langchain/langgraph": "0.4.3",
+    "@langchain/langgraph": "0.4.4",
     "@langchain/langgraph-checkpoint": "0.1.0",
-    "@langchain/langgraph-sdk": "0.0.105",
+    "@langchain/langgraph-sdk": "0.0.107",
     "@types/babel__code-frame": "^7.0.6",
     "@types/node": "^18.15.11",
     "@types/react": "^19.0.8",