@langchain/langgraph-api 1.1.17 → 1.2.1

package/dist/experimental/embed/threads.mjs

@@ -0,0 +1,151 @@
+import { zValidator } from "@hono/zod-validator";
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod/v3";
+import * as schemas from "../../schemas.mjs";
+import { jsonExtra } from "../../utils/hono.mjs";
+import { stateSnapshotToThreadState } from "../../state.mjs";
+/**
+ * Register thread CRUD and state routes on an embed server Hono app.
+ *
+ * @experimental Does not follow semver.
+ */
+export function registerThreadRoutes(api, context) {
+    api.post("/threads", zValidator("json", schemas.ThreadCreate), async (c) => {
+        const payload = c.req.valid("json");
+        const threadId = payload.thread_id || uuidv7();
+        return jsonExtra(c, await context.threads.set(threadId, {
+            kind: "put",
+            metadata: payload.metadata,
+        }));
+    });
+    api.get("/threads/:thread_id", zValidator("param", z.object({ thread_id: z.string().uuid() })), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        return jsonExtra(c, await context.threads.get(thread_id));
+    });
+    api.patch("/threads/:thread_id", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.ThreadCreate), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        const payload = c.req.valid("json");
+        return jsonExtra(c, await context.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) => {
+        const { thread_id } = c.req.valid("param");
+        await context.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 (!context.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 context.threads.search({
+            metadata: payload.metadata,
+            limit: payload.limit ?? 10,
+            offset: payload.offset ?? 0,
+            sortBy,
+            sortOrder: payload.sort_order ?? "desc",
+        })) {
+            result.push(item.thread);
+            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) => {
+        const { thread_id } = c.req.valid("param");
+        const { subgraphs } = c.req.valid("query");
+        const thread = await context.threads.get(thread_id);
+        const graphId = thread?.metadata?.graph_id;
+        const graph = graphId ? await context.getGraph(graphId) : undefined;
+        if (graph == null) {
+            return jsonExtra(c, stateSnapshotToThreadState({
+                values: {},
+                next: [],
+                config: {},
+                metadata: undefined,
+                createdAt: undefined,
+                parentConfig: undefined,
+                tasks: [],
+            }));
+        }
+        const config = { configurable: { thread_id } };
+        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) => {
+        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 context.threads.get(thread_id);
+        const graphId = thread?.metadata?.graph_id;
+        const graph = graphId ? await context.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 });
+    });
+    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) => {
+        const { thread_id, checkpoint_id } = c.req.valid("param");
+        const { subgraphs } = c.req.valid("query");
+        const thread = await context.threads.get(thread_id);
+        const graphId = thread?.metadata?.graph_id;
+        const graph = graphId ? await context.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) => {
+        const { thread_id } = c.req.valid("param");
+        const { checkpoint, subgraphs } = c.req.valid("json");
+        const thread = await context.threads.get(thread_id);
+        const graphId = thread?.metadata?.graph_id;
+        const graph = graphId ? await context.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) => {
+        const { thread_id } = c.req.valid("param");
+        const { limit, before, metadata, checkpoint } = c.req.valid("json");
+        const thread = await context.threads.get(thread_id);
+        const graphId = thread?.metadata?.graph_id;
+        const graph = graphId ? await context.getGraph(graphId) : undefined;
+        if (graph == null)
+            return jsonExtra(c, []);
+        const config = { configurable: { thread_id, ...checkpoint } };
+        const result = [];
+        const beforeConfig = typeof before === "string"
+            ? { configurable: { checkpoint_id: before } }
+            : before;
+        for await (const state of graph.getStateHistory(config, {
+            limit,
+            before: beforeConfig,
+            filter: metadata,
+        })) {
+            result.push(stateSnapshotToThreadState(state));
+        }
+        return jsonExtra(c, result);
+    });
+}

package/dist/experimental/embed/types.d.mts

@@ -0,0 +1,77 @@
+import type { BaseCheckpointSaver, BaseStore, Pregel } from "@langchain/langgraph";
+import type { Metadata, Run } from "../../storage/types.mjs";
+import type { ProtocolEvent } from "../../protocol/types.mjs";
+import type { RunProtocolSession } from "../../protocol/session/index.mjs";
+export type AnyPregel = Pregel<any, any, any, any, any>;
+/**
+ * Shared context passed to each embed route module so that route handlers
+ * can access graphs, thread storage, and the checkpointer without closures.
+ */
+export interface EmbedRouteContext {
+    graph: Record<string, AnyPregel>;
+    threads: ThreadSaver;
+    checkpointer: BaseCheckpointSaver;
+    store?: BaseStore;
+    getGraph: (graphId: string) => Promise<AnyPregel>;
+}
+export interface Thread {
+    thread_id: string;
+    metadata: Metadata;
+}
+/**
+ * Interface for storing and retrieving threads used by `createEmbedServer`.
+ * @experimental Does not follow semver.
+ */
+export interface ThreadSaver {
+    get: (id: string) => Promise<Thread>;
+    set: (id: string, options: {
+        kind: "put" | "patch";
+        metadata?: Metadata;
+    }) => 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;
+    }>;
+}
+export type RunStatus = "pending" | "running" | "success" | "error" | "interrupted";
+/** Per-thread run queue state for enqueue support. */
+export interface ThreadRunState {
+    activeRunId: string | null;
+    pendingRuns: Run[];
+}
+/**
+ * In-memory record for an active embed thread connection.
+ */
+export interface EmbedThread {
+    threadId: string;
+    assistantId?: string;
+    seq: number;
+    runSession?: RunProtocolSession;
+    /** Per-connection filtered event sinks (SSE). */
+    eventSinks: Map<string, {
+        id: string;
+        filter: {
+            channels: Set<string>;
+            namespaces?: string[][];
+            depth?: number;
+            since?: number;
+        };
+        send: (message: ProtocolEvent) => Promise<void> | void;
+        pendingReplay?: boolean;
+        /**
+         * Bypass the sink filter when true. Used for WebSocket transports
+         * which deliver the full event stream to the connected client and
+         * let the client filter locally.
+         */
+        unfiltered?: boolean;
+    }>;
+    queuedEvents: ProtocolEvent[];
+    currentRun?: Run;
+}

package/dist/experimental/embed/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/experimental/embed/utils.d.mts

@@ -0,0 +1,29 @@
+import { z } from "zod/v3";
+import type { MultitaskStrategy, Run } from "../../storage/types.mjs";
+import * as schemas from "../../schemas.mjs";
+import type { RunStatus } from "./types.mjs";
+export declare const ProtocolCommandSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    id: number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>;
+export declare const ThreadIdSchema: z.ZodObject<{
+    thread_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    thread_id: string;
+}, {
+    thread_id: string;
+}>;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare function createStubRun(threadId: string, payload: z.infer<typeof schemas.RunCreate>, overrides?: {
+    status?: RunStatus;
+    multitask_strategy?: MultitaskStrategy;
+}): Run;

package/dist/experimental/embed/utils.mjs

@@ -0,0 +1,62 @@
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod/v3";
+export const ProtocolCommandSchema = z.object({
+    id: z.number().int().nonnegative(),
+    method: z.string(),
+    params: z.record(z.unknown()).optional(),
+});
+export const ThreadIdSchema = z.object({ thread_id: z.string() });
+export const isRecord = (value) => typeof value === "object" && value !== null;
+export function createStubRun(threadId, payload, overrides) {
+    const now = new Date();
+    const runId = uuidv7();
+    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: {
+            ...payload.config?.configurable,
+            run_id: runId,
+            thread_id: threadId,
+            graph_id: payload.assistant_id,
+            ...(payload.checkpoint_id
+                ? { checkpoint_id: payload.checkpoint_id }
+                : null),
+            ...payload.checkpoint,
+            ...(payload.langsmith_tracer
+                ? {
+                    langsmith_project: payload.langsmith_tracer.project_name,
+                    langsmith_example_id: payload.langsmith_tracer.example_id,
+                }
+                : null),
+        },
+    }, { metadata: payload.metadata ?? {} });
+    return {
+        run_id: runId,
+        thread_id: threadId,
+        assistant_id: payload.assistant_id,
+        metadata: payload.metadata ?? {},
+        status: overrides?.status ?? "running",
+        kwargs: {
+            input: payload.input,
+            command: payload.command,
+            config,
+            context: payload.context,
+            stream_mode: streamMode,
+            interrupt_before: payload.interrupt_before,
+            interrupt_after: payload.interrupt_after,
+            feedback_keys: payload.feedback_keys,
+            subgraphs: payload.stream_subgraphs,
+            temporary: false,
+        },
+        multitask_strategy: (overrides?.multitask_strategy ??
+            payload.multitask_strategy ??
+            "reject"),
+        created_at: now,
+        updated_at: now,
+    };
+}

package/dist/experimental/embed.d.mts

@@ -1,42 +1,22 @@
-import type { BaseCheckpointSaver, BaseStore, Pregel } from "@langchain/langgraph";
+import type { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph";
 import { Hono } from "hono";
-import type { Metadata } from "../storage/types.mjs";
-type AnyPregel = Pregel<any, any, any, any, any>;
-interface Thread {
-    thread_id: string;
-    metadata: Metadata;
-}
-/**
- * Interface for storing and retrieving threads used by `createEmbedServer`.
- * @experimental Does not follow semver.
- */
-export interface ThreadSaver {
-    get: (id: string) => Promise<Thread>;
-    set: (id: string, options: {
-        kind: "put" | "patch";
-        metadata?: Metadata;
-    }) => 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;
-    }>;
-}
+import type { UpgradeWebSocket } from "hono/ws";
+import type { AnyPregel } from "./embed/types.mjs";
+export type { ThreadSaver } from "./embed/types.mjs";
 /**
  * Create a Hono server with a subset of LangGraph Platform routes.
  *
+ * Pass `upgradeWebSocket` to enable the WebSocket protocol transport
+ * on `GET /threads/:thread_id/stream/events`. Create it with `@hono/node-ws`'s
+ * `createNodeWebSocket({ app })` and make sure to call `injectWebSocket`
+ * on the underlying HTTP server.
+ *
  * @experimental Does not follow semver.
  */
 export declare function createEmbedServer(options: {
     graph: Record<string, AnyPregel>;
-    threads: ThreadSaver;
+    threads: import("./embed/types.mjs").ThreadSaver;
     checkpointer: BaseCheckpointSaver;
     store?: BaseStore;
+    upgradeWebSocket?: UpgradeWebSocket;
 }): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-export {};