@langgraph-js/pure-graph 1.0.2 → 1.3.0

package/src/adapter/hono/runs.ts

@@ -2,46 +2,26 @@ import { zValidator } from '@hono/zod-validator';
 import { Hono } from 'hono';
 
 import { streamSSE } from 'hono/streaming';
-import { z } from 'zod';
 import { client } from './endpoint';
-import { AssistantConfig, CommandSchema, MetadataSchema } from './zod';
+import {
+    ThreadIdParamSchema,
+    RunIdParamSchema,
+    RunStreamPayloadSchema,
+    RunListQuerySchema,
+    RunCancelQuerySchema,
+    ThreadStateUpdate,
+} from '../zod';
 import { serialiseAsDict } from '../../graph/stream';
+import { RunnableConfig } from '@langchain/core/runnables';
+import z from 'zod';
 
 const api = new Hono();
 
 // 最常用的对话接口
 api.post(
     '/threads/:thread_id/runs/stream',
-    zValidator('param', z.object({ thread_id: z.string().uuid() })),
-    zValidator(
-        'json',
-        z
-            .object({
-                assistant_id: z.union([z.string().uuid(), z.string()]),
-                checkpoint_id: z.string().optional(),
-                // checkpoint: CheckpointSchema.optional(),
-                input: z.any().optional(),
-                command: CommandSchema.optional(),
-                metadata: MetadataSchema.optional(),
-                config: AssistantConfig.optional(),
-                webhook: z.string().optional(),
-                interrupt_before: z.union([z.literal('*'), z.array(z.string())]).optional(),
-                interrupt_after: z.union([z.literal('*'), z.array(z.string())]).optional(),
-                on_disconnect: z.enum(['cancel', 'continue']).optional().default('continue'),
-                multitask_strategy: z.enum(['reject', 'rollback', 'interrupt', 'enqueue']).optional(),
-                stream_mode: z
-                    .array(z.enum(['values', 'messages', 'messages-tuple', 'updates', 'events', 'debug', 'custom']))
-                    .optional(),
-                stream_subgraphs: z.boolean().optional(),
-                stream_resumable: z.boolean().optional(),
-                after_seconds: z.number().optional(),
-                if_not_exists: z.enum(['create', 'reject']).optional(),
-                on_completion: z.enum(['complete', 'continue']).optional(),
-                feedback_keys: z.array(z.string()).optional(),
-                langsmith_tracer: z.unknown().optional(),
-            })
-            .describe('Payload for creating a stateful run.'),
-    ),
+    zValidator('param', ThreadIdParamSchema),
+    zValidator('json', RunStreamPayloadSchema),
     async (c) => {
         // Stream Run
         const { thread_id } = c.req.valid('param');
@@ -51,7 +31,7 @@ api.post(
         return streamSSE(c, async (stream) => {
             /** @ts-ignore zod v3 的问题，与 ts 类型不一致 */
             for await (const { event, data } of client.runs.stream(thread_id, payload.assistant_id, payload)) {
-                await stream.writeSSE({ data: serialiseAsDict(data), event });
+                await stream.writeSSE({ data: serialiseAsDict(data) ?? '', event });
             }
         });
     },
@@ -59,33 +39,20 @@ api.post(
 
 api.get(
     '/threads/:thread_id/runs',
-    zValidator('param', z.object({ thread_id: z.string().uuid() })),
-    zValidator(
-        'query',
-        z.object({
-            limit: z.string().optional(),
-            offset: z.string().optional(),
-            status: z.enum(['pending', 'running', 'error', 'success', 'timeout', 'interrupted']).optional(),
-        }),
-    ),
+    zValidator('param', ThreadIdParamSchema),
+    zValidator('query', RunListQuerySchema),
     async (c) => {
         const { thread_id } = c.req.valid('param');
         const { limit, offset, status } = c.req.valid('query');
-        const runs = await client.runs.list(thread_id, { limit: Number(limit), offset: Number(offset), status });
+        const runs = await client.runs.list(thread_id, { limit, offset, status });
         return c.json(runs);
     },
 );
 
 api.post(
     '/threads/:thread_id/runs/:run_id/cancel',
-    zValidator('param', z.object({ thread_id: z.string().uuid(), run_id: z.string().uuid() })),
-    zValidator(
-        'query',
-        z.object({
-            wait: z.coerce.boolean().optional().default(false),
-            action: z.enum(['interrupt', 'rollback']).optional().default('interrupt'),
-        }),
-    ),
+    zValidator('param', RunIdParamSchema),
+    zValidator('query', RunCancelQuerySchema),
     async (c) => {
         // Cancel Run Http
         const { thread_id, run_id } = c.req.valid('param');
@@ -98,4 +65,28 @@ api.post(
     },
 );
 
+api.post(
+    '/threads/:thread_id/state',
+    zValidator('param', z.object({ thread_id: z.string().uuid() })),
+    zValidator('json', ThreadStateUpdate),
+    async (c) => {
+        // Update Thread State
+        const { thread_id } = c.req.valid('param');
+        const payload = c.req.valid('json');
+        // const config: RunnableConfig = { configurable: { thread_id } };
+
+        // if (payload.checkpoint_id) {
+        //     config.configurable ??= {};
+        //     config.configurable.checkpoint_id = payload.checkpoint_id;
+        // }
+        // if (payload.checkpoint) {
+        //     config.configurable ??= {};
+        //     Object.assign(config.configurable, payload.checkpoint);
+        // }
+
+        const inserted = await client.threads.updateState(thread_id, payload);
+
+        return c.json(inserted);
+    },
+);
 export default api;

package/src/adapter/hono/threads.ts

@@ -1,88 +1,33 @@
 import { zValidator } from '@hono/zod-validator';
 import { Hono } from 'hono';
-import { z } from 'zod';
 import { client } from './endpoint';
-import { CommandSchema, MetadataSchema } from './zod';
+import { ThreadIdParamSchema, ThreadCreatePayloadSchema, ThreadSearchPayloadSchema } from '../zod';
 
 const api = new Hono();
 
 // Threads Routes
-api.post(
-    '/threads',
-    zValidator(
-        'json',
-        z
-            .object({
-                // supersteps: z
-                //     .array(
-                //         z.object({
-                //             updates: z.array(
-                //                 z.object({
-                //                     values: z.unknown(),
-                //                     command: CommandSchema.optional(),
-                //                     as_node: z.string(),
-                //                 }),
-                //             ),
-                //         }),
-                //     )
-                //     .describe('The supersteps to apply to the thread.')
-                //     .optional(),
-                thread_id: z
-                    .string()
-                    .uuid()
-                    .describe('The ID of the thread. If not provided, an ID is generated.')
-                    .optional(),
-                metadata: MetadataSchema.optional(),
-                if_exists: z.union([z.literal('raise'), z.literal('do_nothing')]).optional(),
-            })
-            .describe('Payload for creating a thread.'),
-    ),
-    async (c) => {
-        const payload = c.req.valid('json');
-        const thread = await client.threads.create(payload);
+api.post('/threads', zValidator('json', ThreadCreatePayloadSchema), async (c) => {
+    const payload = c.req.valid('json');
+    const thread = await client.threads.create(payload);
 
-        return c.json(thread);
-    },
-);
+    return c.json(thread);
+});
 
-api.post(
-    '/threads/search',
-    zValidator(
-        'json',
-        z
-            .object({
-                metadata: z.record(z.unknown()).describe('Metadata to search for.').optional(),
-                status: z
-                    .enum(['idle', 'busy', 'interrupted', 'error'])
-                    .describe('Filter by thread status.')
-                    .optional(),
-                values: z.record(z.unknown()).describe('Filter by thread values.').optional(),
-                limit: z.number().int().gte(1).lte(1000).describe('Maximum number to return.').optional(),
-                offset: z.number().int().gte(0).describe('Offset to start from.').optional(),
-                sort_by: z
-                    .enum(['thread_id', 'status', 'created_at', 'updated_at'])
-                    .describe('Sort by field.')
-                    .optional(),
-                sort_order: z.enum(['asc', 'desc']).describe('Sort order.').optional(),
-            })
-            .describe('Payload for listing threads.'),
-    ),
-    async (c) => {
-        // Search Threads
-        const payload = c.req.valid('json');
-        const result = await client.threads.search(payload as any);
-        c.res.headers.set('X-Pagination-Total', result.length.toString());
-        return c.json(result);
-    },
-);
+api.post('/threads/search', zValidator('json', ThreadSearchPayloadSchema), async (c) => {
+    // Search Threads
+    const payload = c.req.valid('json');
+    const result = await client.threads.search(payload as any);
+    c.res.headers.set('X-Pagination-Total', result.length.toString());
+    return c.json(result);
+});
 
-api.get('/threads/:thread_id', zValidator('param', z.object({ thread_id: z.string().uuid() })), async (c) => {
+api.get('/threads/:thread_id', zValidator('param', ThreadIdParamSchema), async (c) => {
     // Get Thread
     const { thread_id } = c.req.valid('param');
     return c.json(await client.threads.get(thread_id));
 });
 
-api.delete('/threads/:thread_id', zValidator('param', z.object({ thread_id: z.string().uuid() })), async (c) => {
+api.delete('/threads/:thread_id', zValidator('param', ThreadIdParamSchema), async (c) => {
     // Delete Thread
     const { thread_id } = c.req.valid('param');
     await client.threads.delete(thread_id);

package/src/adapter/nextjs/endpoint.ts

@@ -0,0 +1,2 @@
+import { createEndpoint } from '../../createEndpoint.js';
+export const client = createEndpoint();

package/src/adapter/nextjs/index.ts

@@ -0,0 +1,2 @@
+// 统一路由处理器
+export { GET, POST, DELETE } from "./router";

package/src/adapter/nextjs/router.ts

@@ -0,0 +1,206 @@
+/** @ts-ignore */
+import { NextRequest, NextResponse } from 'next/server';
+import { client } from './endpoint';
+import {
+    AssistantsSearchSchema,
+    AssistantGraphQuerySchema,
+    RunStreamPayloadSchema,
+    RunListQuerySchema,
+    RunCancelQuerySchema,
+    ThreadCreatePayloadSchema,
+    ThreadSearchPayloadSchema,
+    ThreadStateUpdate,
+} from '../zod';
+import { serialiseAsDict } from '../../graph/stream';
+
+// Next.js App Router 的 SSE 响应实现
+async function sseResponse(generator: AsyncGenerator<{ event: string; data: unknown }>): Promise<Response> {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        async start(controller) {
+            try {
+                for await (const { event, data } of generator) {
+                    const line = `event: ${event}\n` + `data: ${serialiseAsDict(data, 0)}\n\n`;
+                    controller.enqueue(encoder.encode(line));
+                }
+            } catch (err) {
+                // ignore
+            } finally {
+                controller.close();
+            }
+        },
+    });
+    return new Response(stream, {
+        headers: {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+        },
+    });
+}
+
+// 统一路由处理器
+export async function GET(req: NextRequest) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    // Assistants routes
+    if (pathname.match(/\/assistants\/[^/]+\/graph$/)) {
+        const match = pathname.match(/\/assistants\/([^/]+)\/graph$/);
+        if (match) {
+            const assistant_id = match[1];
+            const xrayParam = url.searchParams.get('xray');
+            const queryParams = { xray: xrayParam };
+            const { xray } = AssistantGraphQuerySchema.parse(queryParams);
+            const data = await client.assistants.getGraph(assistant_id, {
+                xray: xray !== undefined ? xray === 'true' : undefined,
+            });
+            return NextResponse.json(data);
+        }
+    }
+
+    // Threads routes
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})$/);
+        if (match) {
+            const thread_id = match[1];
+            const data = await client.threads.get(thread_id);
+            return NextResponse.json(data);
+        }
+    }
+
+    // Runs routes
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}\/runs$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})\/runs$/);
+        if (match) {
+            const thread_id = match[1];
+            const limit = url.searchParams.get('limit');
+            const offset = url.searchParams.get('offset');
+            const status = url.searchParams.get('status');
+            const queryParams = { limit, offset, status };
+            const {
+                limit: parsedLimit,
+                offset: parsedOffset,
+                status: parsedStatus,
+            } = RunListQuerySchema.parse(queryParams);
+            const runs = await client.runs.list(thread_id, {
+                limit: parsedLimit,
+                offset: parsedOffset,
+                status: parsedStatus,
+            });
+            return Response.json(runs);
+        }
+    }
+
+    return new NextResponse('Not Found', { status: 404 });
+}
+
+export async function POST(req: NextRequest) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    // Assistants routes
+    if (pathname.endsWith('/assistants/search')) {
+        const body = await req.json();
+        const payload = AssistantsSearchSchema.parse(body);
+        const data = await client.assistants.search({
+            graphId: payload.graph_id,
+            metadata: payload.metadata as any,
+            limit: payload.limit,
+            offset: payload.offset,
+        } as any);
+        return NextResponse.json(data, {
+            headers: { 'X-Pagination-Total': String(data.length) },
+        });
+    }
+
+    // Threads routes
+    if (pathname.endsWith('/threads')) {
+        const body = await req.json();
+        const payload = ThreadCreatePayloadSchema.parse(body);
+        const thread = await client.threads.create({
+            thread_id: payload.thread_id,
+            metadata: payload.metadata as any,
+            if_exists: (payload.if_exists as any) ?? undefined,
+        });
+        return NextResponse.json(thread);
+    }
+
+    if (pathname.endsWith('/threads/search')) {
+        const body = await req.json();
+        const payload = ThreadSearchPayloadSchema.parse(body);
+        const result = await client.threads.search({
+            metadata: payload.metadata as any,
+            status: payload.status as any,
+            limit: payload.limit,
+            offset: payload.offset,
+            sortBy: (payload.sort_by as any) ?? undefined,
+            sortOrder: (payload.sort_order as any) ?? undefined,
+        });
+        return NextResponse.json(result, {
+            headers: { 'X-Pagination-Total': String(result.length) },
+        });
+    }
+
+    // Threads state update
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}\/state$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})\/state$/);
+        if (match) {
+            const thread_id = match[1];
+            const body = await req.json();
+            const payload = ThreadStateUpdate.parse(body);
+            const result = await client.threads.updateState(thread_id, payload);
+            return NextResponse.json(result);
+        }
+    }
+
+    // Runs routes - stream
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}\/runs\/stream$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})\/runs\/stream$/);
+        if (match) {
+            const thread_id = match[1];
+            const body = await req.json();
+            const payload = RunStreamPayloadSchema.parse(body);
+            const generator = client.runs.stream(thread_id, payload.assistant_id as string, payload as any);
+            return sseResponse(generator as any);
+        }
+    }
+
+    // Runs routes - cancel
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}\/runs\/[0-9a-fA-F-]{36}\/cancel$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})\/runs\/([0-9a-fA-F-]{36})\/cancel$/);
+        if (match) {
+            const thread_id = match[1];
+            const run_id = match[2];
+            const waitParam = url.searchParams.get('wait');
+            const actionParam = url.searchParams.get('action');
+            const queryParams = {
+                wait: waitParam ? waitParam === 'true' : false,
+                action: actionParam ?? 'interrupt',
+            };
+            const { wait, action } = RunCancelQuerySchema.parse(queryParams);
+            const promise = client.runs.cancel(thread_id, run_id, wait, action);
+            if (wait) await promise;
+            return new Response(null, { status: wait ? 204 : 202 });
+        }
+    }
+
+    return new NextResponse('Not Found', { status: 404 });
+}
+
+export async function DELETE(req: NextRequest) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    // Threads routes
+    if (pathname.match(/\/threads\/[0-9a-fA-F-]{36}$/)) {
+        const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})$/);
+        if (match) {
+            const thread_id = match[1];
+            await client.threads.delete(thread_id);
+            return new NextResponse(null, { status: 204 });
+        }
+    }
+
+    return new NextResponse('Not Found', { status: 404 });
+}

package/src/adapter/{hono → nextjs}/zod.ts

@@ -1,4 +1,4 @@
-import z from 'zod';
+import z from "zod";
 
 export const AssistantConfigurable = z
     .object({
@@ -14,7 +14,7 @@ export const AssistantConfig = z
         configurable: AssistantConfigurable.optional(),
     })
     .catchall(z.unknown())
-    .describe('The configuration of an assistant.');
+    .describe("The configuration of an assistant.");
 
 export const Assistant = z.object({
     assistant_id: z.string().uuid(),
@@ -27,7 +27,14 @@ export const Assistant = z.object({
 
 export const MetadataSchema = z
     .object({
-        source: z.union([z.literal('input'), z.literal('loop'), z.literal('update'), z.string()]).optional(),
+        source: z
+            .union([
+                z.literal("input"),
+                z.literal("loop"),
+                z.literal("update"),
+                z.string(),
+            ])
+            .optional(),
         step: z.number().optional(),
         writes: z.record(z.unknown()).nullable().optional(),
         parents: z.record(z.string()).optional(),
@@ -41,9 +48,19 @@ export const SendSchema = z.object({
 
 export const CommandSchema = z.object({
     update: z
-        .union([z.record(z.unknown()), z.array(z.tuple([z.string(), z.unknown()]))])
+        .union([
+            z.record(z.unknown()),
+            z.array(z.tuple([z.string(), z.unknown()])),
+        ])
         .nullable()
         .optional(),
     resume: z.unknown().optional(),
-    goto: z.union([SendSchema, z.array(SendSchema), z.string(), z.array(z.string())]).optional(),
+    goto: z
+        .union([
+            SendSchema,
+            z.array(SendSchema),
+            z.string(),
+            z.array(z.string()),
+        ])
+        .optional(),
 });

package/src/adapter/zod.ts

@@ -0,0 +1,144 @@
+import z from 'zod';
+
+export const AssistantConfigurable = z
+    .object({
+        thread_id: z.string().optional(),
+        thread_ts: z.string().optional(),
+    })
+    .catchall(z.unknown());
+
+export const AssistantConfig = z
+    .object({
+        tags: z.array(z.string()).optional(),
+        recursion_limit: z.number().int().optional(),
+        configurable: AssistantConfigurable.optional(),
+    })
+    .catchall(z.unknown())
+    .describe('The configuration of an assistant.');
+
+export const Assistant = z.object({
+    assistant_id: z.string().uuid(),
+    graph_id: z.string(),
+    config: AssistantConfig,
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: z.object({}).catchall(z.any()),
+});
+
+export const MetadataSchema = z
+    .object({
+        source: z.union([z.literal('input'), z.literal('loop'), z.literal('update'), z.string()]).optional(),
+        step: z.number().optional(),
+        writes: z.record(z.unknown()).nullable().optional(),
+        parents: z.record(z.string()).optional(),
+    })
+    .catchall(z.unknown());
+
+export const SendSchema = z.object({
+    node: z.string(),
+    input: z.unknown().nullable(),
+});
+
+export const CommandSchema = z.object({
+    update: z
+        .union([z.record(z.unknown()), z.array(z.tuple([z.string(), z.unknown()]))])
+        .nullable()
+        .optional(),
+    resume: z.unknown().optional(),
+    goto: z.union([SendSchema, z.array(SendSchema), z.string(), z.array(z.string())]).optional(),
+});
+
+// 公共的查询参数验证 schema
+export const PaginationQuerySchema = z.object({
+    limit: z.number().int().optional(),
+    offset: z.number().int().optional(),
+});
+
+export const ThreadIdParamSchema = z.object({
+    thread_id: z.string().uuid(),
+});
+
+export const RunIdParamSchema = z.object({
+    thread_id: z.string().uuid(),
+    run_id: z.string().uuid(),
+});
+
+// Assistants 相关的 schema
+export const AssistantsSearchSchema = z.object({
+    graph_id: z.string().optional(),
+    metadata: MetadataSchema.optional(),
+    limit: z.number().int().optional(),
+    offset: z.number().int().optional(),
+});
+
+export const AssistantGraphQuerySchema = z.object({
+    xray: z.string().optional(),
+});
+
+// Runs 相关的 schema
+export const RunStreamPayloadSchema = z
+    .object({
+        assistant_id: z.union([z.string().uuid(), z.string()]),
+        checkpoint_id: z.string().optional(),
+        input: z.any().optional(),
+        command: CommandSchema.optional(),
+        metadata: MetadataSchema.optional(),
+        config: AssistantConfig.optional(),
+        webhook: z.string().optional(),
+        interrupt_before: z.union([z.literal('*'), z.array(z.string())]).optional(),
+        interrupt_after: z.union([z.literal('*'), z.array(z.string())]).optional(),
+        on_disconnect: z.enum(['cancel', 'continue']).optional().default('continue'),
+        multitask_strategy: z.enum(['reject', 'rollback', 'interrupt', 'enqueue']).optional(),
+        stream_mode: z
+            .array(z.enum(['values', 'messages', 'messages-tuple', 'updates', 'events', 'debug', 'custom']))
+            .optional(),
+        stream_subgraphs: z.boolean().optional(),
+        stream_resumable: z.boolean().optional(),
+        after_seconds: z.number().optional(),
+        if_not_exists: z.enum(['create', 'reject']).optional(),
+        on_completion: z.enum(['complete', 'continue']).optional(),
+        feedback_keys: z.array(z.string()).optional(),
+        langsmith_tracer: z.unknown().optional(),
+    })
+    .describe('Payload for creating a stateful run.');
+
+export const RunListQuerySchema = z.object({
+    limit: z.coerce.number().int().optional(),
+    offset: z.coerce.number().int().optional(),
+    status: z.enum(['pending', 'running', 'error', 'success', 'timeout', 'interrupted']).optional(),
+});
+
+export const RunCancelQuerySchema = z.object({
+    wait: z.coerce.boolean().optional().default(false),
+    action: z.enum(['interrupt', 'rollback']).optional().default('interrupt'),
+});
+
+// Threads 相关的 schema
+export const ThreadCreatePayloadSchema = z
+    .object({
+        thread_id: z.string().uuid().describe('The ID of the thread. If not provided, an ID is generated.').optional(),
+        metadata: MetadataSchema.optional(),
+        if_exists: z.union([z.literal('raise'), z.literal('do_nothing')]).optional(),
+    })
+    .describe('Payload for creating a thread.');
+
+export const ThreadSearchPayloadSchema = z
+    .object({
+        metadata: z.record(z.unknown()).describe('Metadata to search for.').optional(),
+        status: z.enum(['idle', 'busy', 'interrupted', 'error']).describe('Filter by thread status.').optional(),
+        values: z.record(z.unknown()).describe('Filter by thread values.').optional(),
+        limit: z.number().int().gte(1).lte(1000).describe('Maximum number to return.').optional(),
+        offset: z.number().int().gte(0).describe('Offset to start from.').optional(),
+        sort_by: z.enum(['thread_id', 'status', 'created_at', 'updated_at']).describe('Sort by field.').optional(),
+        sort_order: z.enum(['asc', 'desc']).describe('Sort order.').optional(),
+    })
+    .describe('Payload for listing threads.');
+
+export const ThreadStateUpdate = 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: CheckpointSchema.nullish(),
+    })
+    .describe('Payload for adding state to a thread.');