@langchain/langgraph-api 1.1.16 → 1.2.0

package/dist/api/protocol.d.mts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import type { UpgradeWebSocket } from "hono/ws";
+import type { Ops } from "../storage/types.mjs";
+/**
+ * Register thread-centric protocol transport routes for LangGraph API.
+ */
+export default function createProtocolApi(upgradeWebSocket: UpgradeWebSocket, ops: Ops): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/api/protocol.mjs

@@ -0,0 +1,157 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { v7 as uuid7 } from "uuid";
+import { z } from "zod/v3";
+import { ProtocolService } from "../protocol/service.mjs";
+import { jsonExtra } from "../utils/hono.mjs";
+import { serialiseAsDict } from "../utils/serde.mjs";
+const ThreadIdSchema = z.object({ thread_id: z.string() });
+const EventsFilterSchema = z
+    .object({
+    channels: z.array(z.string()),
+    namespaces: z.array(z.array(z.string())).optional(),
+    depth: z.number().int().nonnegative().optional(),
+    since: z.number().int().nonnegative().optional(),
+})
+    .strict();
+const ProtocolCommandSchema = z.object({
+    id: z.number().int().nonnegative(),
+    method: z.string(),
+    params: z.record(z.unknown()).optional(),
+});
+/**
+ * Normalize browser/node websocket message payloads into UTF-8 text so the
+ * protocol layer only needs to handle JSON strings.
+ */
+const parseSocketPayload = async (event) => {
+    if (typeof event.data === "string")
+        return event.data;
+    if (event.data instanceof ArrayBuffer) {
+        return new TextDecoder().decode(new Uint8Array(event.data));
+    }
+    if (event.data instanceof Blob) {
+        const buffer = await event.data.arrayBuffer();
+        return new TextDecoder().decode(new Uint8Array(buffer));
+    }
+    return String(event.data);
+};
+/**
+ * Register thread-centric protocol transport routes for LangGraph API.
+ */
+export default function createProtocolApi(upgradeWebSocket, ops) {
+    const api = new Hono();
+    const protocolService = new ProtocolService({
+        runs: ops.runs,
+        threads: ops.threads,
+    });
+    api.get("/v2/threads/:thread_id/stream", zValidator("param", ThreadIdSchema), upgradeWebSocket((c) => {
+        const { thread_id } = c.req.valid("param");
+        const record = protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "websocket",
+            auth: c.var.auth,
+        });
+        return {
+            async onOpen(_event, ws) {
+                await protocolService.attachEventSink(thread_id, (event) => {
+                    ws.send(serialiseAsDict(event));
+                });
+            },
+            async onMessage(event, ws) {
+                let payload;
+                try {
+                    payload = JSON.parse(await parseSocketPayload(event));
+                }
+                catch {
+                    ws.send(serialiseAsDict({
+                        type: "error",
+                        id: null,
+                        error: "invalid_argument",
+                        message: "Protocol commands must be valid JSON.",
+                    }));
+                    return;
+                }
+                if (typeof payload !== "object" ||
+                    payload == null ||
+                    typeof payload.id !== "number" ||
+                    typeof payload.method !== "string") {
+                    ws.send(serialiseAsDict({
+                        type: "error",
+                        id: null,
+                        error: "invalid_argument",
+                        message: "Protocol commands must include an integer id and string method.",
+                    }));
+                    return;
+                }
+                const response = await protocolService.handleCommand(record.threadId, payload);
+                // `null` means the session already wrote the response through
+                // the shared transport queue (see
+                // `ProtocolSession.handleSubscribeForResponse`). Sending again
+                // here would double-deliver the success and break ordering.
+                if (response != null) {
+                    ws.send(serialiseAsDict(response));
+                }
+            },
+            onClose() {
+                void protocolService.closeThread(record.threadId);
+            },
+            onError() {
+                void protocolService.closeThread(record.threadId);
+            },
+        };
+    }));
+    api.post("/v2/threads/:thread_id/commands", zValidator("param", ThreadIdSchema), zValidator("json", ProtocolCommandSchema), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "sse-http",
+            auth: c.var.auth,
+        });
+        const payload = c.req.valid("json");
+        return jsonExtra(c, await protocolService.handleCommand(thread_id, payload));
+    });
+    api.post("/v2/threads/:thread_id/stream", zValidator("param", ThreadIdSchema), zValidator("json", EventsFilterSchema), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "sse-http",
+            auth: c.var.auth,
+        });
+        const body = c.req.valid("json");
+        const sinkId = uuid7();
+        const filter = {
+            channels: new Set(body.channels),
+            namespaces: body.namespaces,
+            depth: body.depth,
+            since: body.since,
+        };
+        return streamSSE(c, async (stream) => {
+            const delivered = new Set();
+            const writeSse = async (event) => {
+                if (event.event_id == null)
+                    return;
+                if (delivered.has(event.event_id))
+                    return;
+                delivered.add(event.event_id);
+                await stream.writeSSE({
+                    id: event.event_id,
+                    event: event.method,
+                    data: serialiseAsDict(event),
+                });
+            };
+            await protocolService.attachFilteredEventSink(thread_id, {
+                id: sinkId,
+                filter,
+                send: writeSse,
+            });
+            stream.onAbort(() => {
+                protocolService.detachEventSink(thread_id, sinkId);
+            });
+            await new Promise((resolve) => {
+                stream.onAbort(() => resolve());
+            });
+        });
+    });
+    return api;
+}

package/dist/api/runs.mjs

@@ -150,7 +150,8 @@ api.post("/runs/stream", zValidator("json", schemas.RunCreate), async (c) => {
             : undefined;
         try {
             for await (const { event, data } of runs().stream.join(run.run_id, undefined, {
-                cancelOnDisconnect,
+                signal: cancelOnDisconnect,
+                cancelOnDisconnect: cancelOnDisconnect != null,
                 lastEventId: run.kwargs.resumable ? "-1" : undefined,
                 ignore404: true,
             }, c.var.auth)) {
@@ -173,7 +174,12 @@ api.get("/runs/:run_id/stream", zValidator("param", z.object({ run_id: z.string(
             ? getDisconnectAbortSignal(c, stream)
             : undefined;
         try {
-            for await (const { id, event, data } of runs().stream.join(run_id, undefined, { cancelOnDisconnect, lastEventId, ignore404: true }, c.var.auth)) {
+            for await (const { id, event, data } of runs().stream.join(run_id, undefined, {
+                signal: cancelOnDisconnect,
+                cancelOnDisconnect: cancelOnDisconnect != null,
+                lastEventId,
+                ignore404: true,
+            }, c.var.auth)) {
                 await stream.writeSSE({ id, data: serialiseAsDict(data), event });
             }
         }
@@ -252,7 +258,8 @@ api.post("/threads/:thread_id/runs/stream", zValidator("param", z.object({ threa
             : undefined;
         try {
             for await (const { id, event, data } of runs().stream.join(run.run_id, thread_id, {
-                cancelOnDisconnect,
+                signal: cancelOnDisconnect,
+                cancelOnDisconnect: cancelOnDisconnect != null,
                 lastEventId: run.kwargs.resumable ? "-1" : undefined,
             }, c.var.auth)) {
                 await stream.writeSSE({ id, data: serialiseAsDict(data), event });
@@ -304,7 +311,11 @@ api.get("/threads/:thread_id/runs/:run_id/stream", zValidator("param", z.object(
         const signal = cancel_on_disconnect
             ? getDisconnectAbortSignal(c, stream)
             : undefined;
-        for await (const { id, event, data } of runs().stream.join(run_id, thread_id, { cancelOnDisconnect: signal, lastEventId }, c.var.auth)) {
+        for await (const { id, event, data } of runs().stream.join(run_id, thread_id, {
+            signal,
+            cancelOnDisconnect: signal != null,
+            lastEventId,
+        }, c.var.auth)) {
             await stream.writeSSE({ id, data: serialiseAsDict(data), event });
         }
     });

package/dist/command.mjs

@@ -1,6 +1,6 @@
 import { Command, Send } from "@langchain/langgraph";
 export const getLangGraphCommand = (command) => {
-    let goto = command.goto != null && !Array.isArray(command.goto)
+    const goto = command.goto != null && !Array.isArray(command.goto)
         ? [command.goto]
         : command.goto;
     return new Command({

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

@@ -0,0 +1,3 @@
+import type { StreamMode } from "../../storage/types.mjs";
+export declare const PROTOCOL_VERSION = "0.3.0";
+export declare const DEFAULT_PROTOCOL_STREAM_MODES: StreamMode[];

package/dist/experimental/embed/constants.mjs

@@ -0,0 +1,11 @@
+export const PROTOCOL_VERSION = "0.3.0";
+export const DEFAULT_PROTOCOL_STREAM_MODES = [
+    "values",
+    "updates",
+    "messages",
+    "tools",
+    "custom",
+    "debug",
+    "checkpoints",
+    "tasks",
+];

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

@@ -0,0 +1,9 @@
+import type { Hono } from "hono";
+import type { UpgradeWebSocket } from "hono/ws";
+import type { EmbedRouteContext } from "./types.mjs";
+/**
+ * Register thread-centric v2 protocol routes on an embed server Hono app.
+ *
+ * @experimental Does not follow semver.
+ */
+export declare function registerProtocolRoutes(api: Hono, context: EmbedRouteContext, upgradeWebSocket?: UpgradeWebSocket): void;