@downcity/agent 1.1.22 → 1.1.23

package/src/sdk/Session.ts

@@ -3,12 +3,12 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、session 级模型配置、run/stream/fork 等高层 API。
+ * - 统一收口消息落盘、session 级模型配置、prompt/subscribe/fork 等高层 API。
  * - 内部继续复用 `Executor` / `JsonlSessionHistoryStore` / Composer 体系。
  */
 
 import { nanoid } from "nanoid";
-import type { LanguageModel, Tool } from "ai";
+import type { Tool } from "ai";
 import { Executor } from "@session/Executor.js";
 import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionHistoryStore } from "@/session/store/history/jsonl/JsonlSessionHistoryStore.js";
@@ -17,10 +17,7 @@ import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionMetadata,
-  AgentSessionRunInput,
-  AgentSessionRunResult,
   AgentSessionSetInput,
-  AgentSessionStreamEvent,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/sdk/AgentSdkTypes.js";
@@ -40,14 +37,29 @@ import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
 } from "@/sdk/session/index.js";
-import { AsyncQueue } from "@/sdk/AsyncQueue.js";
 import type { SessionPort } from "@/core/AgentContextTypes.js";
-import { pushUiMessageChunkAsSdkEvent } from "@/sdk/StreamEvents.js";
+import {
+  mapAgentEventToSessionEvent,
+  mapUiMessageChunkToAgentEvent,
+} from "@/sdk/SessionEventMapper.js";
 import {
   persistSdkAssistantResult,
   touchSessionMetadata,
 } from "@/sdk/session/index.js";
 import { createSessionServicePort } from "@/sdk/session/index.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import { SessionEventHub } from "@/sdk/session/runtime/SessionEventHub.js";
+import { SessionPromptRuntime } from "@/sdk/session/runtime/SessionPromptRuntime.js";
+import type {
+  SessionAssistantStepCallback,
+  SessionUiMessageChunkCallback,
+} from "@/session/types/SessionRun.js";
 
 type SessionOptions = {
   /**
@@ -120,12 +132,15 @@ export class Session {
   private readonly historyStore: JsonlSessionHistoryStore;
   private readonly historyComposer: JsonlSessionHistoryComposer;
   private readonly executor: Executor;
+  private readonly eventHub = new SessionEventHub();
+  private readonly promptRuntime: SessionPromptRuntime;
   private sessionConfig: AgentSessionConfigSnapshot = {};
   private createdAt = Date.now();
   private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
   private ensureConfiguredPromise: Promise<void> | null = null;
   private servicePort: SessionPort | null = null;
+  private directExecutionReserved = false;
 
   constructor(options: SessionOptions) {
     this.id = String(options.sessionId || "").trim();
@@ -189,6 +204,22 @@ export class Session {
       }),
       getTools: () => this.tools,
     });
+    this.promptRuntime = new SessionPromptRuntime({
+      sessionId: this.id,
+      publish: (event) => {
+        this.eventHub.publish(event);
+      },
+      createAndPersistUserMessage: async (query) => {
+        return await this.createAndPersistUserPromptMessage(query);
+      },
+      executeTurn: async ({ turnId, query, onStepMerge }) => {
+        return await this.executePromptTurn({
+          turnId,
+          query,
+          onStepMerge,
+        });
+      },
+    });
   }
 
   /**
@@ -259,6 +290,34 @@ export class Session {
     });
   }
 
+  /**
+   * 追加一条新的 Session prompt。
+   *
+   * 关键点（中文）
+   * - 这是 Session actor 模型下唯一的输入入口。
+   * - 首条输入、运行中补充输入、排到下一轮的输入，调用方式完全一致。
+   */
+  async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
+    const query = String(input.query || "").trim();
+    if (!query) {
+      throw new Error("session.prompt requires a non-empty query");
+    }
+    await this.ensureRunnable();
+    this.assertCanPrompt();
+    return await this.promptRuntime.prompt(query);
+  }
+
+  /**
+   * 订阅当前 Session 的未来事件。
+   *
+   * 关键点（中文）
+   * - 只广播订阅之后产生的事件。
+   * - 不做历史回放；历史仍通过 `history()` 读取。
+   */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
+    return this.eventHub.subscribe(subscriber);
+  }
+
   /**
    * 追加一条 user 文本消息。
    */
@@ -332,7 +391,11 @@ export class Session {
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean {
-    return this.executor.isExecuting();
+    return (
+      this.directExecutionReserved ||
+      this.promptRuntime.isActive() ||
+      this.executor.isExecuting()
+    );
   }
 
   /**
@@ -342,83 +405,6 @@ export class Session {
     this.executor.clearExecutor();
   }
 
-  /**
-   * 执行一轮非流式请求。
-   */
-  async run(input: AgentSessionRunInput): Promise<AgentSessionRunResult> {
-    const query = String(input.query || "").trim();
-    if (!query) {
-      throw new Error("session.run requires a non-empty query");
-    }
-    await this.ensureReadyForExecution();
-    if (!this.sessionConfig.model) {
-      throw new Error(
-        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
-      );
-    }
-    await this.appendUserMessage({ text: query });
-    const result = await this.executor.run({
-      query,
-    });
-    await this.persistAssistantResult(result.assistantMessage);
-    return {
-      success: result.success,
-      ...(result.error ? { error: result.error } : {}),
-      text: extractTextFromUiMessage(result.assistantMessage),
-      assistantMessage: result.assistantMessage,
-    };
-  }
-
-  /**
-   * 执行一轮流式请求。
-   */
-  async *stream(
-    input: AgentSessionRunInput,
-  ): AsyncIterable<AgentSessionStreamEvent> {
-    const query = String(input.query || "").trim();
-    if (!query) {
-      throw new Error("session.stream requires a non-empty query");
-    }
-    await this.ensureReadyForExecution();
-    if (!this.sessionConfig.model) {
-      throw new Error(
-        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
-      );
-    }
-    const queue = new AsyncQueue<AgentSessionStreamEvent>();
-    const toolNameByCallId = new Map<string, string>();
-    await this.appendUserMessage({ text: query });
-
-    const runPromise = (async () => {
-      try {
-        const result = await this.executor.run({
-          query,
-          onUiMessageChunkCallback: async (chunk) => {
-            pushUiMessageChunkAsSdkEvent({
-              queue,
-              chunk,
-              toolNameByCallId,
-            });
-          },
-        });
-        await this.persistAssistantResult(result.assistantMessage);
-      } catch (error) {
-        queue.push({
-          type: "error",
-          error: error instanceof Error ? error.message : String(error),
-        });
-      } finally {
-        queue.close();
-      }
-    })();
-
-    for await (const event of queue) {
-      yield event;
-    }
-
-    await runPromise;
-  }
-
   /**
    * 从当前 session 创建一个分叉会话。
    */
@@ -490,7 +476,29 @@ export class Session {
     if (this.servicePort) return this.servicePort;
     this.servicePort = createSessionServicePort({
       sessionId: this.id,
-      executor: this.executor,
+      getExecutor: () => this.executor.getExecutor(),
+      executeDirect: async (runParams) => {
+        return await this.executeDirect(runParams);
+      },
+      prompt: async (input) => {
+        return await this.prompt(input);
+      },
+      subscribe: (subscriber) => {
+        return this.subscribe(subscriber);
+      },
+      clearExecutor: () => {
+        this.executor.clearExecutor();
+      },
+      afterSessionUpdatedAsync: async () => {
+        await this.executor.afterSessionUpdatedAsync();
+      },
+      appendUserMessage: async (messageParams) => {
+        await this.executor.appendUserMessage(messageParams);
+      },
+      appendAssistantMessage: async (messageParams) => {
+        await this.executor.appendAssistantMessage(messageParams);
+      },
+      isExecuting: () => this.isExecuting(),
       historyStore: this.historyStore,
       ensureReadyForExecution: async () => {
         await this.ensureReadyForExecution();
@@ -523,6 +531,43 @@ export class Session {
     }
   }
 
+  private async ensureRunnable(): Promise<void> {
+    await this.ensureReadyForExecution();
+    if (!this.sessionConfig.model) {
+      throw new Error(
+        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
+      );
+    }
+  }
+
+  private assertCanPrompt(): void {
+    if (!this.directExecutionReserved && !this.executor.isExecuting()) {
+      return;
+    }
+    if (this.promptRuntime.isActive()) {
+      return;
+    }
+    throw new Error(
+      "session.prompt cannot attach to an active direct session execution. Use prompt()/subscribe() as the public interactive API, or wait for the current execution to finish.",
+    );
+  }
+
+  private beginDirectExecution(): void {
+    if (this.promptRuntime.isActive()) {
+      throw new Error(
+        "Direct session execution cannot start while session.prompt() is active. Keep SDK-facing interactive sessions on prompt()/subscribe(), or wait for the actor turn to finish.",
+      );
+    }
+    if (this.directExecutionReserved || this.executor.isExecuting()) {
+      throw new Error("Direct session execution does not support concurrent execution on the same session.");
+    }
+    this.directExecutionReserved = true;
+  }
+
+  private endDirectExecution(): void {
+    this.directExecutionReserved = false;
+  }
+
   private async touchMetadata(): Promise<void> {
     await touchSessionMetadata({
       projectRoot: this.projectRoot,
@@ -544,4 +589,108 @@ export class Session {
       assistantMessage,
     });
   }
+
+  private async createAndPersistUserPromptMessage(
+    query: string,
+  ): Promise<SessionUserMessageV1> {
+    const message = this.historyStore.userText({
+      text: String(query || "").trim(),
+      metadata: {
+        sessionId: this.id,
+      },
+    }) as SessionUserMessageV1;
+    await this.executor.appendUserMessage({
+      message,
+    });
+    await this.touchMetadata();
+    return message;
+  }
+
+  private async executePromptTurn(input: {
+    turnId: string;
+    query: string;
+    onStepMerge: () => Promise<SessionUserMessageV1[]>;
+  }): Promise<{
+    text: string;
+    success: boolean;
+    error?: string;
+  }> {
+    const toolNameByCallId = new Map<string, string>();
+    const result = await this.executor.run({
+      query: input.query,
+      onStepCallback: input.onStepMerge,
+      onUiMessageChunkCallback: async (chunk) => {
+        if (chunk.type === "tool-input-start") {
+          toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+          return;
+        }
+        const event = mapUiMessageChunkToAgentEvent(chunk);
+        if (!event) return;
+        const resolvedEvent =
+          (
+            event.type === "tool-result" ||
+            event.type === "tool-error"
+          ) &&
+          event.toolName === "unknown"
+            ? {
+                ...event,
+                toolName:
+                  toolNameByCallId.get(event.toolCallId) || event.toolName,
+              }
+            : event;
+        if (
+          resolvedEvent.type === "tool-call" ||
+          resolvedEvent.type === "tool-error"
+        ) {
+          toolNameByCallId.set(
+            resolvedEvent.toolCallId,
+            resolvedEvent.toolName,
+          );
+        }
+        const sessionEvent = mapAgentEventToSessionEvent({
+          event: resolvedEvent,
+          turnId: input.turnId,
+        });
+        if (sessionEvent) {
+          this.eventHub.publish(sessionEvent);
+        }
+      },
+    });
+    await this.persistAssistantResult(result.assistantMessage);
+    return {
+      text: extractTextFromUiMessage(result.assistantMessage),
+      success: result.success,
+      ...(result.error ? { error: result.error } : {}),
+    };
+  }
+
+  private async executeDirect(input: {
+    query: string;
+    onStepCallback?: () => Promise<SessionUserMessageV1[]>;
+    onAssistantStepCallback?: SessionAssistantStepCallback;
+    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
+  }) {
+    const query = String(input.query || "").trim();
+    if (!query) {
+      throw new Error("Session direct execution requires a non-empty query");
+    }
+    await this.ensureRunnable();
+    this.beginDirectExecution();
+    try {
+      return await this.executor.run({
+        query,
+        ...(typeof input.onStepCallback === "function"
+          ? { onStepCallback: input.onStepCallback }
+          : {}),
+        ...(typeof input.onAssistantStepCallback === "function"
+          ? { onAssistantStepCallback: input.onAssistantStepCallback }
+          : {}),
+        ...(typeof input.onUiMessageChunkCallback === "function"
+          ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
+          : {}),
+      });
+    } finally {
+      this.endDirectExecution();
+    }
+  }
 }

package/src/sdk/{StreamEvents.ts → SessionEventMapper.ts}

@@ -1,15 +1,15 @@
 /**
- * SDK Stream 事件映射辅助。
+ * Session 事件映射辅助。
  *
  * 关键点（中文）
- * - 把底层 AI SDK `UIMessageChunk` 归一到 `AgentSessionStreamEvent`。
- * - 仅保留 SDK 当前需要的稳定事件，不把所有底层细节直接暴露出去。
+ * - 把底层 AI SDK `UIMessageChunk` 归一到内部 `AgentUiChunkEvent`。
+ * - 再把内部 chunk 事件转换为 `session.subscribe()` 可见的 Session 事件。
  */
 
 import type { UIMessageChunk } from "ai";
 import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentSessionStreamEvent } from "@/sdk/AgentSdkTypes.js";
-import type { AsyncQueue } from "@/sdk/AsyncQueue.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentUiChunkEvent } from "@/types/sdk/AgentUiChunkEvent.js";
 
 function toJsonValue(value: unknown): JsonValue {
   if (value === undefined) return null;
@@ -29,11 +29,11 @@ function toJsonValue(value: unknown): JsonValue {
 }
 
 /**
- * 把单个 UI chunk 映射为 SDK stream 事件。
+ * 把单个 UI chunk 映射为内部 chunk 事件。
  */
-export function mapUiMessageChunkToSdkEvent(
+export function mapUiMessageChunkToAgentEvent(
   chunk: UIMessageChunk,
-): AgentSessionStreamEvent | null {
+): AgentUiChunkEvent | null {
   switch (chunk.type) {
     case "text-delta":
       return {
@@ -88,7 +88,7 @@ export function mapUiMessageChunkToSdkEvent(
     case "abort":
       return {
         type: "error",
-        error: String(chunk.reason || "stream aborted"),
+        error: String(chunk.reason || "execution aborted"),
       };
     default:
       return null;
@@ -96,43 +96,53 @@ export function mapUiMessageChunkToSdkEvent(
 }
 
 /**
- * 把 UI chunk 推入 SDK stream 队列。
+ * 把内部 chunk 事件映射为 Session actor 事件。
  *
  * 关键点（中文）
- * - `tool-output-*` chunk 本身不总是携带 toolName。
- * - 这里用调用 id 维护一次流式执行内的工具名称映射，避免上层重复关心底层 chunk 细节。
+ * - Session 级事件只保留 turn 维度所需的最小字段。
+ * - `finish` 与通用 `error` 由 turn 生命周期统一表达，不在这里直接透出。
  */
-export function pushUiMessageChunkAsSdkEvent(params: {
+export function mapAgentEventToSessionEvent(params: {
   /**
-   * SDK stream 事件队列。
+   * 当前内部 chunk 事件。
    */
-  queue: AsyncQueue<AgentSessionStreamEvent>;
+  event: AgentUiChunkEvent;
   /**
-   * 底层 AI SDK UI chunk。
+   * 当前 turn 标识。
    */
-  chunk: UIMessageChunk;
-  /**
-   * 当前 stream 生命周期内的 toolCallId 到 toolName 映射。
-   */
-  toolNameByCallId: Map<string, string>;
-}): void {
-  const { queue, chunk, toolNameByCallId } = params;
-  if (chunk.type === "tool-input-start") {
-    toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
-    return;
-  }
-  const event = mapUiMessageChunkToSdkEvent(chunk);
-  if (!event) return;
-  if (event.type === "tool-call" || event.type === "tool-error") {
-    toolNameByCallId.set(event.toolCallId, event.toolName);
-  }
-  if (
-    (event.type === "tool-result" || event.type === "tool-error") &&
-    event.toolName === "unknown"
-  ) {
-    const toolName = toolNameByCallId.get(event.toolCallId);
-    queue.push(toolName ? { ...event, toolName } : event);
-    return;
+  turnId: string;
+}): AgentSessionEvent | null {
+  const { event, turnId } = params;
+  switch (event.type) {
+    case "text-delta":
+      return {
+        type: "text-delta",
+        turnId,
+        text: event.text,
+      };
+    case "reasoning-delta":
+      return {
+        type: "reasoning-delta",
+        turnId,
+        text: event.text,
+      };
+    case "tool-call":
+      return {
+        type: "tool-call",
+        turnId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        args: event.args,
+      };
+    case "tool-result":
+      return {
+        type: "tool-result",
+        turnId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        result: event.result,
+      };
+    default:
+      return null;
   }
-  queue.push(event);
 }

package/src/sdk/session/ServicePort.ts

@@ -2,12 +2,24 @@
  * SDK Session service 端口构造器。
  *
  * 关键点（中文）
- * - 把 SDK 本地 session 适配成 chat service 依赖的 `SessionPort`。
- * - service 侧直接复用底层 `Executor` 协议，避免 SDK `run()` 包装层重复补写消息。
+ * - 把 SDK 本地 session 适配成 runtime / service 依赖的 `SessionPort`。
+ * - SDK 公开面只保留 `prompt()` / `subscribe()`；内部单轮执行原语仍通过这里暴露给 service/runtime。
  */
 
 import type { SessionPort } from "@/core/AgentContextTypes.js";
 import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+import type { SessionRunResult } from "@/session/types/SessionRun.js";
+import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type {
+  SessionAssistantStepCallback,
+  SessionUiMessageChunkCallback,
+} from "@/session/types/SessionRun.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";
 
 /**
  * 构造 SDK SessionPort 的参数。
@@ -18,9 +30,52 @@ export interface CreateSessionServicePortParams {
    */
   sessionId: string;
   /**
-   * 底层执行编排器。
+   * 读取当前 session 底层执行端口。
    */
-  executor: Omit<SessionPort, "sessionId" | "getHistoryStore">;
+  getExecutor: SessionPort["getExecutor"];
+  /**
+   * 运行一次内部 direct execution。
+   *
+   * 关键点（中文）
+   * - 这是 runtime / service 侧保留的内部原语。
+   * - 它不属于 SDK 用户推荐直接调用的公开模式。
+   */
+  executeDirect: (params: {
+    query: string;
+    onStepCallback?: () => Promise<SessionUserMessageV1[]>;
+    onAssistantStepCallback?: SessionAssistantStepCallback;
+    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
+  }) => Promise<SessionRunResult>;
+  /**
+   * 追加一条新的 session prompt。
+   */
+  prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
+  /**
+   * 订阅当前 session 的 future 事件。
+   */
+  subscribe: (
+    subscriber: AgentSessionSubscriber,
+  ) => AgentSessionUnsubscribe;
+  /**
+   * 清理当前 session executor 状态。
+   */
+  clearExecutor: () => void;
+  /**
+   * session 更新后的异步通知回调。
+   */
+  afterSessionUpdatedAsync: () => Promise<void>;
+  /**
+   * 追加 user 消息到底层历史。
+   */
+  appendUserMessage: SessionPort["appendUserMessage"];
+  /**
+   * 追加 assistant 消息到底层历史。
+   */
+  appendAssistantMessage: SessionPort["appendAssistantMessage"];
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting: () => boolean;
   /**
    * 当前 session 历史持久化端口。
    */
@@ -43,26 +98,33 @@ export function createSessionServicePort(
 ): SessionPort {
   return {
     sessionId: params.sessionId,
-    getExecutor: () => params.executor.getExecutor(),
+    getExecutor: () => params.getExecutor(),
     getHistoryStore: () => params.historyStore,
-    run: async (runParams) => {
+    execute: async (runParams) => {
+      await params.ensureReadyForExecution();
+      return await params.executeDirect(runParams);
+    },
+    prompt: async (input) => {
       await params.ensureReadyForExecution();
-      return await params.executor.run(runParams);
+      return await params.prompt(input);
+    },
+    subscribe: (subscriber) => {
+      return params.subscribe(subscriber);
     },
     clearExecutor: () => {
-      params.executor.clearExecutor();
+      params.clearExecutor();
     },
     afterSessionUpdatedAsync: async () => {
-      await params.executor.afterSessionUpdatedAsync();
+      await params.afterSessionUpdatedAsync();
     },
     appendUserMessage: async (messageParams) => {
-      await params.executor.appendUserMessage(messageParams);
+      await params.appendUserMessage(messageParams);
       await params.touchMetadata();
     },
     appendAssistantMessage: async (messageParams) => {
-      await params.executor.appendAssistantMessage(messageParams);
+      await params.appendAssistantMessage(messageParams);
       await params.touchMetadata();
     },
-    isExecuting: () => params.executor.isExecuting(),
+    isExecuting: () => params.isExecuting(),
   };
 }