@langchain/langgraph-api 1.1.17 → 1.2.0

package/dist/experimental/embed.mjs

@@ -1,417 +1,37 @@
 import { Hono } from "hono";
-import { zValidator } from "@hono/zod-validator";
-import { streamSSE } from "hono/streaming";
-import { v7 as uuidv7 } from "uuid";
-import * as schemas from "../schemas.mjs";
-import { z } from "zod/v3";
-import { streamState } from "../stream.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, 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: {
-            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,
-    };
-}
+import { registerThreadRoutes } from "./embed/threads.mjs";
+import { registerRunRoutes } from "./embed/runs.mjs";
+import { registerProtocolRoutes } from "./embed/protocol.mjs";
 /**
  * Create a Hono server with a subset of LangGraph Platform routes.
  *
+ * Pass `upgradeWebSocket` to enable the WebSocket protocol transport
+ * on `GET /v2/threads/:thread_id/stream`. 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 function createEmbedServer(options) {
-    const threadRunState = new Map();
-    function getThreadState(threadId) {
-        let state = threadRunState.get(threadId);
-        if (!state) {
-            state = { activeRunId: null, pendingRuns: [] };
-            threadRunState.set(threadId, state);
-        }
-        return state;
-    }
-    async function waitForRunReady(threadId, runId, signal) {
-        const state = getThreadState(threadId);
-        const run = state.pendingRuns.find((r) => r.run_id === runId);
-        if (!run)
-            return null;
-        while (true) {
-            if (signal?.aborted) {
-                throw new DOMException("Aborted", "AbortError");
-            }
-            const isHead = state.pendingRuns[0]?.run_id === runId;
-            const noActive = !state.activeRunId;
-            if (isHead && noActive)
-                break;
-            await new Promise((r) => setTimeout(r, 50));
-        }
-        return run;
-    }
     async function getGraph(graphId) {
-        const targetGraph = options.graph[graphId];
+        const targetGraph = await options.graph[graphId];
         targetGraph.store = options.store;
         targetGraph.checkpointer = options.checkpointer;
         return targetGraph;
     }
+    const context = {
+        graph: options.graph,
+        threads: options.threads,
+        checkpointer: options.checkpointer,
+        store: options.store,
+        getGraph,
+    };
     const api = new Hono();
     api.use(ensureContentType());
-    api.post("/threads", zValidator("json", schemas.ThreadCreate), async (c) => {
-        // create a new thread
-        const payload = c.req.valid("json");
-        const threadId = payload.thread_id || uuidv7();
-        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");
-        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");
-        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 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) => {
-        // 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");
-        const { limit, before, metadata, checkpoint } = 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 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);
-    });
-    api.post("/threads/:thread_id/runs", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.RunCreate), async (c) => {
-        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);
-        const state = getThreadState(thread_id);
-        const multitaskStrategy = payload.multitask_strategy ?? "reject";
-        const shouldEnqueue = multitaskStrategy === "enqueue" && state.activeRunId != null;
-        const run = createStubRun(thread_id, payload, {
-            status: shouldEnqueue ? "pending" : "running",
-            multitask_strategy: multitaskStrategy,
-        });
-        state.pendingRuns.push(run);
-        c.header("Content-Location", `/threads/${thread_id}/runs/${run.run_id}`);
-        return jsonExtra(c, run);
-    });
-    api.get("/threads/:thread_id/runs/:run_id/stream", zValidator("param", z.object({
-        thread_id: z.string().uuid(),
-        run_id: z.string().uuid(),
-    })), async (c) => {
-        const { thread_id, run_id } = c.req.valid("param");
-        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 signal = getDisconnectAbortSignal(c, stream);
-            const state = getThreadState(thread_id);
-            try {
-                const run = await waitForRunReady(thread_id, run_id, signal);
-                if (!run) {
-                    await stream.writeSSE({
-                        data: serialiseAsDict({ error: "Run not found" }),
-                        event: "error",
-                    });
-                    return;
-                }
-                const idx = state.pendingRuns.findIndex((r) => r.run_id === run_id);
-                if (idx >= 0)
-                    state.pendingRuns.splice(idx, 1);
-                state.activeRunId = run_id;
-                run.status = "running";
-                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 {
-                    if (state.activeRunId === run_id) {
-                        state.activeRunId = null;
-                    }
-                }
-            }
-            catch (err) {
-                if (err instanceof DOMException && err.name === "AbortError") {
-                    return;
-                }
-                throw err;
-            }
-        });
-    });
-    api.post("/threads/:thread_id/runs/:run_id/cancel", zValidator("param", z.object({
-        thread_id: z.string().uuid(),
-        run_id: z.string().uuid(),
-    })), async (c) => {
-        const { thread_id, run_id } = c.req.valid("param");
-        const state = getThreadState(thread_id);
-        const idx = state.pendingRuns.findIndex((r) => r.run_id === run_id);
-        if (idx >= 0) {
-            state.pendingRuns.splice(idx, 1);
-        }
-        return new Response(null, { status: 204 });
-    });
-    api.post("/threads/:thread_id/runs/stream", zValidator("param", z.object({ thread_id: z.string().uuid() })), zValidator("json", schemas.RunCreate), async (c) => {
-        // Stream Run (create + stream in one request)
-        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);
-        const state = getThreadState(thread_id);
-        const run = createStubRun(thread_id, payload);
-        c.header("Content-Location", `/threads/${thread_id}/runs/${run.run_id}`);
-        return streamSSE(c, async (stream) => {
-            const signal = getDisconnectAbortSignal(c, stream);
-            state.activeRunId = run.run_id;
-            await options.threads.set(thread_id, {
-                kind: "patch",
-                metadata: {
-                    graph_id: payload.assistant_id,
-                    assistant_id: payload.assistant_id,
-                },
-            });
-            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 {
-                if (state.activeRunId === run.run_id) {
-                    state.activeRunId = null;
-                }
-            }
-        });
-    });
-    api.post("/runs/stream", zValidator("json", schemas.RunCreate), async (c) => {
-        // Stream Stateless Run
-        const payload = c.req.valid("json");
-        const threadId = uuidv7();
-        const run = createStubRun(threadId, payload);
-        c.header("Content-Location", `/threads/${threadId}/runs/${run.run_id}`);
-        return streamSSE(c, async (stream) => {
-            const signal = getDisconnectAbortSignal(c, stream);
-            await options.threads.set(threadId, {
-                kind: "put",
-                metadata: {
-                    graph_id: payload.assistant_id,
-                    assistant_id: payload.assistant_id,
-                },
-            });
-            try {
-                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 {
-                await options.threads.delete(threadId);
-            }
-        });
-    });
+    registerThreadRoutes(api, context);
+    registerRunRoutes(api, context);
+    registerProtocolRoutes(api, context, options.upgradeWebSocket);
     api.notFound((c) => {
         return c.json({ error: `${c.req.method} ${c.req.path} not implemented` }, 404);
     });

package/dist/graph/load.d.mts

@@ -9,11 +9,11 @@ export declare const NAMESPACE_GRAPH: Uint8Array<ArrayBufferLike>;
 export declare const getAssistantId: (graphId: string) => string;
 export declare function registerFromEnv(assistants: AssistantsRepo, specs: Record<string, string>, options: {
     cwd: string;
-}): Promise<(CompiledGraph<string, any, any, Record<string, any>, any, any, unknown, unknown, any> | CompiledGraphFactory<string>)[]>;
+}): Promise<(CompiledGraph<string, any, any, Record<string, any>, any, any, unknown, unknown, any, []> | 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, unknown, unknown, any>>;
+}): Promise<CompiledGraph<string, any, any, Record<string, any>, any, any, unknown, unknown, any, []>>;
 export declare function assertGraphExists(graphId: string): void;
 export declare function getGraphKeys(): string[];
 export declare function getCachedStaticGraphSchema(graphId: string): Promise<Record<string, GraphSchema>>;

package/dist/graph/load.utils.mjs

@@ -31,9 +31,19 @@ export async function resolveGraph(spec, options) {
             throw new Error("Failed to load graph: graph is nullush");
         const afterResolve = (graphLike) => {
             const graph = isGraph(graphLike) ? graphLike.compile() : graphLike;
-            // TODO: hack, remove once LangChain 1.x createAgent is fixed
-            if (!isCompiledGraph(graph) && "graph" in graph) {
-                return graph.graph;
+            // TODO: hack, remove once LangChain 1.x createAgent is fixed.
+            // `createAgent` returns a ReactAgent wrapper that itself looks
+            // like a CompiledGraph (it has a `builder` — the outer
+            // StateGraph) *and* exposes the real compiled pregel under
+            // `.graph`. Unwrap to the inner graph whenever both are
+            // present so downstream code (e.g. the v2 streaming path that
+            // keys off `graph.streamTransformers`) sees the actual pregel
+            // rather than the wrapper.
+            const inner = graph.graph;
+            if (inner != null &&
+                typeof inner === "object" &&
+                isCompiledGraph(inner)) {
+                return inner;
             }
             return graph;
         };

package/dist/protocol/constants.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Internal kwargs flag set on runs created through the protocol transport.
+ *
+ * When present, the streaming layer uses `streamStateV2` and forwards native
+ * protocol events to the v2 protocol session.
+ */
+export declare const PROTOCOL_STREAM_RUN_KEY = "__protocol_stream_run";

package/dist/protocol/constants.mjs

@@ -0,0 +1,7 @@
+/**
+ * Internal kwargs flag set on runs created through the protocol transport.
+ *
+ * When present, the streaming layer uses `streamStateV2` and forwards native
+ * protocol events to the v2 protocol session.
+ */
+export const PROTOCOL_STREAM_RUN_KEY = "__protocol_stream_run";

package/dist/protocol/service.d.mts

@@ -0,0 +1,101 @@
+import type { RunsRepo, ThreadsRepo } from "../storage/types.mjs";
+import type { EventSinkEntry, EventSinkFilter, ProtocolCommand, ProtocolError, ProtocolEvent, ProtocolSuccess, ThreadRecord, ProtocolTransportName } from "./types.mjs";
+type ServiceBindings = {
+    runs: RunsRepo;
+    threads: ThreadsRepo;
+};
+/**
+ * Transport-agnostic sink used to forward normalized protocol events into a
+ * concrete delivery mechanism such as WebSocket or SSE.
+ */
+type EventSink = (message: ProtocolEvent) => Promise<void> | void;
+/**
+ * Thread-scoped connection registry and command dispatcher.
+ *
+ * In the thread-centric protocol, a `ThreadRecord` holds ephemeral
+ * connection state for an active client interacting with a thread. The
+ * thread itself is durable (lives in the checkpoint store); records are
+ * created lazily on first interaction and dropped when all connections
+ * close.
+ */
+export declare class ProtocolService {
+    private readonly bindings;
+    private readonly threads;
+    constructor(bindings: ServiceBindings);
+    getThread(threadId: string): ThreadRecord | undefined;
+    /**
+     * Get or create the in-memory record for a thread. Records hold
+     * ephemeral connection state (event sinks, current run session) and
+     * are created on first use for any thread the client targets.
+     */
+    ensureThread(options: {
+        threadId: string;
+        transport: ProtocolTransportName;
+        auth?: ThreadRecord["auth"];
+        sendEvent?: EventSink;
+    }): ThreadRecord;
+    /**
+     * Attach a live transport consumer (WebSocket) and flush any buffered
+     * events.
+     */
+    attachEventSink(threadId: string, sendEvent: EventSink): Promise<ThreadRecord>;
+    /**
+     * Attach a filtered SSE event sink and replay buffered events that
+     * match the filter.
+     *
+     * The sink is flagged `pendingReplay` while draining so that the live
+     * `send` path skips it — preventing live events from interleaving with
+     * the replay loop's awaits and producing out-of-order delivery.
+     */
+    attachFilteredEventSink(threadId: string, sink: EventSinkEntry): Promise<ThreadRecord>;
+    /**
+     * Remove an SSE event sink when the connection closes.
+     */
+    detachEventSink(threadId: string, sinkId: string): void;
+    closeThread(threadId: string): Promise<void>;
+    /**
+     * Route a protocol command on a thread.
+     *
+     * `subscription.subscribe` can resolve to `null` on ordered
+     * transports (WebSocket) — see
+     * `ProtocolSession.handleSubscribeForResponse` for the rationale.
+     * Callers must treat `null` as "response already sent on the wire"
+     * and skip any additional send.
+     */
+    handleCommand(threadId: string, command: ProtocolCommand): Promise<ProtocolSuccess | ProtocolError | null>;
+    /**
+     * Start a new run, resume an interrupted run, or continue on the
+     * thread depending on its current state.
+     */
+    private handleRunStart;
+    private handleInputRespond;
+    private createOrResumeRun;
+    private hasPendingInterrupts;
+    private hasPendingInterruptsForThread;
+    private handleStateGet;
+    private forwardToRunSession;
+    /**
+     * Drain any WebSocket subscribes that arrived before the first run
+     * session was bound. Called from `createOrResumeRun` right after
+     * {@link ensureRunSession} sets up `record.session`.
+     *
+     * Each parked command is forwarded to the freshly-bound session,
+     * added to `activeSubscriptions` so it persists across subsequent
+     * runs, and its deferred `handleCommand` promise is resolved so the
+     * WebSocket handler can finally send the response.
+     */
+    private drainPendingSubscribes;
+    /**
+     * Bind the thread record to a concrete LangGraph run and forward
+     * normalized protocol events to attached sinks.
+     */
+    private ensureRunSession;
+    private requireThread;
+    error(id: number | null, code: ProtocolError["error"], message: string): ProtocolError;
+}
+/**
+ * Check whether a protocol event matches an SSE event sink filter.
+ * Mirrors the subscription matching logic in {@link RunProtocolSession}.
+ */
+export declare function matchesSinkFilter(filter: EventSinkFilter, event: ProtocolEvent): boolean;
+export {};