@downcity/agent 1.1.22 → 1.1.25

package/bin/types/sdk/AgentSessionEvent.js

@@ -0,0 +1,9 @@
+/**
+ * Agent Session 事件类型定义。
+ *
+ * 关键点（中文）
+ * - `subscribe()` 暴露的是 session 级长期事件序列，而不是单次执行的局部结果。
+ * - 事件只表达“当前 turn 正在发生什么”，不负责历史回放。
+ */
+export {};
+//# sourceMappingURL=AgentSessionEvent.js.map

package/bin/types/sdk/AgentSessionEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionEvent.js","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionEvent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/sdk/AgentSessionPrompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent Session prompt 输入类型定义。
+ *
+ * 关键点（中文）
+ * - `prompt()` 是 Session actor 模型下唯一的输入入口。
+ * - 首条输入、运行中补充输入、排队到下一轮的输入，调用侧都使用同一结构。
+ */
+/**
+ * Session prompt 输入。
+ */
+export interface AgentSessionPromptInput {
+    /**
+     * 当前这次要追加到 Session 的用户文本。
+     *
+     * 说明（中文）
+     * - 调用侧永远只传“新的用户输入”。
+     * - 它是否并入当前 turn，还是排到下一 turn，由 Session 内部决定。
+     */
+    query: string;
+}
+//# sourceMappingURL=AgentSessionPrompt.d.ts.map

package/bin/types/sdk/AgentSessionPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionPrompt.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;CACf"}

package/bin/types/sdk/AgentSessionPrompt.js

@@ -0,0 +1,9 @@
+/**
+ * Agent Session prompt 输入类型定义。
+ *
+ * 关键点（中文）
+ * - `prompt()` 是 Session actor 模型下唯一的输入入口。
+ * - 首条输入、运行中补充输入、排队到下一轮的输入，调用侧都使用同一结构。
+ */
+export {};
+//# sourceMappingURL=AgentSessionPrompt.js.map

package/bin/types/sdk/AgentSessionPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionPrompt.js","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/sdk/AgentSessionTurn.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Agent Session turn 句柄与结果类型定义。
+ *
+ * 关键点（中文）
+ * - `session.prompt()` 返回的是“已绑定到某个 turn”的句柄，而不是一次性文本结果。
+ * - 同一个 turn 可以吸收多条 prompt，因此多个 prompt 可能返回相同 `id` 的 turn handle。
+ * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
+ */
+/**
+ * 单个 Session turn 的最终结果。
+ */
+export interface AgentSessionTurnResult {
+    /**
+     * 当前已完成 turn 的稳定标识。
+     */
+    turnId: string;
+    /**
+     * 当前 turn 最终可见文本。
+     */
+    text: string;
+    /**
+     * 当前 turn 是否成功结束。
+     */
+    success: boolean;
+    /**
+     * 当前 turn 失败时的错误文本。
+     */
+    error?: string;
+}
+/**
+ * 单个 Session turn 的等待句柄。
+ */
+export interface AgentSessionTurnHandle {
+    /**
+     * 当前句柄绑定到的 turnId。
+     *
+     * 说明（中文）
+     * - `prompt()` 只有在确定当前输入被并入哪个 turn 后才会返回。
+     * - 因此这里总是最终可用的 turnId，而不是临时 receipt id。
+     */
+    id: string;
+    /**
+     * 当前 turn 已完成后的最终结果快照。
+     *
+     * 说明（中文）
+     * - 在 `finished` 兑现之前这里为 `null`。
+     * - 兑现之后会变成与 `finished` 相同的最终结果对象。
+     */
+    result: AgentSessionTurnResult | null;
+    /**
+     * 等待当前 turn 完成的 Promise。
+     *
+     * 关键点（中文）
+     * - 这里无论 turn 成功还是失败都会 resolve。
+     * - 调用方应读取返回结果中的 `success` / `error` 判断最终状态。
+     */
+    finished: Promise<AgentSessionTurnResult>;
+}
+//# sourceMappingURL=AgentSessionTurn.d.ts.map

package/bin/types/sdk/AgentSessionTurn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionTurn.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionTurn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;OAMG;IACH,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEtC;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC3C"}

package/bin/types/sdk/AgentSessionTurn.js

@@ -0,0 +1,10 @@
+/**
+ * Agent Session turn 句柄与结果类型定义。
+ *
+ * 关键点（中文）
+ * - `session.prompt()` 返回的是“已绑定到某个 turn”的句柄，而不是一次性文本结果。
+ * - 同一个 turn 可以吸收多条 prompt，因此多个 prompt 可能返回相同 `id` 的 turn handle。
+ * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
+ */
+export {};
+//# sourceMappingURL=AgentSessionTurn.js.map

package/bin/types/sdk/AgentSessionTurn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionTurn.js","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionTurn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/types/sdk/InternalUiChunkEvent.d.ts

@@ -0,0 +1,100 @@
+/**
+ * SDK 内部 UI chunk 事件类型定义。
+ *
+ * 关键点（中文）
+ * - 这是 Session 事件映射器的内部中间态，不从包根入口导出。
+ * - 它只负责承接底层 AI SDK `UIMessageChunk`，再转成 `AgentSessionEvent`。
+ */
+import type { JsonValue } from "../../types/common/Json.js";
+/**
+ * SDK 内部 UI chunk 事件。
+ */
+export type InternalUiChunkEvent = {
+    /**
+     * 文本增量事件。
+     */
+    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;
+};
+//# sourceMappingURL=InternalUiChunkEvent.d.ts.map

package/bin/types/sdk/InternalUiChunkEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalUiChunkEvent.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/InternalUiChunkEvent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC;CACjB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;CACnB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC;IACnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC"}

package/bin/types/sdk/InternalUiChunkEvent.js

@@ -0,0 +1,9 @@
+/**
+ * SDK 内部 UI chunk 事件类型定义。
+ *
+ * 关键点（中文）
+ * - 这是 Session 事件映射器的内部中间态，不从包根入口导出。
+ * - 它只负责承接底层 AI SDK `UIMessageChunk`，再转成 `AgentSessionEvent`。
+ */
+export {};
+//# sourceMappingURL=InternalUiChunkEvent.js.map

package/bin/types/sdk/InternalUiChunkEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalUiChunkEvent.js","sourceRoot":"","sources":["../../../src/types/sdk/InternalUiChunkEvent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.22",
+  "version": "1.1.25",
   "type": "module",
   "description": "Downcity Agent 运行时 — 执行壳，通过 RPC/HTTP 调用 City 的能力",
   "main": "./bin/index.js",
@@ -45,6 +45,7 @@
   "scripts": {
     "build": "node scripts/agent-compiler.mjs build",
     "dev": "node scripts/agent-compiler.mjs dev",
+    "test:session-runtime": "pnpm build && node --test scripts/session-prompt-runtime.test.mjs",
     "typecheck": "node scripts/agent-compiler.mjs typecheck"
   }
 }

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,22 +24,25 @@ export type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionMetadata,
-  AgentSessionRunInput,
-  AgentSessionRunResult,
   AgentSessionSetInput,
-  AgentSessionStreamEvent,
   AgentSessionSystemBlock,
   AgentSessionSystemBlockSource,
   AgentSessionSystemSessionInfo,
   AgentSessionSystemSnapshot,
 } from "./sdk/AgentSdkTypes.js";
 export type {
-  AgentRuntime as AgentCoreRuntime,
-  AgentRuntimeBase as AgentCoreRuntimeBase,
-} from "./core/AgentCoreTypes.js";
+  AgentSessionEvent,
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "./types/sdk/AgentSessionEvent.js";
+export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
 export type {
-  AgentContext as AgentContext,
-  AgentContext as AgentCoreContext,
+  AgentSessionTurnHandle,
+  AgentSessionTurnResult,
+} from "./types/sdk/AgentSessionTurn.js";
+export type { AgentRuntime, AgentRuntimeBase } from "./core/AgentCoreTypes.js";
+export type {
+  AgentContext,
   ChatRuntimePort,
   InvokeServicePort,
   SessionCollectionPort,

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/SessionRoutes.ts

@@ -30,7 +30,6 @@ import {
   toUiMessageTimeline,
 } from "./Helpers.js";
 import { executeBySessionId } from "./ExecuteBySession.js";
-import { createControlSessionStreamResponse } from "./StreamBySession.js";
 const CONSOLEUI_SESSION_ID = "consoleui-chat-main";
 
 function normalizeSystemText(input: string | null | undefined): string {
@@ -413,30 +412,4 @@ export function registerControlSessionRoutes(
     });
   }
 
-  for (const routePath of buildControlRouteAliases("/sessions/:sessionId/stream")) {
-    app.post(routePath, async (c) => {
-      try {
-        const runtime = params.getAgentRuntime();
-        const sessionId = decodeMaybe(String(c.req.param("sessionId") || "").trim());
-        const body = (await c.req.json().catch(() => ({}))) as Partial<ControlSessionExecuteRequestBody>;
-        const instructions = String(body.instructions || "").trim();
-        if (!sessionId) {
-          return c.json({ success: false, error: "Missing sessionId" }, 400);
-        }
-        if (!instructions) {
-          return c.json({ success: false, error: "Missing instructions" }, 400);
-        }
-
-        return await createControlSessionStreamResponse({
-          agentState: runtime,
-          executionContext: params.getAgentContext(),
-          sessionId,
-          instructions,
-          attachments: Array.isArray(body.attachments) ? body.attachments : undefined,
-        });
-      } catch (error) {
-        return c.json({ success: false, error: String(error) }, 500);
-      }
-    });
-  }
 }

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