@downcity/agent 1.1.22 → 1.1.23

package/src/runtime/server/http/Server.ts

@@ -22,6 +22,7 @@ import {
 import { createPluginsRouter } from "@/runtime/server/http/plugins/plugins.js";
 import { createStaticRouter } from "@/runtime/server/http/static/static.js";
 import { createControlRouter } from "@/runtime/server/http/control/ControlRouter.js";
+import { createSdkRouter } from "@/runtime/server/http/sdk/Router.js";
 import {
   registerBuiltinPluginHttpRoutes,
 } from "@/plugin/core/HttpRoutes.js";
@@ -38,7 +39,7 @@ export interface ServerStartOptions {
   /** HTTP 服务监听主机。 */
   host: string;
   /** 可选实例级 agent core。 */
-  core?: Pick<AgentCore, "getContext" | "getRuntime">;
+  core?: Pick<AgentCore, "getContext" | "getRuntime" | "session" | "sessions">;
   /** 可选实例级 runtime 读取函数。 */
   getAgentRuntime?: () => AgentRuntime;
   /** 可选实例级 context 读取函数。 */
@@ -122,6 +123,9 @@ export function createServerApp(
     getAgentRuntime: bindings.getAgentRuntime,
     getAgentContext: bindings.getAgentContext,
   }));
+  if (options.core) {
+    app.route("/", createSdkRouter(options.core));
+  }
   registerBuiltinPluginHttpRoutes({
     app,
     getContext: bindings.getAgentContext,

package/src/runtime/server/http/control/ExecuteBySession.ts

@@ -112,7 +112,7 @@ export async function executeBySessionId(params: {
     text: executeInput,
   });
 
-  const result = await session.run({
+  const result = await session.execute({
     query: executeInput,
   });
 

package/src/runtime/server/http/control/StreamBySession.ts

@@ -1,10 +1,10 @@
 /**
- * Control session 流式执行 helper。
+ * Control session 增量执行 helper。
  *
  * 关键点（中文）
- * - 仅用于单 agent control API 的本地 session 流式返回。
+ * - 仅用于单 agent control API 的本地 session 增量返回。
  * - chatKey 命中的平台 chat 队列仍保持原有入队语义，不在这里伪造“流式完成”。
- * - 输出协议复用 SDK `AgentSessionStreamEvent` 的 NDJSON 事件行，便于 CLI 直接消费。
+ * - 输出协议使用内部 `AgentUiChunkEvent` 的 NDJSON 事件行，便于 CLI 直接消费。
  */
 
 import type { AgentContext, SessionPort } from "@/core/AgentContextTypes.js";
@@ -14,8 +14,8 @@ import type {
 } from "@/runtime/server/http/control/types/ControlSessionExecute.js";
 import { buildExecuteInputText } from "@/runtime/server/http/control/Helpers.js";
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
-import { mapUiMessageChunkToSdkEvent } from "@/sdk/StreamEvents.js";
-import type { AgentSessionStreamEvent } from "@/sdk/AgentSdkTypes.js";
+import { mapUiMessageChunkToAgentEvent } from "@/sdk/SessionEventMapper.js";
+import type { AgentUiChunkEvent } from "@/types/sdk/AgentUiChunkEvent.js";
 import type {
   SessionRunResult,
   SessionUiMessageChunkCallback,
@@ -34,7 +34,7 @@ type StreamableSessionPort = SessionPort & {
    * - `SessionPort` 对外接口当前未显式暴露 `onUiMessageChunkCallback`，
    *   但本地 executor 已支持该回调，这里按本地 control runtime 语义做窄化使用。
    */
-  run(params: {
+  execute(params: {
     query: string;
     onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
   }): Promise<SessionRunResult>;
@@ -44,7 +44,7 @@ const NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
 
 function encodeNdjsonLine(
   encoder: TextEncoder,
-  value: AgentSessionStreamEvent,
+  value: AgentUiChunkEvent,
 ): Uint8Array {
   return encoder.encode(`${JSON.stringify(value)}\n`);
 }
@@ -52,14 +52,14 @@ function encodeNdjsonLine(
 function resolveStreamEventFromUiChunk(params: {
   chunk: Parameters<NonNullable<SessionUiMessageChunkCallback>>[0];
   toolNameByCallId: Map<string, string>;
-}): AgentSessionStreamEvent | null {
+}): AgentUiChunkEvent | null {
   const { chunk, toolNameByCallId } = params;
   if (chunk.type === "tool-input-start") {
     toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
     return null;
   }
 
-  const event = mapUiMessageChunkToSdkEvent(chunk);
+  const event = mapUiMessageChunkToAgentEvent(chunk);
   if (!event) return null;
 
   if (event.type === "tool-call" || event.type === "tool-error") {
@@ -126,7 +126,7 @@ export async function createControlSessionStreamResponse(params: {
       void (async () => {
         const toolNameByCallId = new Map<string, string>();
 
-        const pushEvent = (event: AgentSessionStreamEvent): void => {
+        const pushEvent = (event: AgentUiChunkEvent): void => {
           controller.enqueue(encodeNdjsonLine(encoder, event));
         };
 
@@ -135,7 +135,7 @@ export async function createControlSessionStreamResponse(params: {
             text: executeInput,
           });
 
-          const result = await session.run({
+          const result = await session.execute({
             query: executeInput,
             onUiMessageChunkCallback: async (chunk) => {
               const event = resolveStreamEventFromUiChunk({

package/src/runtime/server/http/execute/execute.ts

@@ -94,7 +94,7 @@ export function createExecuteRouter(
         text: String(instructions),
       });
 
-      const result = await session.run({
+      const result = await session.execute({
         query: String(instructions),
       });
 

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

@@ -0,0 +1,22 @@
+/**
+ * SDK HTTP 路由入口模块。
+ *
+ * 关键点（中文）
+ * - 这里专门承载 `RemoteAgent` 对应的最小 SDK transport。
+ * - 路由面围绕 Session actor 公开能力展开，不混入 control UI 语义。
+ */
+
+import { Hono } from "hono";
+import type { AgentCore } from "@/core/AgentCore.js";
+import { registerSdkSessionRoutes } from "@/runtime/server/http/sdk/SessionRoutes.js";
+
+/**
+ * 创建 SDK HTTP router。
+ */
+export function createSdkRouter(
+  core: Pick<AgentCore, "session" | "sessions">,
+): Hono {
+  const router = new Hono();
+  registerSdkSessionRoutes(router, core);
+  return router;
+}

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;