@downcity/agent 1.1.15 → 1.1.17

package/src/session/composer/history/jsonl/JsonlSessionHistoryComposer.ts

@@ -1,322 +1,45 @@
 /**
- * JsonlSessionHistoryComposer：基于 JSONL 的 session history Composer 实现。
+ * JsonlSessionHistoryComposer：基于 JSONL store 的 history 组装器。
  *
  * 关键点（中文）
- * - 以 `.downcity/session/<sessionId>/messages/messages.jsonl` 为事实源。
- * - append 与 compact 共用同一把文件锁，避免并发覆盖。
- * - 对 Session 执行层暴露统一的 SessionHistoryComposer 接口。
+ * - 只负责 `prepare()`，把 history store 中的消息组装成本轮模型输入。
+ * - 不负责 append / list / meta / compact 等落盘能力。
+ * - JSONL 文件事实源由 `JsonlSessionHistoryStore` 承担。
  */
 
-import fs from "fs-extra";
-import {
-  open as openFile,
-  readFile as readFileNative,
-  stat as statNative,
-} from "node:fs/promises";
-import path from "node:path";
-import {
-  type Tool,
-} from "ai";
-import { generateId } from "@/utils/Id.js";
-import { getLogger } from "@/utils/logger/Logger.js";
-import { compactSessionMessagesIfNeeded } from "@session/composer/compaction/jsonl/JsonlSessionCompactionExecutor.js";
+import type { Tool } from "ai";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
 import type {
-  SessionMessageV1,
-  SessionMetadataV1,
-} from "@/session/types/SessionMessages.js";
-import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
-import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
-import type { SessionHistoryPathOverrides } from "@/session/types/SessionHistoryPaths.js";
-import {
   SessionHistoryComposer,
-  type SessionHistoryCompactInput,
-  type SessionHistoryPrepareInput,
+  SessionHistoryPrepareInput,
 } from "@session/composer/history/SessionHistoryComposer.js";
 
-type JsonlSessionHistoryComposerOptions = {
-  rootPath: string;
-  sessionId?: string;
-  paths?: SessionHistoryPathOverrides;
+/**
+ * JSONL history composer 构造参数。
+ */
+export type JsonlSessionHistoryComposerOptions = {
+  /**
+   * 当前 history 事实源。
+   */
+  store: SessionHistoryStore;
 };
 
-function getDowncityDirPath(rootPath: string): string {
-  return path.join(rootPath, ".downcity");
-}
-
-function getDowncitySessionRootDirPath(rootPath: string): string {
-  return path.join(getDowncityDirPath(rootPath), "session");
-}
-
-function getDowncitySessionDirPath(rootPath: string, sessionId: string): string {
-  return path.join(
-    getDowncitySessionRootDirPath(rootPath),
-    encodeURIComponent(sessionId),
-  );
-}
-
-function getDowncitySessionMessagesDirPath(
-  rootPath: string,
-  sessionId: string,
-): string {
-  return path.join(getDowncitySessionDirPath(rootPath, sessionId), "messages");
-}
-
-export class JsonlSessionHistoryComposer extends SessionHistoryComposer {
-  readonly name = "jsonl_history_store";
+/**
+ * JSONL history composer。
+ */
+export class JsonlSessionHistoryComposer implements SessionHistoryComposer {
+  readonly name = "jsonl_history_composer";
   readonly sessionId: string;
 
-  private readonly rootPath: string;
-  private readonly overrideSessionDirPath?: string;
-  private readonly overrideMessagesDirPath?: string;
-  private readonly overrideMessagesFilePath?: string;
-  private readonly overrideMetaFilePath?: string;
-  private readonly overrideArchiveDirPath?: string;
+  private readonly store: SessionHistoryStore;
 
   constructor(options: JsonlSessionHistoryComposerOptions) {
-    super();
-    const rootPath = String(options.rootPath || "").trim();
-    if (!rootPath) {
-      throw new Error("JsonlSessionHistoryComposer requires a non-empty rootPath");
-    }
-    const sessionId = String(options.sessionId || "").trim();
-    if (!sessionId) {
+    this.store = options.store;
+    this.sessionId = String(options.store?.sessionId || "").trim();
+    if (!this.sessionId) {
       throw new Error("JsonlSessionHistoryComposer requires a non-empty sessionId");
     }
-
-    this.rootPath = rootPath;
-    this.sessionId = sessionId;
-    this.overrideSessionDirPath = this.readOptionalPath(
-      options.paths?.sessionDirPath,
-    );
-    this.overrideMessagesDirPath = this.readOptionalPath(
-      options.paths?.messagesDirPath,
-    );
-    this.overrideMessagesFilePath = this.readOptionalPath(
-      options.paths?.messagesFilePath,
-    );
-    this.overrideMetaFilePath = this.readOptionalPath(
-      options.paths?.metaFilePath,
-    );
-    this.overrideArchiveDirPath = this.readOptionalPath(
-      options.paths?.archiveDirPath,
-    );
-  }
-
-  private readOptionalPath(value: string | undefined): string | undefined {
-    const out = String(value || "").trim();
-    return out || undefined;
-  }
-
-  private getMessagesDirPath(): string {
-    if (this.overrideMessagesDirPath) return this.overrideMessagesDirPath;
-    if (this.overrideSessionDirPath) {
-      return path.join(this.overrideSessionDirPath, "messages");
-    }
-    return getDowncitySessionMessagesDirPath(this.rootPath, this.sessionId);
-  }
-
-  private getMessagesFilePath(): string {
-    if (this.overrideMessagesFilePath) return this.overrideMessagesFilePath;
-    if (this.overrideMessagesDirPath) {
-      return path.join(this.overrideMessagesDirPath, "messages.jsonl");
-    }
-    return path.join(this.getMessagesDirPath(), "messages.jsonl");
-  }
-
-  private getMetaFilePath(): string {
-    if (this.overrideMetaFilePath) return this.overrideMetaFilePath;
-    if (this.overrideMessagesDirPath) {
-      return path.join(this.overrideMessagesDirPath, "meta.json");
-    }
-    return path.join(this.getMessagesDirPath(), "meta.json");
-  }
-
-  private getArchiveDirPath(): string {
-    if (this.overrideArchiveDirPath) return this.overrideArchiveDirPath;
-    if (this.overrideMessagesDirPath) {
-      return path.join(this.overrideMessagesDirPath, "archive");
-    }
-    return path.join(this.getMessagesDirPath(), "archive");
-  }
-
-  private getLockFilePath(): string {
-    return path.join(this.getMessagesDirPath(), ".session.lock");
-  }
-
-  private async ensureLayout(): Promise<void> {
-    // 关键点（中文）：以 messages 目录为最小落盘单元，统一保证 messages/meta/archive 可写。
-    await fs.ensureDir(this.getMessagesDirPath());
-    await fs.ensureDir(this.getArchiveDirPath());
-    await fs.ensureFile(this.getMessagesFilePath());
-  }
-
-  private normalizePinnedSkillIds(input: string[] | undefined): string[] {
-    if (!Array.isArray(input)) return [];
-    const out: string[] = [];
-    for (const raw of input) {
-      const id = typeof raw === "string" ? raw.trim() : "";
-      if (!id) continue;
-      out.push(id);
-    }
-    return Array.from(new Set(out)).slice(0, 2000);
-  }
-
-  private normalizeSdkConfig(
-    input: SessionHistoryMetaV1["sdkConfig"],
-  ): SessionHistoryMetaV1["sdkConfig"] {
-    if (!input || typeof input !== "object" || Array.isArray(input)) {
-      return undefined;
-    }
-    const modelLabel =
-      typeof input.modelLabel === "string" ? input.modelLabel.trim() : "";
-    if (!modelLabel) return undefined;
-    return {
-      modelLabel,
-    };
-  }
-
-  private async readMetaUnsafe(): Promise<SessionHistoryMetaV1> {
-    const file = this.getMetaFilePath();
-    try {
-      const raw = (await fs.readJson(
-        file,
-      )) as Partial<SessionHistoryMetaV1> | null;
-      if (!raw || typeof raw !== "object") throw new Error("invalid_meta");
-      return {
-        v: 1,
-        sessionId: this.sessionId,
-        ...(typeof raw.agentId === "string" && raw.agentId.trim()
-          ? { agentId: raw.agentId.trim() }
-          : {}),
-        ...(typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
-          ? { createdAt: raw.createdAt }
-          : {}),
-        updatedAt: typeof raw.updatedAt === "number" ? raw.updatedAt : 0,
-        pinnedSkillIds: this.normalizePinnedSkillIds(raw.pinnedSkillIds),
-        ...(typeof raw.lastArchiveId === "string" && raw.lastArchiveId.trim()
-          ? { lastArchiveId: raw.lastArchiveId.trim() }
-          : {}),
-        ...(typeof raw.keepLastMessages === "number" &&
-        Number.isFinite(raw.keepLastMessages)
-          ? { keepLastMessages: raw.keepLastMessages }
-          : {}),
-        ...(typeof raw.maxInputTokensApprox === "number" &&
-        Number.isFinite(raw.maxInputTokensApprox)
-          ? { maxInputTokensApprox: raw.maxInputTokensApprox }
-          : {}),
-        ...(typeof raw.compactRatio === "number" &&
-        Number.isFinite(raw.compactRatio)
-          ? { compactRatio: raw.compactRatio }
-          : {}),
-        ...(this.normalizeSdkConfig(raw.sdkConfig)
-          ? { sdkConfig: this.normalizeSdkConfig(raw.sdkConfig) }
-          : {}),
-      };
-    } catch {
-      return {
-        v: 1,
-        sessionId: this.sessionId,
-        createdAt: Date.now(),
-        updatedAt: 0,
-        pinnedSkillIds: [],
-      };
-    }
-  }
-
-  private async writeMetaUnsafe(
-    next: SessionHistoryMetaV1,
-  ): Promise<void> {
-    const normalized: SessionHistoryMetaV1 = {
-      v: 1,
-      sessionId: this.sessionId,
-      ...(typeof next.agentId === "string" && next.agentId.trim()
-        ? { agentId: next.agentId.trim() }
-        : {}),
-      ...(typeof next.createdAt === "number" && Number.isFinite(next.createdAt)
-        ? { createdAt: next.createdAt }
-        : {}),
-      updatedAt:
-        typeof next.updatedAt === "number" ? next.updatedAt : Date.now(),
-      pinnedSkillIds: this.normalizePinnedSkillIds(next.pinnedSkillIds),
-      ...(typeof next.lastArchiveId === "string" && next.lastArchiveId.trim()
-        ? { lastArchiveId: next.lastArchiveId.trim() }
-        : {}),
-      ...(typeof next.keepLastMessages === "number" &&
-      Number.isFinite(next.keepLastMessages)
-        ? { keepLastMessages: next.keepLastMessages }
-        : {}),
-      ...(typeof next.maxInputTokensApprox === "number" &&
-      Number.isFinite(next.maxInputTokensApprox)
-        ? { maxInputTokensApprox: next.maxInputTokensApprox }
-        : {}),
-      ...(typeof next.compactRatio === "number" &&
-      Number.isFinite(next.compactRatio)
-        ? { compactRatio: next.compactRatio }
-        : {}),
-      ...(this.normalizeSdkConfig(next.sdkConfig)
-        ? { sdkConfig: this.normalizeSdkConfig(next.sdkConfig) }
-        : {}),
-    };
-    await fs.writeJson(this.getMetaFilePath(), normalized, { spaces: 2 });
-  }
-
-  private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
-    await this.ensureLayout();
-    const lockPath = this.getLockFilePath();
-    const token = `${process.pid}:${Date.now()}:${generateId()}`;
-    const logger = getLogger(this.rootPath, "info");
-
-    // 关键点（中文）：append 与 compact 共用同一把文件锁，防止 rewrite 覆盖 append。
-    const staleMs = 30_000;
-    const start = Date.now();
-    while (true) {
-      try {
-        const fh = await openFile(lockPath, "wx");
-        await fh.writeFile(token, "utf8");
-        await fh.close();
-        break;
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException;
-        if (err.code !== "EEXIST") throw err;
-        try {
-          const stat = await statNative(lockPath);
-          const age = Date.now() - stat.mtimeMs;
-          if (age > staleMs) {
-            await fs.remove(lockPath);
-            await logger.log("warn", "Removed stale session lock", {
-              sessionId: this.sessionId,
-              lockPath,
-              ageMs: age,
-            });
-            continue;
-          }
-        } catch {
-          // ignore
-        }
-        if (Date.now() - start > staleMs * 2) {
-          throw new Error(`Context lock timeout: ${lockPath}`);
-        }
-        await new Promise((resolve) => setTimeout(resolve, 60));
-      }
-    }
-
-    try {
-      return await fn();
-    } finally {
-      try {
-        const current = await readFileNative(lockPath, "utf8");
-        if (String(current || "").trim() === token) {
-          await fs.remove(lockPath);
-        }
-      } catch {
-        // ignore
-      }
-    }
-  }
-
-  private normalizeSystem(system: SessionSystemMessage[]): SessionSystemMessage[] {
-    if (!Array.isArray(system)) return [];
-    return system.filter((item) => item && typeof item === "object");
   }
 
   private normalizeTools(tools: Record<string, Tool>): Record<string, Tool> {
@@ -371,54 +94,15 @@ export class JsonlSessionHistoryComposer extends SessionHistoryComposer {
       .filter((message) => Array.isArray(message.parts) && message.parts.length > 0);
   }
 
-  async compact(input: SessionHistoryCompactInput): Promise<{
-    compacted: boolean;
-    reason?: string;
-  }> {
-    return await compactSessionMessagesIfNeeded(
-      {
-        rootPath: this.rootPath,
-        sessionId: this.sessionId,
-        withWriteLock: (fn) => this.withWriteLock(fn),
-        loadAll: () => this.list(),
-        createSummaryMessage: ({ text, sourceRange }) => ({
-          id: `a:${this.sessionId}:${generateId()}`,
-          role: "assistant",
-          metadata: {
-            v: 1,
-            ts: Date.now(),
-            sessionId: this.sessionId,
-            source: "compact",
-            kind: "summary",
-            ...(sourceRange ? { sourceRange } : {}),
-          },
-          parts: [{ type: "text", text: String(text ?? "") }],
-        }),
-        getArchiveDirPath: () => this.getArchiveDirPath(),
-        getMessagesFilePath: () => this.getMessagesFilePath(),
-        readMetaUnsafe: () => this.readMetaUnsafe(),
-        writeMetaUnsafe: (next) => this.writeMetaUnsafe(next),
-      },
-      {
-        model: input.model,
-        system: this.normalizeSystem(input.system),
-        keepLastMessages: input.keepLastMessages,
-        maxInputTokensApprox: input.maxInputTokensApprox,
-        archiveOnCompact: input.archiveOnCompact,
-        compactRatio: input.compactRatio,
-      },
-    );
-  }
-
   async prepare(input: SessionHistoryPrepareInput): Promise<SessionMessageV1[]> {
     const query = String(input.query || "").trim();
     const tools = this.normalizeTools(input.tools);
     void tools;
 
-    let baseMessages = this.sanitizeMessages(await this.list());
+    let baseMessages = this.sanitizeMessages(await this.store.list());
     if ((!Array.isArray(baseMessages) || baseMessages.length === 0) && query) {
       baseMessages = [
-        this.userText({
+        this.store.userText({
           text: query,
           metadata: {
             sessionId: this.sessionId,
@@ -429,7 +113,7 @@ export class JsonlSessionHistoryComposer extends SessionHistoryComposer {
     if (query && !this.hasTrailingUserQuery(baseMessages, query)) {
       baseMessages = [
         ...baseMessages,
-        this.userText({
+        this.store.userText({
           text: query,
           metadata: {
             sessionId: this.sessionId,
@@ -439,103 +123,4 @@ export class JsonlSessionHistoryComposer extends SessionHistoryComposer {
     }
     return baseMessages;
   }
-
-  async append(message: SessionMessageV1): Promise<void> {
-    await this.withWriteLock(async () => {
-      await fs.appendFile(
-        this.getMessagesFilePath(),
-        JSON.stringify(message) + "\n",
-        "utf8",
-      );
-    });
-  }
-
-  async list(): Promise<SessionMessageV1[]> {
-    await this.ensureLayout();
-    const file = this.getMessagesFilePath();
-    const raw = await fs.readFile(file, "utf8");
-    const lines = raw.split("\n").filter(Boolean);
-    const out: SessionMessageV1[] = [];
-    for (const line of lines) {
-      try {
-        const obj = JSON.parse(line) as Partial<SessionMessageV1>;
-        if (!obj || typeof obj !== "object") continue;
-        const role = String(obj.role || "");
-        if (role !== "user" && role !== "assistant") continue;
-        if (!Array.isArray(obj.parts)) continue;
-        out.push(obj as SessionMessageV1);
-      } catch {
-        // ignore invalid lines
-      }
-    }
-    return out;
-  }
-
-  async slice(start: number, end: number): Promise<SessionMessageV1[]> {
-    const msgs = await this.list();
-    const startIndex = Math.max(0, Math.floor(start));
-    const endIndex = Math.max(startIndex, Math.floor(end));
-    return msgs.slice(startIndex, endIndex);
-  }
-
-  async size(): Promise<number> {
-    const msgs = await this.list();
-    return msgs.length;
-  }
-
-  async meta(): Promise<Record<string, unknown>> {
-    await this.ensureLayout();
-    const metadata = await this.readMetaUnsafe();
-    return (
-      metadata && typeof metadata === "object" ? { ...metadata } : {}
-    ) as Record<string, unknown>;
-  }
-
-  userText(input: {
-    text: string;
-    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
-      Partial<Pick<SessionMetadataV1, "ts">>;
-    id?: string;
-  }): SessionMessageV1 {
-    const { ts, ...metadata } = input.metadata;
-    const md: SessionMetadataV1 = {
-      v: 1,
-      ts: typeof ts === "number" ? ts : Date.now(),
-      ...metadata,
-      source: "ingress",
-      kind: "normal",
-    };
-    const id = input.id || `u:${this.sessionId}:${generateId()}`;
-    return {
-      id,
-      role: "user",
-      metadata: md,
-      parts: [{ type: "text", text: String(input.text ?? "") }],
-    };
-  }
-
-  assistantText(input: {
-    text: string;
-    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
-      Partial<Pick<SessionMetadataV1, "ts">>;
-    id?: string;
-    kind?: "normal" | "summary";
-    source?: "egress" | "compact";
-  }): SessionMessageV1 {
-    const { ts, ...metadata } = input.metadata;
-    const md: SessionMetadataV1 = {
-      v: 1,
-      ts: typeof ts === "number" ? ts : Date.now(),
-      ...metadata,
-      source: input.source || "egress",
-      kind: input.kind || "normal",
-    };
-    const id = input.id || `a:${this.sessionId}:${generateId()}`;
-    return {
-      id,
-      role: "assistant",
-      metadata: md,
-      parts: [{ type: "text", text: String(input.text ?? "") }],
-    };
-  }
 }

package/src/session/composer/system/SessionSystemComposer.ts

@@ -3,23 +3,22 @@
  *
  * 关键点（中文）
  * - 专职负责“会话上下文 -> system messages”解析。
- * - 与 tools / step 编排解耦，避免 Runner 过载。
+ * - 与 tools / step 编排解耦，避免 Executor 过载。
  */
 
 import type { SystemModelMessage } from "ai";
-import { SessionComposer } from "@session/composer/SessionComposer.js";
 
 /**
- * Session system Composer 抽象类。
+ * Session system Composer 协议。
  */
-export abstract class SessionSystemComposer extends SessionComposer {
+export interface SessionSystemComposer {
   /**
    * 解析器名称（由具体实现声明）。
    */
-  abstract readonly name: string;
+  readonly name: string;
 
   /**
    * 解析本轮 system messages。
    */
-  abstract resolve(): Promise<SystemModelMessage[]>;
+  resolve(): Promise<SystemModelMessage[]>;
 }

package/src/session/composer/system/default/DefaultSessionSystemComposer.ts

@@ -6,7 +6,7 @@
  * - 具体“解析 / 加载 / 组装”下沉到 SystemDomain，保持类本身轻量。
  */
 
-import {
+import type {
   SessionSystemComposer,
 } from "@session/composer/system/SessionSystemComposer.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
@@ -41,7 +41,7 @@ type DefaultSessionSystemComposerOptions = {
 /**
  * SessionSystemComposer 默认实现。
  */
-export class DefaultSessionSystemComposer extends SessionSystemComposer {
+export class DefaultSessionSystemComposer implements SessionSystemComposer {
   readonly name = "prompt_system";
 
   private readonly projectRoot: string;
@@ -50,7 +50,6 @@ export class DefaultSessionSystemComposer extends SessionSystemComposer {
   private readonly profile: SystemProfile;
 
   constructor(options: DefaultSessionSystemComposerOptions) {
-    super();
     const projectRoot = String(options.projectRoot || "").trim();
     if (!projectRoot) {
       throw new Error("DefaultSessionSystemComposer requires a non-empty projectRoot");

package/src/session/{executors/local/SessionExecutionError.ts → core-engine/CoreEngineError.ts}

@@ -1,9 +1,9 @@
 /**
- * Session 执行错误归一化工具。
+ * CoreEngine 执行错误归一化工具。
  *
  * 关键点（中文）
  * - AI SDK 的最终错误有时只是兜底包装，底层 provider 错误会先从 stream `onError` 暴露。
- * - Runner 只需要消费这里输出的日志字段与最终错误文本。
+ * - Executor 内部 CoreEngine 流程只需要消费这里输出的日志字段与最终错误文本。
  */
 
 import type { JsonObject } from "@/types/common/Json.js";
@@ -28,7 +28,7 @@ export function summarizeStreamError(error: unknown): JsonObject {
 /**
  * 提取实际应返回给上层的错误文本。
  */
-export function resolveEffectiveExecutionError(params: {
+export function resolveEffectiveCoreEngineError(params: {
   /**
    * 外层捕获到的执行错误。
    */

package/src/session/{executors/local/SessionLoopDecision.ts → core-engine/CoreEngineLoopDecision.ts}

@@ -1,8 +1,8 @@
 /**
- * SessionLoopDecision：Runner 执行循环的纯决策模块。
+ * CoreEngineLoopDecision：模型/tool-loop 核心循环的纯决策模块。
  *
  * 关键点（中文）
- * - 把 “是否继续下一轮” 的分支优先级从 Runner 主流程中拆出。
+ * - 把 “是否继续下一轮” 的分支优先级从 CoreEngine 主流程中拆出。
  * - 保持纯函数，不依赖模型、持久化或 logger，便于直接测试。
  */
 
@@ -13,7 +13,7 @@ import type {
 } from "@/session/types/SessionLoop.js";
 
 /**
- * 评估当前 step 完成后，Runner 是否应继续下一轮。
+ * 评估当前 step 完成后，tool-loop 是否应继续下一轮。
  *
  * 优先级（中文）
  * 1. 不完整响应恢复
@@ -21,7 +21,7 @@ import type {
  * 3. text-only 自动续跑
  * 4. 停止
  */
-export function evaluateSessionLoopDecision(
+export function evaluateCoreEngineLoopDecision(
   input: SessionLoopDecisionInput,
 ): SessionLoopDecision {
   if (

package/src/session/{executors/local/SessionModelMessageState.ts → core-engine/CoreEngineMessageState.ts}

@@ -1,8 +1,8 @@
 /**
- * Session 模型消息运行态。
+ * CoreEngine 模型消息运行态。
  *
  * 关键点（中文）
- * - Runner 同时维护 session 语义消息与模型消息。
+ * - CoreEngine 同时维护 session 语义消息与模型消息。
  * - 新增 user 消息可优先做增量转换，失败时再回退为全量重算。
  * - assistant UI 消息只需要进入 session 语义基线；模型侧使用 SDK 返回的 response messages。
  */
@@ -15,9 +15,9 @@ import {
 } from "@session/messages/SessionMessageCodec.js";
 
 /**
- * Runner 单轮执行期间的消息基线。
+ * CoreEngine 单轮执行期间的消息基线。
  */
-export class SessionModelMessageState {
+export class CoreEngineMessageState {
   /**
    * 当前运行时 session 语义消息。
    */
@@ -64,11 +64,11 @@ export class SessionModelMessageState {
      * 当前轮可用工具集合。
      */
     tools: Record<string, Tool>;
-  }): Promise<SessionModelMessageState> {
+  }): Promise<CoreEngineMessageState> {
     const sessionMessages = Array.isArray(params.messages)
       ? [...params.messages]
       : [];
-    return new SessionModelMessageState({
+    return new CoreEngineMessageState({
       sessionMessages,
       modelMessages: await toModelMessages(sessionMessages, params.tools),
       tools: params.tools,

package/src/session/{executors/local/SessionSignals.ts → core-engine/CoreEngineSignals.ts}

@@ -1,10 +1,10 @@
 /**
- * SessionLoopSignals：Runner 执行循环的信号判断与调试摘要工具。
+ * SessionLoopSignals：tool-loop 执行循环的信号判断与调试摘要工具。
  *
  * 关键点（中文）
  * - 这里只放“如何判断继续执行 / 如何输出调试摘要”的纯函数。
- * - 不放 Runner 主流程，避免执行内核被大量辅助细节淹没。
- * - 目标是让 Runner 保持“只看主链路就能理解”的结构。
+ * - 不放 tool-loop 主流程，避免执行内核被大量辅助细节淹没。
+ * - 目标是让 tool-loop 保持“只看主链路就能理解”的结构。
  */
 
 import {

package/src/session/{executors/local/SessionUiStreamCollector.ts → core-engine/CoreEngineUiStreamCollector.ts}

@@ -15,7 +15,7 @@ import { getSessionRunScope } from "@session/SessionRunScope.js";
 import {
   summarizeUiMessageForDebug,
   toInlinePreview,
-} from "@session/executors/local/SessionSignals.js";
+} from "@session/core-engine/CoreEngineSignals.js";
 
 /**
  * 收敛 UI stream 中的最终 assistant 消息。