@downcity/agent 1.1.22 → 1.1.23

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

@@ -0,0 +1,160 @@
+/**
+ * Agent Session 事件类型定义。
+ *
+ * 关键点（中文）
+ * - `subscribe()` 暴露的是 session 级长期事件序列，而不是单次执行的局部结果。
+ * - 事件只表达“当前 turn 正在发生什么”，不负责历史回放。
+ */
+import type { JsonValue } from "../../types/common/Json.js";
+/**
+ * 单个 turn 开始事件。
+ */
+export interface AgentSessionTurnStartEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "turn-start";
+    /**
+     * 当前 turn 的稳定标识。
+     *
+     * 说明（中文）
+     * - 同一个 turn 内的全部增量事件都会复用这个 turnId。
+     * - 当 Session 排队进入下一轮时，会生成新的 turnId。
+     */
+    turnId: string;
+}
+/**
+ * 普通文本增量事件。
+ */
+export interface AgentSessionTextDeltaEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "text-delta";
+    /**
+     * 当前文本所属 turn。
+     */
+    turnId: string;
+    /**
+     * 当前这次新增的可见文本片段。
+     */
+    text: string;
+}
+/**
+ * reasoning 文本增量事件。
+ */
+export interface AgentSessionReasoningDeltaEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "reasoning-delta";
+    /**
+     * 当前 reasoning 所属 turn。
+     */
+    turnId: string;
+    /**
+     * 当前这次新增的 reasoning 文本片段。
+     */
+    text: string;
+}
+/**
+ * 工具调用事件。
+ */
+export interface AgentSessionToolCallEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "tool-call";
+    /**
+     * 当前工具调用所属 turn。
+     */
+    turnId: string;
+    /**
+     * 当前工具调用唯一标识。
+     */
+    toolCallId: string;
+    /**
+     * 当前工具名称。
+     */
+    toolName: string;
+    /**
+     * 当前工具输入参数。
+     */
+    args: JsonValue;
+}
+/**
+ * 工具结果事件。
+ */
+export interface AgentSessionToolResultEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "tool-result";
+    /**
+     * 当前工具结果所属 turn。
+     */
+    turnId: string;
+    /**
+     * 当前工具调用唯一标识。
+     */
+    toolCallId: string;
+    /**
+     * 当前工具名称。
+     */
+    toolName: string;
+    /**
+     * 当前工具输出结果。
+     */
+    result: JsonValue;
+}
+/**
+ * 单个 turn 完成事件。
+ */
+export interface AgentSessionTurnFinishEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "turn-finish";
+    /**
+     * 当前已完成 turn 的稳定标识。
+     */
+    turnId: string;
+    /**
+     * 当前 turn 最终可见文本。
+     */
+    text: string;
+    /**
+     * 当前 turn 是否成功结束。
+     */
+    success: boolean;
+    /**
+     * 当前 turn 失败时的错误文本。
+     */
+    error?: string;
+}
+/**
+ * Session 级错误事件。
+ */
+export interface AgentSessionErrorEvent {
+    /**
+     * 当前事件类型。
+     */
+    type: "error";
+    /**
+     * 当前错误文本。
+     */
+    message: string;
+}
+/**
+ * Session 订阅可见事件联合类型。
+ */
+export type AgentSessionEvent = AgentSessionTurnStartEvent | AgentSessionTextDeltaEvent | AgentSessionReasoningDeltaEvent | AgentSessionToolCallEvent | AgentSessionToolResultEvent | AgentSessionTurnFinishEvent | AgentSessionErrorEvent;
+/**
+ * Session 事件订阅回调。
+ */
+export type AgentSessionSubscriber = (event: AgentSessionEvent) => void;
+/**
+ * 取消 Session 订阅的返回函数。
+ */
+export type AgentSessionUnsubscribe = () => void;
+//# sourceMappingURL=AgentSessionEvent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionEvent.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionEvent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC;IAEnB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAC;IAExB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC;IAEpB;;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;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,0BAA0B,GAC1B,+BAA+B,GAC/B,yBAAyB,GACzB,2BAA2B,GAC3B,2BAA2B,GAC3B,sBAAsB,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,IAAI,CAAC"}

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/AgentUiChunkEvent.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent UI chunk 事件类型定义。
+ *
+ * 关键点（中文）
+ * - 这是内部传输/映射层事件，不是 Session 的公开订阅事件。
+ * - 它用于把底层 AI SDK `UIMessageChunk` 归一化，再按不同宿主场景转成最终输出。
+ */
+import type { JsonValue } from "../../types/common/Json.js";
+/**
+ * 内部 UI chunk 事件。
+ */
+export type AgentUiChunkEvent = {
+    /**
+     * 文本增量事件。
+     */
+    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=AgentUiChunkEvent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentUiChunkEvent.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentUiChunkEvent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB;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/AgentUiChunkEvent.js

@@ -0,0 +1,9 @@
+/**
+ * Agent UI chunk 事件类型定义。
+ *
+ * 关键点（中文）
+ * - 这是内部传输/映射层事件，不是 Session 的公开订阅事件。
+ * - 它用于把底层 AI SDK `UIMessageChunk` 归一化，再按不同宿主场景转成最终输出。
+ */
+export {};
+//# sourceMappingURL=AgentUiChunkEvent.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.22",
+  "version": "1.1.23",
   "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,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,