@downcity/agent 1.1.22 → 1.1.25

package/src/sdk/session/runtime/SessionEventHub.ts

@@ -0,0 +1,47 @@
+/**
+ * SessionEventHub：Session 级事件分发器。
+ *
+ * 关键点（中文）
+ * - 收口 `Session.subscribe()` 的订阅/取消订阅能力。
+ * - 只做未来事件广播，不做缓存、重放或背压管理。
+ */
+
+import type {
+  AgentSessionEvent,
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+
+/**
+ * SessionEventHub：最小事件总线实现。
+ */
+export class SessionEventHub {
+  private readonly subscribers = new Map<number, AgentSessionSubscriber>();
+  private nextSubscriberId = 1;
+
+  /**
+   * 注册一个新的 Session 事件订阅者。
+   */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
+    const id = this.nextSubscriberId;
+    this.nextSubscriberId += 1;
+    this.subscribers.set(id, subscriber);
+
+    return () => {
+      this.subscribers.delete(id);
+    };
+  }
+
+  /**
+   * 广播一条 Session 事件。
+   */
+  publish(event: AgentSessionEvent): void {
+    for (const subscriber of this.subscribers.values()) {
+      try {
+        subscriber(event);
+      } catch {
+        // ignore single subscriber failures
+      }
+    }
+  }
+}

package/src/sdk/session/runtime/SessionPromptRuntime.ts

@@ -0,0 +1,269 @@
+/**
+ * SessionPromptRuntime：Session actor 模式下的最小 prompt 调度器。
+ *
+ * 关键点（中文）
+ * - `prompt()` 是唯一输入入口，内部决定并入当前 turn 还是排到下一 turn。
+ * - 不把调度逻辑塞进 Executor；Executor 继续只负责单次执行。
+ * - 这里不暴露历史或消息模型，只编排 prompt 队列与 turn 生命周期。
+ */
+
+import { nanoid } from "nanoid";
+import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type {
+  AgentSessionTurnHandle,
+  AgentSessionTurnResult,
+} from "@/types/sdk/AgentSessionTurn.js";
+
+type QueuedPrompt = {
+  /**
+   * 当前排队中的用户文本。
+   */
+  query: string;
+
+  /**
+   * 当前 prompt 对应的 turn handle Promise 控制器。
+   */
+  deferredHandle: Deferred<AgentSessionTurnHandle>;
+};
+
+/**
+ * Promise 延迟控制器。
+ */
+interface Deferred<T> {
+  /**
+   * 延迟 Promise。
+   */
+  promise: Promise<T>;
+
+  /**
+   * 兑现 Promise。
+   */
+  resolve: (value: T) => void;
+}
+
+/**
+ * 当前活跃 turn 的运行态。
+ */
+interface ActiveTurnState {
+  /**
+   * 当前 turnId。
+   */
+  turnId: string;
+
+  /**
+   * 当前 turn 的最终结果快照。
+   */
+  result: AgentSessionTurnResult | null;
+
+  /**
+   * 当前 turn 完成 Promise 控制器。
+   */
+  deferredFinished: Deferred<AgentSessionTurnResult>;
+}
+
+/**
+ * SessionPromptRuntime 构造参数。
+ */
+export interface SessionPromptRuntimeOptions {
+  /**
+   * 当前 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * 广播 session 事件。
+   */
+  publish: (event: AgentSessionEvent) => void;
+
+  /**
+   * 构造并持久化一条 user 消息。
+   */
+  createAndPersistUserMessage: (query: string) => Promise<SessionUserMessageV1>;
+
+  /**
+   * 执行单轮 turn。
+   */
+  executeTurn: (input: {
+    turnId: string;
+    query: string;
+    onStepMerge: () => Promise<SessionUserMessageV1[]>;
+  }) => Promise<{
+    text: string;
+    success: boolean;
+    error?: string;
+  }>;
+}
+
+/**
+ * SessionPromptRuntime：最小 prompt 队列调度器。
+ */
+export class SessionPromptRuntime {
+  private readonly sessionId: string;
+  private readonly publish: SessionPromptRuntimeOptions["publish"];
+  private readonly createAndPersistUserMessage: SessionPromptRuntimeOptions["createAndPersistUserMessage"];
+  private readonly executeTurn: SessionPromptRuntimeOptions["executeTurn"];
+  private readonly queue: QueuedPrompt[] = [];
+  private processingPromise: Promise<void> | null = null;
+
+  constructor(options: SessionPromptRuntimeOptions) {
+    this.sessionId = String(options.sessionId || "").trim();
+    this.publish = options.publish;
+    this.createAndPersistUserMessage = options.createAndPersistUserMessage;
+    this.executeTurn = options.executeTurn;
+    if (!this.sessionId) {
+      throw new Error("SessionPromptRuntime requires a non-empty sessionId");
+    }
+  }
+
+  /**
+   * 追加一条新的 prompt。
+   */
+  prompt(query: string): Promise<AgentSessionTurnHandle> {
+    const deferredHandle = createDeferred<AgentSessionTurnHandle>();
+    this.queue.push({
+      query: String(query || "").trim(),
+      deferredHandle,
+    });
+    this.ensureProcessing();
+    return deferredHandle.promise;
+  }
+
+  /**
+   * 返回当前 actor prompt 调度器是否仍处于活跃态。
+   *
+   * 说明（中文）
+   * - 只要还有排队 prompt，或处理循环尚未结束，就视为活跃。
+   * - Session 会用它阻止内部 direct execution 与 actor 模式并发混用。
+   */
+  isActive(): boolean {
+    return this.processingPromise !== null || this.queue.length > 0;
+  }
+
+  private ensureProcessing(): void {
+    if (this.processingPromise) return;
+    this.processingPromise = this.processLoop().finally(() => {
+      this.processingPromise = null;
+      if (this.queue.length > 0) {
+        this.ensureProcessing();
+      }
+    });
+  }
+
+  private async processLoop(): Promise<void> {
+    while (this.queue.length > 0) {
+      const current = this.queue.shift();
+      if (!current) break;
+
+      const turnId = `turn:${this.sessionId}:${Date.now()}:${nanoid(6)}`;
+      const activeTurn = createActiveTurnState(turnId);
+      this.publish({
+        type: "turn-start",
+        turnId,
+      });
+      current.deferredHandle.resolve(createTurnHandle(activeTurn));
+
+      try {
+        await this.createAndPersistUserMessage(current.query);
+        const result = await this.executeTurn({
+          turnId,
+          query: current.query,
+          onStepMerge: async () => {
+            return await this.drainQueuedPromptsAsMessages(activeTurn);
+          },
+        });
+        const finalResult: AgentSessionTurnResult = {
+          turnId,
+          text: result.text,
+          success: result.success,
+          ...(result.error ? { error: result.error } : {}),
+        };
+        activeTurn.result = finalResult;
+        this.publish({
+          type: "turn-finish",
+          turnId,
+          text: finalResult.text,
+          success: finalResult.success,
+          ...(finalResult.error ? { error: finalResult.error } : {}),
+        });
+        activeTurn.deferredFinished.resolve(finalResult);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const finalResult: AgentSessionTurnResult = {
+          turnId,
+          text: "",
+          success: false,
+          error: message,
+        };
+        activeTurn.result = finalResult;
+        this.publish({
+          type: "error",
+          message,
+        });
+        this.publish({
+          type: "turn-finish",
+          turnId,
+          text: "",
+          success: false,
+          error: message,
+        });
+        activeTurn.deferredFinished.resolve(finalResult);
+      }
+    }
+  }
+
+  private async drainQueuedPromptsAsMessages(
+    activeTurn: ActiveTurnState,
+  ): Promise<SessionUserMessageV1[]> {
+    if (this.queue.length <= 0) return [];
+    const drained = this.queue.splice(0, this.queue.length);
+    const merged: SessionUserMessageV1[] = [];
+
+    for (let index = 0; index < drained.length; index += 1) {
+      const item = drained[index];
+      try {
+        const message = await this.createAndPersistUserMessage(item.query);
+        item.deferredHandle.resolve(createTurnHandle(activeTurn));
+        merged.push(message);
+      } catch {
+        // 关键点（中文）：若某条消息持久化失败，把未处理部分重新放回队列头部，避免静默丢失。
+        const remaining = drained.slice(index);
+        this.queue.unshift(...remaining);
+        break;
+      }
+    }
+
+    return merged;
+  }
+}
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {
+    promise,
+    resolve,
+  };
+}
+
+function createActiveTurnState(turnId: string): ActiveTurnState {
+  return {
+    turnId,
+    result: null,
+    deferredFinished: createDeferred<AgentSessionTurnResult>(),
+  };
+}
+
+function createTurnHandle(
+  activeTurn: ActiveTurnState,
+): AgentSessionTurnHandle {
+  return {
+    id: activeTurn.turnId,
+    get result() {
+      return activeTurn.result;
+    },
+    finished: activeTurn.deferredFinished.promise,
+  };
+}

package/src/service/builtins/chat/runtime/ChatQueueWorker.ts

@@ -371,7 +371,7 @@ export class ChatQueueWorker {
     const typing = this.startTypingHeartbeat(runItem);
     let result: SessionRunResult;
     try {
-      result = await serviceContext.run({
+      result = await serviceContext.execute({
         query: runItem.text,
         onStepCallback,
         onAssistantStepCallback,

package/src/service/builtins/chat/runtime/ChatSession.ts

@@ -127,7 +127,7 @@ export class ChatSession extends Executor {
    * 运行当前 chat session 的一次请求。
    *
    * 关键点（中文）
-   * - 外层继续走统一的 `session.run(...)` 入口。
+   * - 外层继续走统一的内部执行入口。
    * - ChatSession 只是在 run 生命周期里临时绑定 turn 状态给自己的 composer。
    */
   override async run(params: {

package/src/service/builtins/contact/runtime/ChatRuntime.ts

@@ -64,7 +64,7 @@ export async function receiveContactChatMessage(params: {
   });
 
   const sessionId = `contact_${contact.id}`;
-  const result = await params.context.session.get(sessionId).run({
+  const result = await params.context.session.get(sessionId).execute({
     query: params.message,
   });
   const reply = extractMessageText(result.assistantMessage);

package/src/session/README.md

@@ -1,22 +1,23 @@
 # Session Module
 
-`session/` 是单 Agent 会话执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.run()`、`session.stream()`、`session.history()` 等 API。
+`session/` 是单 Agent 会话执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.prompt()`、`session.subscribe()`、`session.history()` 等 API。
 
 ## 核心概念
 
-- `Session`：用户/SDK 面向的完整会话对象，负责模型配置、历史入口、运行入口和分叉能力。
-- `Executor`：单个 session 的一轮 run 执行引擎，负责并发锁、run scope、Composer 编排、压缩重试、assistant step 持久化和 tool-loop 调用。
+- `Session`：用户/SDK 面向的完整会话对象，负责模型配置、历史入口、prompt 入口和分叉能力。
+- `Executor`：单个 session 的内部单轮执行引擎，负责并发锁、执行 scope、Composer 编排、压缩重试、assistant step 持久化和 tool-loop 调用。
 - `Composer`：执行前的材料组装协议，只负责把原材料组装成某一阶段输入，不直接执行模型，也没有公共运行时基类。
 - `HistoryStore`：历史事实源，负责 JSONL 读写、meta、archive、lock、compact 与消息工厂。
 - `HistoryComposer`：历史组装策略，只负责把 `HistoryStore` 中的历史组装成本轮模型输入。
 - `CoreEngine`：Executor 内部的模型/tool-loop 核心机制，负责模型流、tool calls、续写和最终 assistant message 合并。
 
-## 一轮 run 的调用链
+## 一轮 prompt 的调用链
 
 ```text
-sdk/Session.run({ query })
+sdk/Session.prompt({ query })
+  -> SessionPromptRuntime 绑定 turn
   -> append user message
-  -> session/Executor.run({ query })
+  -> session/Executor 执行当前 turn
      -> ContextComposer.compose()
      -> SystemComposer.resolve()
      -> CompactionComposer.run()
@@ -25,7 +26,7 @@ sdk/Session.run({ query })
         -> ai.streamText({ model, system, messages, tools })
      -> return assistantMessage
   -> append final assistant message
-  -> return SDK result
+  -> resolve turn.finished
 ```
 
 ## Composer 分工

package/src/types/sdk/AgentSessionEvent.ts

@@ -0,0 +1,195 @@
+/**
+ * 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;

package/src/types/sdk/AgentSessionPrompt.ts

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

package/src/types/sdk/AgentSessionTurn.ts

@@ -0,0 +1,65 @@
+/**
+ * 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>;
+}