@downcity/agent 1.1.22 → 1.1.25

package/src/runtime/server/http/sdk/SessionRoutes.ts

@@ -0,0 +1,232 @@
+/**
+ * SDK HTTP session 路由。
+ *
+ * 关键点（中文）
+ * - 这组路由面向 `RemoteAgent`，只暴露最小 Session actor 使用面。
+ * - 当前公开输入收口到 `prompt()`，公开输出收口到 `events` 长连接。
+ * - 不复用 control API 的控制台语义，避免 transport 面混入非 SDK 约束。
+ */
+
+import { Hono } from "hono";
+import type { AgentCore } from "@/core/AgentCore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+
+const NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+const SDK_EVENTS_READY_FRAME = {
+  type: "sdk-events-ready",
+} as const;
+
+/**
+ * 注册 SDK session 路由。
+ */
+export function registerSdkSessionRoutes(
+  app: Hono,
+  core: Pick<AgentCore, "session" | "sessions">,
+): void {
+  app.get("/api/sdk/sessions", async (c) => {
+    try {
+      const sessions = await core.sessions();
+      return c.json({
+        success: true,
+        sessions,
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.post("/api/sdk/sessions", async (c) => {
+    try {
+      const body = (await c.req.json().catch(() => ({}))) as {
+        sessionId?: unknown;
+      };
+      const rawSessionId = String(body.sessionId || "").trim();
+      const session = await core.session(rawSessionId || undefined);
+      return c.json({
+        success: true,
+        session: await session.toMetadata(),
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.post("/api/sdk/sessions/:sessionId/prompt", async (c) => {
+    try {
+      const sessionId = String(c.req.param("sessionId") || "").trim();
+      if (!sessionId) {
+        return c.json({ success: false, error: "Missing sessionId" }, 400);
+      }
+      const body = (await c.req.json()) as AgentSessionPromptInput;
+      const session = await core.session(sessionId);
+      const turn = await session.prompt(body);
+      return c.json({
+        success: true,
+        turn: {
+          id: turn.id,
+        },
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.get("/api/sdk/sessions/:sessionId/events", async (c) => {
+    const sessionId = String(c.req.param("sessionId") || "").trim();
+    if (!sessionId) {
+      return c.json({ success: false, error: "Missing sessionId" }, 400);
+    }
+
+    try {
+      const session = await core.session(sessionId);
+      const encoder = new TextEncoder();
+      const requestSignal = c.req.raw.signal;
+
+      let cleanupEventsConnection = (): void => {};
+      const stream = new ReadableStream<Uint8Array>({
+        cancel() {
+          cleanupEventsConnection();
+        },
+        start(controller) {
+          const writeLine = (value: unknown): void => {
+            controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`));
+          };
+
+          const unsubscribe = session.subscribe((event) => {
+            writeLine(event);
+          });
+
+          const closeStream = (): void => {
+            cleanupEventsConnection();
+            try {
+              controller.close();
+            } catch {
+              // ignore duplicate close attempts
+            }
+          };
+
+          cleanupEventsConnection = (): void => {
+            unsubscribe();
+            requestSignal.removeEventListener("abort", closeStream);
+          };
+
+          if (requestSignal.aborted) {
+            closeStream();
+            return;
+          }
+
+          requestSignal.addEventListener("abort", closeStream, { once: true });
+          writeLine(SDK_EVENTS_READY_FRAME);
+        },
+      });
+
+      return new Response(stream, {
+        status: 200,
+        headers: {
+          "Content-Type": NDJSON_CONTENT_TYPE,
+          "Cache-Control": "no-cache, no-transform",
+          "X-Accel-Buffering": "no",
+        },
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.get("/api/sdk/sessions/:sessionId/messages", async (c) => {
+    try {
+      const sessionId = String(c.req.param("sessionId") || "").trim();
+      if (!sessionId) {
+        return c.json({ success: false, error: "Missing sessionId" }, 400);
+      }
+      const session = await core.session(sessionId);
+      return c.json({
+        success: true,
+        messages: await session.history(),
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.get("/api/sdk/sessions/:sessionId/system", async (c) => {
+    try {
+      const sessionId = String(c.req.param("sessionId") || "").trim();
+      if (!sessionId) {
+        return c.json({ success: false, error: "Missing sessionId" }, 400);
+      }
+      const session = await core.session(sessionId);
+      return c.json({
+        success: true,
+        system: await session.system(),
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+
+  app.post("/api/sdk/sessions/:sessionId/fork", async (c) => {
+    try {
+      const sessionId = String(c.req.param("sessionId") || "").trim();
+      if (!sessionId) {
+        return c.json({ success: false, error: "Missing sessionId" }, 400);
+      }
+      const body = (await c.req.json().catch(() => ({}))) as {
+        messageId?: unknown;
+      };
+      const session = await core.session(sessionId);
+      const forked = await session.fork(
+        String(body.messageId || "").trim() || undefined,
+      );
+      return c.json({
+        success: true,
+        session: await forked.toMetadata(),
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        500,
+      );
+    }
+  });
+}

package/src/sdk/AgentSdkTypes.ts

@@ -9,9 +9,7 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { JsonValue } from "@/types/common/Json.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
-import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
 import type { ServerInstance } from "@/runtime/server/http/Server.js";
@@ -292,140 +290,6 @@ export interface AgentSessionConfigSnapshot {
   modelLabel?: string;
 }
 
-/**
- * Session 运行输入。
- */
-export interface AgentSessionRunInput {
-  /**
-   * 当前轮用户查询文本。
-   */
-  query: string;
-}
-
-/**
- * Session 运行结果。
- */
-export interface AgentSessionRunResult {
-  /**
-   * 本轮执行是否成功。
-   */
-  success: boolean;
-
-  /**
-   * 失败时的错误文本。
-   */
-  error?: string;
-
-  /**
-   * 最终 assistant 文本。
-   */
-  text: string;
-
-  /**
-   * 最终 assistant 原始 UIMessage。
-   */
-  assistantMessage: SessionMessageV1;
-}
-
-/**
- * SDK 对外的流式事件。
- */
-export type AgentSessionStreamEvent =
-  | {
-      /**
-       * 文本增量事件。
-       */
-      type: "text-delta";
-      /**
-       * 当前追加的文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * reasoning 增量事件。
-       */
-      type: "reasoning-delta";
-      /**
-       * 当前追加的 reasoning 文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * 工具调用可用事件。
-       */
-      type: "tool-call";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输入参数。
-       */
-      args: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用结果事件。
-       */
-      type: "tool-result";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输出结果。
-       */
-      result: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用失败事件。
-       */
-      type: "tool-error";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 错误文本。
-       */
-      error: string;
-    }
-  | {
-      /**
-       * 运行结束事件。
-       */
-      type: "finish";
-      /**
-       * 最终完成原因（若底层可提供）。
-       */
-      finishReason?: string;
-    }
-  | {
-      /**
-       * 运行错误事件。
-       */
-      type: "error";
-      /**
-       * 错误文本。
-       */
-      error: string;
-    };
-
 /**
  * Session system block 来源类型。
  */
@@ -490,7 +354,7 @@ export interface AgentSessionSystemSessionInfo {
    *
    * 关键点（中文）
    * - 这是 session 初始化时落盘的稳定参考时间，按 Date/ISO 字符串对外展示。
-   * - 它不是每轮运行的当前时间，不会随着 `run()` / `stream()` 改变。
+   * - 它不是每轮运行的当前时间，不会随着后续 turn 执行而改变。
    */
   createdAt: string;