@downcity/agent 1.1.15 → 1.1.17

package/src/session/README.md

@@ -0,0 +1,107 @@
+# Session Module
+
+`session/` 是单 Agent 会话执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.run()`、`session.stream()`、`session.history()` 等 API。
+
+## 核心概念
+
+- `Session`：用户/SDK 面向的完整会话对象，负责模型配置、历史入口、运行入口和分叉能力。
+- `Executor`：单个 session 的一轮 run 执行引擎，负责并发锁、run scope、Composer 编排、压缩重试、assistant step 持久化和 tool-loop 调用。
+- `Composer`：执行前的材料组装协议，只负责把原材料组装成某一阶段输入，不直接执行模型，也没有公共运行时基类。
+- `HistoryStore`：历史事实源，负责 JSONL 读写、meta、archive、lock、compact 与消息工厂。
+- `HistoryComposer`：历史组装策略，只负责把 `HistoryStore` 中的历史组装成本轮模型输入。
+- `CoreEngine`：Executor 内部的模型/tool-loop 核心机制，负责模型流、tool calls、续写和最终 assistant message 合并。
+
+## 一轮 run 的调用链
+
+```text
+sdk/Session.run({ query })
+  -> append user message
+  -> session/Executor.run({ query })
+     -> ContextComposer.compose()
+     -> SystemComposer.resolve()
+     -> CompactionComposer.run()
+     -> HistoryComposer.prepare()
+     -> Executor.runCoreEngine()
+        -> ai.streamText({ model, system, messages, tools })
+     -> return assistantMessage
+  -> append final assistant message
+  -> return SDK result
+```
+
+## Composer 分工
+
+- `composer/system/`：组装本轮 system messages，例如 instruction、service system、plugin system 和 session context。
+- `composer/history/`：只组装本轮 model messages，不负责历史落盘。
+- `composer/context/`：组装 tools、step hooks、fallback assistant message 等运行上下文。
+- `composer/compaction/`：判断上下文错误和压缩历史，必要时写入 summary 与 archive。
+
+## Composer 的代码实现方式
+
+Composer 在代码里是 TypeScript `interface`，不是抽象基类。每个 Composer 只声明当前阶段需要的最小协议，实现类用 `implements` 接上。
+
+```ts
+export interface SessionSystemComposer {
+  readonly name: string;
+  resolve(): Promise<SystemModelMessage[]>;
+}
+
+export class DefaultSessionSystemComposer implements SessionSystemComposer {
+  readonly name = "prompt_system";
+
+  async resolve() {
+    // 关键点（中文）：只组装 system messages，不执行模型、不写历史。
+  }
+}
+```
+
+当前四类协议分别回答四个问题：
+
+- `SessionSystemComposer.resolve()`：这一轮 system messages 是什么？
+- `SessionHistoryComposer.prepare()`：这一轮喂给模型的 history messages 是什么？
+- `SessionContextComposer.compose()`：这一轮有哪些 tools 与 step hooks？
+- `SessionCompactionComposer.run()`：是否需要压缩，以及压缩策略是什么？
+
+`Executor.prepareExecuteInput()` 是 Composer 的唯一主装配点：
+
+```text
+Executor.prepareExecuteInput()
+  -> ContextComposer.compose()
+  -> SystemComposer.resolve()
+  -> CompactionComposer.run(historyStore)
+  -> HistoryComposer.prepare()
+  -> SessionExecuteInput
+```
+
+边界规则：
+
+- Composer 不调用模型，模型调用只发生在 `Executor.runCoreEngine()`。
+- Composer 不持有历史事实，历史事实由 `HistoryStore` 负责。
+- Composer 不管理 session 生命周期，生命周期由 `Session` / `Executor` 管理。
+- Composer 可以读取上下文并做策略判断，但输出应该是“本轮执行材料”。
+
+## 当前目录结构
+
+```text
+session/
+├── Executor.ts
+├── SessionRunScope.ts
+├── composer/
+│   ├── compaction/
+│   ├── context/
+│   ├── history/
+│   └── system/
+├── core-engine/
+│   ├── CoreEngineMessageState.ts
+│   ├── CoreEngineLoopDecision.ts
+│   ├── CoreEngineSignals.ts
+│   ├── CoreEngineError.ts
+│   └── CoreEngineUiStreamCollector.ts
+├── store/
+│   └── history/
+│       ├── SessionHistoryStore.ts
+│       └── jsonl/JsonlSessionHistoryStore.ts
+├── ids/
+├── messages/
+├── tools/
+└── types/
+```

package/src/session/composer/compaction/SessionCompactionComposer.ts

@@ -3,21 +3,20 @@
  *
  * 关键点（中文）
  * - 负责“何时压缩 + 压缩策略参数”决策。
- * - 具体读写由 SessionHistoryComposer 执行（CompactionComposer 不直接落盘）。
+ * - 具体读写由 SessionHistoryStore 执行（CompactionComposer 不直接落盘）。
  */
 
 import type { LanguageModel, SystemModelMessage } from "ai";
-import { SessionComposer } from "@session/composer/SessionComposer.js";
-import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
 
 /**
  * compaction Composer 执行输入。
  */
 export type SessionCompactionInput = {
   /**
-   * 当前会话 history Composer。
+   * 当前会话 history Store。
    */
-  historyComposer: SessionHistoryComposer;
+  historyStore: SessionHistoryStore;
 
   /**
    * 当前模型实例。
@@ -30,24 +29,24 @@ export type SessionCompactionInput = {
   system: SystemModelMessage[];
 
   /**
-   * 当前重试次数（由 Runner 递增）。
+   * 当前重试次数（由 Executor 递增）。
    */
   retryCount: number;
 };
 
 /**
- * Compaction Composer 抽象类。
+ * Compaction Composer 协议。
  */
-export abstract class SessionCompactionComposer extends SessionComposer {
+export interface SessionCompactionComposer {
   /**
    * Composer 名（由具体实现声明）。
    */
-  abstract readonly name: string;
+  readonly name: string;
 
   /**
    * 执行 compact（best-effort）。
    */
-  abstract run(input: SessionCompactionInput): Promise<{
+  run(input: SessionCompactionInput): Promise<{
     compacted: boolean;
     reason?: string;
   }>;
@@ -57,12 +56,7 @@ export abstract class SessionCompactionComposer extends SessionComposer {
    *
    * 关键点（中文）
    * - 由 compaction Composer 实现侧维护错误识别策略。
-   * - Runner 不感知具体错误文案，只按该布尔结果决定是否重试。
+   * - Executor 不感知具体错误文案，只按该布尔结果决定是否重试。
    */
-  abstract shouldCompactOnError(error: unknown): boolean;
-
-  /**
-   * 可选初始化钩子。
-   */
-  // 生命周期沿用 SessionComposer 默认实现。
+  shouldCompactOnError(error: unknown): boolean;
 }

package/src/session/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -3,11 +3,13 @@
  *
  * 关键点（中文）
  * - 只负责压缩参数策略（retry 越多，窗口越紧）。
- * - 真正的读写与 compact 执行交由 history Composer。
+ * - 真正的读写与 compact 执行交由 history Store。
  */
 
-import type { SessionCompactionInput } from "@session/composer/compaction/SessionCompactionComposer.js";
-import { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
+import type {
+  SessionCompactionComposer,
+  SessionCompactionInput,
+} from "@session/composer/compaction/SessionCompactionComposer.js";
 
 type JsonlSessionCompactionComposerOptions = {
   keepLastMessages?: number;
@@ -19,12 +21,11 @@ type JsonlSessionCompactionComposerOptions = {
 /**
  * JsonlSessionCompactionComposer 默认实现。
  */
-export class JsonlSessionCompactionComposer extends SessionCompactionComposer {
+export class JsonlSessionCompactionComposer implements SessionCompactionComposer {
   readonly name = "summary_compaction_composer";
   private readonly options: JsonlSessionCompactionComposerOptions;
 
   constructor(options?: JsonlSessionCompactionComposerOptions) {
-    super();
     this.options = options || {};
   }
 
@@ -71,7 +72,7 @@ export class JsonlSessionCompactionComposer extends SessionCompactionComposer {
     reason?: string;
   }> {
     const policy = this.resolvePolicy(input.retryCount);
-    return await input.historyComposer.compact({
+    return await input.historyStore.compact({
       model: input.model,
       system: input.system,
       keepLastMessages: policy.keepLastMessages,

package/src/session/composer/{execution/LocalSessionExecutionComposer.ts → context/LocalSessionContextComposer.ts}

@@ -1,9 +1,9 @@
 /**
- * LocalSessionExecutionComposer：本地 session 运行时编排 Composer 实现。
+ * LocalSessionContextComposer：本地 session 运行时编排 Composer 实现。
  *
  * 关键点（中文）
  * - 统一组装 tools。
- * - step 边界回调从 SessionRunScope 读取，Runner 不直接管理来源。
+ * - step 边界回调从 SessionRunScope 读取，Executor 不直接管理来源。
  */
 
 import type { ModelMessage } from "ai";
@@ -12,15 +12,15 @@ import {
   drainInjectedUserMessages,
   getSessionRunScope,
 } from "@session/SessionRunScope.js";
-import { SessionExecutionComposer } from "@session/composer/execution/SessionExecutionComposer.js";
 import type {
-  SessionExecutionComposeResult,
-} from "@session/composer/execution/SessionExecutionComposer.js";
+  SessionContextComposer,
+  SessionContextComposeResult,
+} from "@session/composer/context/SessionContextComposer.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
 import type { Tool } from "ai";
 
-type LocalSessionExecutionComposerOptions = {
+type LocalSessionContextComposerOptions = {
   /**
    * 可选默认 session id。
    */
@@ -33,26 +33,25 @@ type LocalSessionExecutionComposerOptions = {
 };
 
 /**
- * LocalSessionExecutionComposer 默认 Composer 实现。
+ * LocalSessionContextComposer 默认 Composer 实现。
  */
-export class LocalSessionExecutionComposer extends SessionExecutionComposer {
-  readonly name = "runtime_execution_composer";
+export class LocalSessionContextComposer implements SessionContextComposer {
+  readonly name = "runtime_context_composer";
   private readonly sessionId: string;
-  private readonly getTools: LocalSessionExecutionComposerOptions["getTools"];
+  private readonly getTools: LocalSessionContextComposerOptions["getTools"];
 
-  constructor(options: LocalSessionExecutionComposerOptions) {
-    super();
+  constructor(options: LocalSessionContextComposerOptions) {
     this.sessionId = String(options.sessionId || "").trim();
     this.getTools = options.getTools;
   }
 
-  async compose(): Promise<SessionExecutionComposeResult> {
+  async compose(): Promise<SessionContextComposeResult> {
     const tools = this.getTools();
     const ctx = getSessionRunScope();
     const sessionId = String(ctx?.sessionId || this.sessionId || "").trim();
     if (!sessionId) {
       throw new Error(
-        "LocalSessionExecutionComposer.compose requires a sessionId from sessionRunScope or options.sessionId",
+        "LocalSessionContextComposer.compose requires a sessionId from sessionRunScope or options.sessionId",
       );
     }
     // 关键点（中文）：sessionId 统一回填到请求上下文，后续组件直接读取。
@@ -150,7 +149,7 @@ export class LocalSessionExecutionComposer extends SessionExecutionComposer {
     const sessionId = String(ctx?.sessionId || this.sessionId || "").trim();
     if (!sessionId) {
       throw new Error(
-        "LocalSessionExecutionComposer.buildFallbackAssistantMessage requires a sessionId from sessionRunScope or options.sessionId",
+        "LocalSessionContextComposer.buildFallbackAssistantMessage requires a sessionId from sessionRunScope or options.sessionId",
       );
     }
     return {

package/src/session/composer/{execution/SessionExecutionComposer.ts → context/SessionContextComposer.ts}

@@ -1,20 +1,19 @@
 /**
- * SessionExecutionComposer：单次 Session run 编排 Composer 抽象。
+ * SessionContextComposer：单次 Session run context 组装协议。
  *
  * 关键点（中文）
- * - 负责 tools/onStepCallback 等运行时编排。
+ * - 负责 tools / prepareStep / onStepFinish / fallback message factory 等运行上下文组装。
  * - 不负责历史读写，不负责 system 解析，不负责 compact。
  */
 
 import type { ModelMessage, Tool } from "ai";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
-import { SessionComposer } from "@session/composer/SessionComposer.js";
 
 /**
- * 本轮运行编排输出。
+ * 本轮运行上下文组装输出。
  */
-export type SessionExecutionComposeResult = {
+export type SessionContextComposeResult = {
   /**
    * 本轮工具集合。
    */
@@ -22,23 +21,23 @@ export type SessionExecutionComposeResult = {
 };
 
 /**
- * 运行编排 Composer 抽象类。
+ * 运行上下文 Composer 协议。
  */
-export abstract class SessionExecutionComposer extends SessionComposer {
+export interface SessionContextComposer {
   /**
    * Composer 名（由具体实现声明）。
    */
-  abstract readonly name: string;
+  readonly name: string;
 
   /**
-   * 组装一次 run 所需运行态。
+   * 组装一次 run 所需上下文。
    */
-  abstract compose(): Promise<SessionExecutionComposeResult>;
+  compose(): Promise<SessionContextComposeResult>;
 
   /**
    * 构造 prepareStep 回调。
    */
-  abstract createPrepareStepHandler(
+  createPrepareStepHandler(
     input: {
       /**
        * 当前轮 system 消息。
@@ -59,13 +58,13 @@ export abstract class SessionExecutionComposer extends SessionComposer {
   /**
    * 构造 onStepFinish 回调。
    */
-  abstract createOnStepFinishHandler(): (stepResult: unknown) => Promise<void>;
+  createOnStepFinishHandler(): (stepResult: unknown) => Promise<void>;
 
   /**
    * 构造 fallback assistant 消息。
    *
    * 关键点（中文）
- * - fallback 消息构造由 execution Composer 内部实现，Runner 不直接依赖 history Composer。
+   * - fallback 消息构造由 ContextComposer 内部实现，Executor 不直接依赖 history Composer。
    */
-  abstract buildFallbackAssistantMessage(text: string): SessionMessageV1;
+  buildFallbackAssistantMessage(text: string): SessionMessageV1;
 }

package/src/session/composer/history/SessionHistoryComposer.ts

@@ -2,17 +2,14 @@
  * SessionHistoryComposer：会话历史 Composer 抽象。
  *
  * 关键点（中文）
- * - 负责“历史读写 + 运行输入准备 + 文本消息工厂”。
+ * - 负责把历史事实源组装成本轮模型输入消息。
+ * - 不负责 append / list / meta / archive 等落盘能力。
  * - 不负责模型调用，不负责执行编排。
  */
 
 import type { LanguageModel, Tool } from "ai";
-import type {
-  SessionMessageV1,
-  SessionMetadataV1,
-} from "@/session/types/SessionMessages.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
-import { SessionComposer } from "@session/composer/SessionComposer.js";
 
 /**
  * prepare 输入参数。
@@ -39,156 +36,27 @@ export type SessionHistoryPrepareInput = {
   model: LanguageModel;
 
   /**
-   * 当前重试次数（由 Runner 递增）。
+   * 当前重试次数（由 Executor 递增）。
    */
   retryCount: number;
 };
 
 /**
- * compact 输入参数。
+ * SessionHistoryComposer 协议。
  */
-export type SessionHistoryCompactInput = {
-  /**
-   * 当前模型实例。
-   */
-  model: LanguageModel;
-
-  /**
-   * 当前轮 system messages。
-   */
-  system: SessionSystemMessage[];
-
-  /**
-   * 保留最近消息条数。
-   */
-  keepLastMessages: number;
-
-  /**
-   * 输入 token 近似上限。
-   */
-  maxInputTokensApprox: number;
-
-  /**
-   * compact 时是否归档旧消息。
-   */
-  archiveOnCompact: boolean;
-
-  /**
-   * 前段压缩比例（0-1）。
-   *
-   * 关键点（中文）
-   * - 例如 0.5 表示“优先压缩最早 50% 的 UIMessage”。
-   * - 具体切分由 history Composer 实现侧做边界校正。
-   */
-  compactRatio: number;
-};
-
-/**
- * SessionHistoryComposer 抽象类。
- */
-export abstract class SessionHistoryComposer extends SessionComposer {
+export interface SessionHistoryComposer {
   /**
    * Composer 名（由具体实现声明）。
    */
-  abstract readonly name: string;
+  readonly name: string;
 
   /**
    * 当前会话 ID。
    */
-  abstract readonly sessionId: string;
+  readonly sessionId: string;
 
   /**
    * 为本轮 Session 执行准备模型输入消息。
    */
-  abstract prepare(input: SessionHistoryPrepareInput): Promise<SessionMessageV1[]>;
-
-  /**
-   * 执行一次 compact（best-effort）。
-   */
-  abstract compact(input: SessionHistoryCompactInput): Promise<{
-    compacted: boolean;
-    reason?: string;
-  }>;
-
-  /**
-   * 追加一条消息到历史。
-   */
-  abstract append(message: SessionMessageV1): Promise<void>;
-
-  /**
-   * 读取完整消息历史。
-   */
-  abstract list(): Promise<SessionMessageV1[]>;
-
-  /**
-   * 读取消息区间 [start, end)。
-   */
-  abstract slice(start: number, end: number): Promise<SessionMessageV1[]>;
-
-  /**
-   * 读取消息总条数。
-   */
-  abstract size(): Promise<number>;
-
-  /**
-   * 读取元信息。
-   */
-  abstract meta(): Promise<Record<string, unknown>>;
-
-  /**
-   * 构造 user 文本消息。
-   */
-  abstract userText(input: {
-    /**
-     * 用户文本内容。
-     */
-    text: string;
-
-    /**
-     * 消息元信息（除 schema 字段）。
-     */
-    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
-      Partial<Pick<SessionMetadataV1, "ts">>;
-
-    /**
-     * 可选消息 ID（默认自动生成）。
-     */
-    id?: string;
-  }): SessionMessageV1;
-
-  /**
-   * 构造 assistant 文本消息。
-   */
-  abstract assistantText(input: {
-    /**
-     * 助手文本内容。
-     */
-    text: string;
-
-    /**
-     * 消息元信息（除 schema 字段）。
-     */
-    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
-      Partial<Pick<SessionMetadataV1, "ts">>;
-
-    /**
-     * 可选消息 ID（默认自动生成）。
-     */
-    id?: string;
-
-    /**
-     * 消息种类（普通/摘要）。
-     */
-    kind?: "normal" | "summary";
-
-    /**
-     * 消息来源（egress/compact）。
-     */
-    source?: "egress" | "compact";
-  }): SessionMessageV1;
-
-  /**
-   * 可选初始化钩子。
-   */
-  // 生命周期沿用 SessionComposer 默认实现。
+  prepare(input: SessionHistoryPrepareInput): Promise<SessionMessageV1[]>;
 }

package/src/session/composer/history/SessionHistoryWriter.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 只负责当前 session 的 user / assistant 消息补写。
- * - 只依赖当前 session 的 history Composer，不感知其他 session。
+ * - 只依赖当前 session 的 history Store，不感知其他 session。
  * - 会话更新后的通知也收在这里，避免把写入细节散到 Session 主类里。
  */
 
@@ -12,7 +12,7 @@ import type {
   SessionMessageV1,
   SessionMetadataV1,
 } from "@/session/types/SessionMessages.js";
-import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
 
 type SessionHistoryWriterOptions = {
   /**
@@ -21,9 +21,9 @@ type SessionHistoryWriterOptions = {
   sessionId: string;
 
   /**
-   * 获取当前 session 对应的 history Composer。
+   * 获取当前 session 对应的 history Store。
    */
-  getHistoryComposer: () => SessionHistoryComposer;
+  getHistoryStore: () => SessionHistoryStore;
 
   /**
    * session 更新后的异步回调。
@@ -36,12 +36,12 @@ type SessionHistoryWriterOptions = {
  */
 export class SessionHistoryWriter {
   private readonly sessionId: string;
-  private readonly getHistoryComposer: SessionHistoryWriterOptions["getHistoryComposer"];
+  private readonly getHistoryStore: SessionHistoryWriterOptions["getHistoryStore"];
   private readonly runAfterSessionUpdated?: SessionHistoryWriterOptions["runAfterSessionUpdated"];
 
   constructor(options: SessionHistoryWriterOptions) {
     this.sessionId = String(options.sessionId || "").trim();
-    this.getHistoryComposer = options.getHistoryComposer;
+    this.getHistoryStore = options.getHistoryStore;
     this.runAfterSessionUpdated = options.runAfterSessionUpdated;
     if (!this.sessionId) {
       throw new Error("SessionHistoryWriter requires a non-empty sessionId");
@@ -69,9 +69,9 @@ export class SessionHistoryWriter {
     extra?: JsonObject;
   }): Promise<void> {
     try {
-      const historyComposer = this.getHistoryComposer();
+      const historyStore = this.getHistoryStore();
       if (params.message && typeof params.message === "object") {
-        await historyComposer.append(params.message);
+        await historyStore.append(params.message);
         void this.afterSessionUpdatedAsync();
         return;
       }
@@ -79,14 +79,14 @@ export class SessionHistoryWriter {
       const fallbackText = String(params.text || "").trim();
       if (!fallbackText) return;
 
-      const message = historyComposer.userText({
+      const message = historyStore.userText({
         text: fallbackText,
         metadata: {
           sessionId: this.sessionId,
           extra: params.extra,
         } as Omit<SessionMetadataV1, "v" | "ts">,
       });
-      await historyComposer.append(message);
+      await historyStore.append(message);
       void this.afterSessionUpdatedAsync();
     } catch {
       // ignore
@@ -102,9 +102,9 @@ export class SessionHistoryWriter {
     extra?: JsonObject;
   }): Promise<void> {
     try {
-      const historyComposer = this.getHistoryComposer();
+      const historyStore = this.getHistoryStore();
       if (params.message && typeof params.message === "object") {
-        await historyComposer.append(params.message);
+        await historyStore.append(params.message);
         void this.afterSessionUpdatedAsync();
         return;
       }
@@ -112,8 +112,8 @@ export class SessionHistoryWriter {
       const fallbackText = String(params.fallbackText || "").trim();
       if (!fallbackText) return;
 
-      await historyComposer.append(
-        historyComposer.assistantText({
+      await historyStore.append(
+        historyStore.assistantText({
           text: fallbackText,
           metadata: {
             sessionId: this.sessionId,