@downcity/agent 1.1.21 → 1.1.23

package/scripts/session-prompt-runtime.test.mjs

@@ -0,0 +1,167 @@
+/**
+ * @file 验证 SessionPromptRuntime 的 actor 队列语义。
+ *
+ * 关键点（中文）
+ * - 测试编译后的 bin 输出，避免把测试文件混入 package 源码导出面。
+ * - 重点锁住 prompt merge 与排队到下一 turn 的行为，防止后续重构破坏交互模型。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { SessionPromptRuntime } from "../bin/sdk/session/runtime/SessionPromptRuntime.js";
+
+function createDeferred() {
+  let resolve;
+  const promise = new Promise((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {
+    promise,
+    resolve,
+  };
+}
+
+function createUserMessage(query, index) {
+  return {
+    id: `u:test:${String(index)}`,
+    role: "user",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: "test",
+      source: "sdk",
+      kind: "normal",
+    },
+    parts: [{ type: "text", text: query }],
+  };
+}
+
+async function waitUntil(readValue) {
+  for (let index = 0; index < 20; index += 1) {
+    const value = readValue();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  throw new Error("Timed out while waiting for test condition");
+}
+
+async function isSettled(promise) {
+  const marker = {};
+  const result = await Promise.race([
+    promise.then(
+      () => true,
+      () => true,
+    ),
+    new Promise((resolve) => setTimeout(() => resolve(marker), 0)),
+  ]);
+  return result !== marker;
+}
+
+test("SessionPromptRuntime merges queued prompts at the next step boundary", async () => {
+  const events = [];
+  const persisted = [];
+  const executionFinished = createDeferred();
+  let stepMerge = null;
+
+  const runtime = new SessionPromptRuntime({
+    sessionId: "test",
+    publish: (event) => {
+      events.push(event);
+    },
+    createAndPersistUserMessage: async (query) => {
+      const message = createUserMessage(query, persisted.length + 1);
+      persisted.push(message);
+      return message;
+    },
+    executeTurn: async (input) => {
+      stepMerge = input.onStepMerge;
+      await executionFinished.promise;
+      return {
+        text: "done",
+        success: true,
+      };
+    },
+  });
+
+  const firstTurn = await runtime.prompt("first");
+  const secondTurnPromise = runtime.prompt("second");
+  const merge = await waitUntil(() => stepMerge);
+
+  assert.equal(await isSettled(secondTurnPromise), false);
+
+  const mergedMessages = await merge();
+  const secondTurn = await secondTurnPromise;
+
+  assert.equal(secondTurn.id, firstTurn.id);
+  assert.deepEqual(
+    mergedMessages.map((message) => message.parts[0]?.text),
+    ["second"],
+  );
+  assert.deepEqual(
+    persisted.map((message) => message.parts[0]?.text),
+    ["first", "second"],
+  );
+
+  executionFinished.resolve();
+  const result = await firstTurn.finished;
+
+  assert.equal(result.success, true);
+  assert.equal(result.text, "done");
+  assert.equal(secondTurn.result, result);
+  assert.deepEqual(
+    events.map((event) => event.type),
+    ["turn-start", "turn-finish"],
+  );
+});
+
+test("SessionPromptRuntime moves unmerged prompts into the next turn", async () => {
+  const events = [];
+  const finishQueue = [];
+
+  const runtime = new SessionPromptRuntime({
+    sessionId: "test",
+    publish: (event) => {
+      events.push(event);
+    },
+    createAndPersistUserMessage: async (query) => {
+      return createUserMessage(query, events.length + 1);
+    },
+    executeTurn: async (input) => {
+      const deferred = createDeferred();
+      finishQueue.push({
+        query: input.query,
+        deferred,
+      });
+      await deferred.promise;
+      return {
+        text: `done:${input.query}`,
+        success: true,
+      };
+    },
+  });
+
+  const firstTurn = await runtime.prompt("first");
+  const secondTurnPromise = runtime.prompt("second");
+  const firstExecution = await waitUntil(() => finishQueue[0]);
+
+  assert.equal(await isSettled(secondTurnPromise), false);
+
+  firstExecution.deferred.resolve();
+  const firstResult = await firstTurn.finished;
+  const secondTurn = await secondTurnPromise;
+  const secondExecution = await waitUntil(() => finishQueue[1]);
+
+  assert.notEqual(secondTurn.id, firstTurn.id);
+  assert.equal(firstResult.text, "done:first");
+  assert.equal(secondExecution.query, "second");
+
+  secondExecution.deferred.resolve();
+  const secondResult = await secondTurn.finished;
+
+  assert.equal(secondResult.text, "done:second");
+  assert.deepEqual(
+    events.map((event) => event.type),
+    ["turn-start", "turn-finish", "turn-start", "turn-finish"],
+  );
+});

package/src/core/AgentContextTypes.ts

@@ -34,6 +34,12 @@ import type {
   SessionRunResult,
 } from "@/session/types/SessionRun.js";
 import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
  * 跨 service 调用参数。
@@ -116,9 +122,9 @@ export interface SessionPort {
    */
   getHistoryStore(): SessionHistoryStore;
   /**
-   * 执行当前 session 的一次请求。
+   * 执行当前 session 的一次内部请求。
    */
-  run(params: {
+  execute(params: {
     /**
      * 本轮输入文本。
      */
@@ -132,6 +138,22 @@ export interface SessionPort {
      */
     onAssistantStepCallback?: SessionAssistantStepCallback;
   }): Promise<SessionRunResult>;
+  /**
+   * 向当前 session actor 追加一条新的 prompt。
+   *
+   * 关键点（中文）
+   * - 这是面向 SDK / transport 的统一交互输入入口。
+   * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
+   */
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+  /**
+   * 订阅当前 session 后续产生的 future 事件。
+   *
+   * 关键点（中文）
+   * - 只广播订阅之后产生的事件。
+   * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
+   */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
   /**
    * 清理当前 session 的 executor 缓存。
    */

package/src/index.ts

@@ -24,15 +24,23 @@ export type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionMetadata,
-  AgentSessionRunInput,
-  AgentSessionRunResult,
   AgentSessionSetInput,
-  AgentSessionStreamEvent,
   AgentSessionSystemBlock,
   AgentSessionSystemBlockSource,
   AgentSessionSystemSessionInfo,
   AgentSessionSystemSnapshot,
 } from "./sdk/AgentSdkTypes.js";
+export type {
+  AgentSessionEvent,
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "./types/sdk/AgentSessionEvent.js";
+export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
+export type {
+  AgentSessionTurnHandle,
+  AgentSessionTurnResult,
+} from "./types/sdk/AgentSessionTurn.js";
+export type { AgentUiChunkEvent } from "./types/sdk/AgentUiChunkEvent.js";
 export type {
   AgentRuntime as AgentCoreRuntime,
   AgentRuntimeBase as AgentCoreRuntimeBase,

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,
+      );
+    }
+  });
+}