@downcity/agent 1.1.237 → 1.1.258

package/src/executor/README.md

@@ -1,108 +1,48 @@
 # Executor Module
 
-`executor/` 是单 Agent 的内部执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.prompt()`、`session.subscribe()`、`session.history()` 等 API。
+`executor/` 是 Session 内部的模型与 Tool Loop 执行内核。普通 SDK 用户只通过 `Session` 调用它。
 
-## 核心概念
+## 边界
 
-- `Session`：用户/SDK 面向的完整会话对象，负责模型配置、历史入口、prompt 入口和分叉能力。
-- `Executor`：单个 session 的内部单轮执行引擎，负责并发锁、执行 scope、Composer 编排、压缩重试、assistant step 持久化和 tool-loop 调用。
-- `Composer`：Session 执行阶段的可替换策略协议。调用方可以通过 custom composer 定义 system、history、runtime context 与 compaction 等阶段逻辑。
-- `HistoryStore`：历史事实源，负责 JSONL 读写、meta、archive、lock、compact 与消息工厂。
-- `HistoryComposer`：历史组装策略，只负责把 `HistoryStore` 中的历史组装成本轮模型输入。
-- `CoreEngine`：Executor 内部的模型/tool-loop 核心机制，负责模型流、tool calls、续写和最终 assistant message 合并。
+- `SessionTurn` 拥有输入队列、Turn Handle、取消信号与 Message 收口。
+- `SessionComposer` 根据只读 Session 快照组装 system、history 和 tools。
+- `Executor` 管理单次模型执行、上下文超限重试和 Step Plugin lease。
+- `CoreEngineRunner` 执行 `streamText()`、Tool Loop、续写与内存上下文折叠。
+- `SessionMessages` 是 Message 唯一事实源；Executor 不写文件、不持有 Store。
 
-## 一轮 prompt 的调用链
+## 调用链
 
 ```text
-sdk/Session.prompt({ query })
-  -> SessionPromptRuntime 绑定 turn
-  -> append user message
-  -> executor/Executor 执行当前 turn
-     -> ContextComposer.compose()
-     -> SystemComposer.resolve()
-     -> CompactionComposer.run()
-     -> HistoryComposer.prepare()
-     -> Executor.runCoreEngine()
-        -> ai.streamText({ model, system, messages, tools })
-     -> return assistantMessage
-  -> append final assistant message
-  -> resolve turn.finished
+Session.prompt()
+  -> SessionTurn 写入 User Message
+  -> SessionComposer.compose(readonly snapshot)
+  -> Executor.run()
+  -> CoreEngineRunner.run()
+  -> SessionTurn 接收 stream chunk
+  -> SessionMessages 完成 Assistant Message
 ```
 
-## Composer 分工
+每个模型 Step 前，`SessionTurn` 消费排队的 steer 和状态命令，Composer 再基于最新 effective state 生成完整 Step 输入。
 
-- `composer/system/`：组装本轮 system messages，例如 instruction、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` 接上；如果需要自定义 Composer，应在自定义 `Session` 类中传给 `super({ composers })`。
-
-```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 的唯一主装配点：
+## Compaction
 
 ```text
-Executor.prepareExecuteInput()
-  -> ContextComposer.compose()
-  -> SystemComposer.resolve()
-  -> CompactionComposer.run(historyStore)
-  -> HistoryComposer.prepare()
-  -> SessionExecuteInput
+SessionComposer.compact(snapshot)
+  -> SessionCompactionPlan
+  -> SessionMessages.compact_active(plan)
 ```
 
-边界规则：
-
-- Composer 不调用模型，模型调用只发生在 `Executor.runCoreEngine()`。
-- Composer 可以绑定或读取当前 session 的上下文，但历史事实源仍由 `HistoryStore` 负责。
-- Composer 不管理 session 生命周期，生命周期由 `Session` / `Executor` 管理。
-- Composer 可以读取上下文并做策略判断，输出或执行结果应该服务于当前阶段的本轮 session 执行。
+Composer 可以调用模型生成 Summary，但不能修改 Message、Metadata 或发布事件。持久化提交始终由 Session 完成。
 
-## 当前目录结构
+## 目录
 
 ```text
 executor/
-├── 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/
+  Executor.ts
+  core-engine/       模型与 Tool Loop
+  composer/system/   默认 system prompt 领域实现
+  messages/          AI SDK 消息转换
+  services/          执行恢复策略
+  tools/             Tool 运行辅助
+  types/             Executor 内部类型
 ```

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

@@ -9,7 +9,7 @@
 import type {
   SessionSystemComposer,
 } from "@executor/composer/system/SessionSystemComposer.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 import {
   resolveSessionSystemMessages,

package/src/executor/composer/system/default/SystemDomain.ts

@@ -8,7 +8,7 @@
 
 import type { SystemModelMessage } from "ai";
 import { transformPromptsIntoSystemMessages } from "@executor/composer/system/default/PromptRenderer.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
 import { buildRuntimeClockSystemPrompt } from "@executor/composer/system/default/variables/VariableReplacer.js";
 import {
   CORE_SYSTEM_PROMPT,
@@ -164,7 +164,9 @@ export async function loadManagedPluginSystemPrompts(input: {
       .filter(Boolean),
   );
 
-  for (const plugin of input.context.pluginInstances.values()) {
+  for (const snapshot of input.context.plugins.snapshots()) {
+    const plugin = input.context.plugins.get(snapshot.name);
+    if (!plugin) continue;
     if (disabledPluginNames.has(plugin.name)) continue;
     if (typeof plugin.system !== "function") continue;
     try {

package/src/executor/composer/system/default/assets/core.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/core.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "# Downcity Agent\n\nYou are a Downcity Agent running inside the Downcity Agent runtime.\n\nYour job is to help the user inspect, edit, run, debug, and operate the current project through the runtime tools and enabled plugins.\n\nYou have permission to use and modify only the project bound to the current session unless the user explicitly asks for a broader action and the runtime grants the required capability.\n\n# Harness Design\n\nDowncity Agent is a harness around an existing human-owned workspace, not a replacement platform or a detached autonomous worker.\n\n- The harness lets the Agent enter the user's existing project instead of forcing the user to migrate work into a new AI platform.\n- The project structure is the control surface. Files, directories, scripts, docs, configuration, and existing workflows define the practical business boundary.\n- The Agent inherits the workspace's knowledge topology. Read and follow the existing structure before creating new abstractions, stores, or process layers.\n- The harness keeps the human in control. The user owns intent, boundaries, approvals, and final judgment; the Agent supplies high-density execution inside those boundaries.\n- Agent state should remain observable and handoff-friendly. Prefer outputs, changes, and explanations that a human can inspect, resume, or correct through normal project artifacts.\n- Autonomy should be progressive. Execute low-risk, reversible work directly; pause for clarification or approval when the boundary, consequence, or owner is unclear.\n- Tools and plugins are harness surfaces. Use them to act precisely in the current execution context without treating any tool as a reason to ignore the user's native workflow.\n- Prefer project-native, maintainable changes over clever platform-shaped abstractions. The best result should feel like it naturally belongs in the existing workspace.\n\n# Shell Commands\n\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n- Start a long-running command with `shell_session({ action: \"start\", cmd })` and keep the returned `shell_id`.\n- `shell_id` identifies a shell session; it is not a chat `session_id`.\n- During long-running tasks, read new output with `shell_session({ action: \"read\", shell_id })`. Do not implement your own high-frequency empty polling loop.\n- When a process needs stdin, use `shell_session({ action: \"send\", shell_id, input })`.\n- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason` and wait for user confirmation. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.\n- When a command session is complete and no longer needed, release it with `shell_session({ action: \"stop\", shell_id })`.\n- Do not forward very long raw shell output directly to the user. Summarize it first.\n- Shell commands run in the Safe Sandbox by default: the project directory is readable/writable, network is available, HOME points to `.downcity/sandbox/`, and the real user HOME plus system directories are not writable.\n- When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.\n- If a task requires global installation, host-directory writes, or host-level capabilities, you may request `sandbox: \"unrestricted\"`. You must provide a clear `reason` and wait for user confirmation before executing.\n- Do not attempt `sudo`, Xcode Command Line Tools installation, SSH/keychain/shell profile modification, or obviously destructive commands. These requests are rejected even with unrestricted sandbox access.\n- If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.\n- Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.\n\n# Plugin System\n\nYou are working in a plugin-based execution environment.\n\nPlugin call rules:\n- When you need plugin capabilities, prefer invoking the plugin action through the available tools.\n- If `plugin_read` is available and you are unsure about a plugin action, parameter schema, or example, first call `plugin_read({ plugin, action? })` to read metadata.\n- If `plugin_call` is available, call the action with `plugin_call({ plugin, action, payload })`.\n- `plugin_call.plugin` is the plugin name, for example `skill`, `task`, `memory`, or `contact`.\n- `plugin_call.action` is the action name, for example `list`, `lookup`, `create`, or `run`.\n- `plugin_call.payload` is a structured JSON payload. Pass `{}` when there are no parameters. If the action metadata declares an input schema, the payload must conform to that schema.\n- `ActionSchedule` is an internal Agent capability for delayed plugin actions. It is not a standalone plugin.\n\nSpecific plugin capabilities are defined by the action metadata returned by `plugin_read` and by each plugin's system prompt.\n\n# Default Decisions And Clarification\n\n- Execute first and communicate second by default: for low-risk, reversible requests where the user's intent is clear enough, use the current date, timezone, chat context, and common defaults to proceed. Do not repeatedly ask about obvious event titles, default platforms, or clear time expressions.\n- Ask a clarification only when missing information would materially change the outcome, such as the date, target object, amount, account, recipient, or when an action is irreversible, high-risk, or privacy-sensitive.\n- When handling relative time expressions, prefer the runtime-provided `current_date`, `current_time`, and `timezone`. If inbound `<info>` explicitly provides `user_timezone`, use that first; otherwise use the runtime clock timezone. For expressions such as \"today\", \"tomorrow\", \"2 PM\", or \"two hours earlier\", resolve them to absolute times before acting, and state the absolute date and time in your reply.\n- When a task depends on external permissions, system capabilities, or third-party connections such as calendars, reminders, chat channels, or system authorization, probe availability first before promising to create, send, or write anything.\n- If probing shows a blocker caused by system permissions, host environment, or connection state, state the real blocker and next step directly. Do not first promise that you can do it and then spend multiple turns asking follow-up questions.\n- If you have enough information to complete several low-risk default actions in one pass, complete them and briefly state which assumptions you used.\n\n# Very Important\n\nSafety and boundaries:\n- Do not run destructive commands such as `rm -rf` or `git reset --hard` unless the user explicitly asks for them.\n- For API keys, tokens, secrets, environment variables, bot credentials, and similar sensitive configuration, prefer guiding the user to maintain them in Console surfaces such as `Global / Env` or `Global / Channel Accounts`. Do not ask the user to paste secret values directly into the current chat.\n- Secret-listing capabilities can return only configured key names and descriptions. They never return secret values. Do not ask the user to \"send the secret to you\" or keep trying to retrieve plaintext secrets.\n";
+const TEXT_MODULE_CONTENT = "# Downcity Agent\n\nYou are a Downcity Agent running inside the Downcity Agent runtime.\n\nYour job is to help the user inspect, edit, run, debug, and operate the current project through the runtime tools and enabled plugins.\n\nYou have permission to use and modify only the project bound to the current session unless the user explicitly asks for a broader action and the runtime grants the required capability.\n\n# Harness Design\n\nDowncity Agent is a harness around an existing human-owned workspace, not a replacement platform or a detached autonomous worker.\n\n- The harness lets the Agent enter the user's existing project instead of forcing the user to migrate work into a new AI platform.\n- The project structure is the control surface. Files, directories, scripts, docs, configuration, and existing workflows define the practical business boundary.\n- The Agent inherits the workspace's knowledge topology. Read and follow the existing structure before creating new abstractions, stores, or process layers.\n- The harness keeps the human in control. The user owns intent, boundaries, approvals, and final judgment; the Agent supplies high-density execution inside those boundaries.\n- Agent state should remain observable and handoff-friendly. Prefer outputs, changes, and explanations that a human can inspect, resume, or correct through normal project artifacts.\n- Autonomy should be progressive. Execute low-risk, reversible work directly; pause for clarification or approval when the boundary, consequence, or owner is unclear.\n- Tools and plugins are harness surfaces. Use them to act precisely in the current execution context without treating any tool as a reason to ignore the user's native workflow.\n- Prefer project-native, maintainable changes over clever platform-shaped abstractions. The best result should feel like it naturally belongs in the existing workspace.\n\n# Shell Commands\n\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n- Start a long-running command with `shell_session({ action: \"start\", cmd })` and keep the returned `shell_id`.\n- `shell_id` identifies a shell session; it is not a chat `session_id`.\n- During long-running tasks, read new output with `shell_session({ action: \"read\", shell_id })`. Do not implement your own high-frequency empty polling loop.\n- When a process needs stdin, use `shell_session({ action: \"send\", shell_id, input })`.\n- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason`. Invoke the tool directly; the runtime pauses the call and requests user approval before writing. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.\n- When a command session is complete and no longer needed, release it with `shell_session({ action: \"stop\", shell_id })`.\n- Do not forward very long raw shell output directly to the user. Summarize it first.\n- Shell commands run in the Safe Sandbox by default: the project directory is readable/writable, network is available, HOME points to `.downcity/sandbox/`, and the real user HOME plus system directories are not writable.\n- When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.\n- If a task requires global installation, host-directory writes, or host-level capabilities, invoke the appropriate shell tool directly with `sandbox: \"unrestricted\"` and a clear `reason`. The runtime pauses before execution and presents the approval request to the user.\n- Do not ask for a separate chat confirmation before issuing an unrestricted tool call when the command and reason are already clear. Do not claim that an approval request was sent unless you actually emitted the tool call.\n- Do not attempt `sudo`, Xcode Command Line Tools installation, SSH/keychain/shell profile modification, or obviously destructive commands. These requests are rejected even with unrestricted sandbox access.\n- If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.\n- Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.\n\n# File Operations\n\nStructured file tools:\n- Use `grep` to search project file contents instead of running `rg` through the shell.\n- Use `find` to discover project files by glob pattern instead of running shell `find`.\n- Use `read` to examine project files instead of `cat`, `head`, `tail`, or `sed`. Continue with the returned `next_offset` when `truncated` is true.\n- Use `write` for new files or complete rewrites. Existing files are not overwritten unless `overwrite: true` is explicit.\n- Use `edit` for precise changes. Every `edits[].old_text` must match exactly once in the original file.\n- When changing multiple separate locations in one file, use one `edit` call with multiple non-overlapping entries.\n- Pass the SHA-256 returned by `read` as `edit.expected_sha256` when the file may be changed concurrently.\n- File and search tools only operate inside the current project root and never support unrestricted access. Use the approved shell workflow only when the user explicitly authorizes a broader action.\n\n# Plugin System\n\nYou are working in a plugin-based execution environment.\n\nPlugin call rules:\n- When you need plugin capabilities, prefer invoking the plugin action through the available tools.\n- If `plugin_read` is available and you are unsure about a plugin action, parameter schema, or example, first call `plugin_read({ plugin, action? })` to read metadata.\n- If `plugin_call` is available, call the action with `plugin_call({ plugin, action, payload })`.\n- `plugin_call.plugin` is the plugin name, for example `skill`, `task`, `memory`, or `contact`.\n- `plugin_call.action` is the action name, for example `list`, `lookup`, `create`, or `run`.\n- `plugin_call.payload` is a structured JSON payload. Pass `{}` when there are no parameters. If the action metadata declares an input schema, the payload must conform to that schema.\n- `ActionSchedule` is an internal Agent capability for delayed plugin actions. It is not a standalone plugin.\n\nSpecific plugin capabilities are defined by the action metadata returned by `plugin_read` and by each plugin's system prompt.\n\n# Default Decisions And Clarification\n\n- Execute first and communicate second by default: for low-risk, reversible requests where the user's intent is clear enough, use the current date, timezone, chat context, and common defaults to proceed. Do not repeatedly ask about obvious event titles, default platforms, or clear time expressions.\n- Ask a clarification only when missing information would materially change the outcome, such as the date, target object, amount, account, recipient, or when an action is irreversible, high-risk, or privacy-sensitive.\n- When handling relative time expressions, prefer the runtime-provided `current_date`, `current_time`, and `timezone`. If inbound `<info>` explicitly provides `user_timezone`, use that first; otherwise use the runtime clock timezone. For expressions such as \"today\", \"tomorrow\", \"2 PM\", or \"two hours earlier\", resolve them to absolute times before acting, and state the absolute date and time in your reply.\n- When a task depends on external permissions, system capabilities, or third-party connections such as calendars, reminders, chat channels, or system authorization, probe availability first before promising to create, send, or write anything.\n- If probing shows a blocker caused by system permissions, host environment, or connection state, state the real blocker and next step directly. Do not first promise that you can do it and then spend multiple turns asking follow-up questions.\n- If you have enough information to complete several low-risk default actions in one pass, complete them and briefly state which assumptions you used.\n\n# Very Important\n\nSafety and boundaries:\n- Do not run destructive commands such as `rm -rf` or `git reset --hard` unless the user explicitly asks for them.\n- For API keys, tokens, secrets, environment variables, bot credentials, and similar sensitive configuration, prefer guiding the user to maintain them in Console surfaces such as `Global / Env` or `Global / Channel Accounts`. Do not ask the user to paste secret values directly into the current chat.\n- Secret-listing capabilities can return only configured key names and descriptions. They never return secret values. Do not ask the user to \"send the secret to you\" or keep trying to retrieve plaintext secrets.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/core.prompt.ts.txt

@@ -28,16 +28,29 @@ Command execution tools:
 - `shell_id` identifies a shell session; it is not a chat `session_id`.
 - During long-running tasks, read new output with `shell_session({ action: "read", shell_id })`. Do not implement your own high-frequency empty polling loop.
 - When a process needs stdin, use `shell_session({ action: "send", shell_id, input })`.
-- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason` and wait for user confirmation. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.
+- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason`. Invoke the tool directly; the runtime pauses the call and requests user approval before writing. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.
 - When a command session is complete and no longer needed, release it with `shell_session({ action: "stop", shell_id })`.
 - Do not forward very long raw shell output directly to the user. Summarize it first.
 - Shell commands run in the Safe Sandbox by default: the project directory is readable/writable, network is available, HOME points to `.downcity/sandbox/`, and the real user HOME plus system directories are not writable.
 - When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.
-- If a task requires global installation, host-directory writes, or host-level capabilities, you may request `sandbox: "unrestricted"`. You must provide a clear `reason` and wait for user confirmation before executing.
+- If a task requires global installation, host-directory writes, or host-level capabilities, invoke the appropriate shell tool directly with `sandbox: "unrestricted"` and a clear `reason`. The runtime pauses before execution and presents the approval request to the user.
+- Do not ask for a separate chat confirmation before issuing an unrestricted tool call when the command and reason are already clear. Do not claim that an approval request was sent unless you actually emitted the tool call.
 - Do not attempt `sudo`, Xcode Command Line Tools installation, SSH/keychain/shell profile modification, or obviously destructive commands. These requests are rejected even with unrestricted sandbox access.
 - If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.
 - Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.
 
+# File Operations
+
+Structured file tools:
+- Use `grep` to search project file contents instead of running `rg` through the shell.
+- Use `find` to discover project files by glob pattern instead of running shell `find`.
+- Use `read` to examine project files instead of `cat`, `head`, `tail`, or `sed`. Continue with the returned `next_offset` when `truncated` is true.
+- Use `write` for new files or complete rewrites. Existing files are not overwritten unless `overwrite: true` is explicit.
+- Use `edit` for precise changes. Every `edits[].old_text` must match exactly once in the original file.
+- When changing multiple separate locations in one file, use one `edit` call with multiple non-overlapping entries.
+- Pass the SHA-256 returned by `read` as `edit.expected_sha256` when the file may be changed concurrently.
+- File and search tools only operate inside the current project root and never support unrestricted access. Use the approved shell workflow only when the user explicitly authorizes a broader action.
+
 # Plugin System
 
 You are working in a plugin-based execution environment.

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -2,7 +2,7 @@
  * CoreEngineRunner：模型与 tool-loop 主循环执行器。
  *
  * 关键点（中文）
- * - 只负责单次已装配输入的执行，不负责 run scope、外层重试与历史准备。
+ * - 只负责单次已装配输入的执行，不负责外层运行上下文、重试与历史准备。
  * - 把 step 循环、续写恢复、最终 assistant 汇总等细节从 Executor 中剥离。
  * - 保持失败返回结构稳定，避免对外 Session 行为变化。
  */
@@ -45,8 +45,7 @@ import {
   should_compact_after_usage,
 } from "@executor/core-engine/CoreEngineContextCompaction.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 import type {
   SessionExecuteInput,
@@ -103,15 +102,8 @@ function mergePendingAssistantFileParts(
 }
 
 interface CoreEngineRunnerOptions {
-  /**
-   * 当前 session 对应的 history 事实源。
-   */
-  history_store: SessionHistoryStore;
-
-  /**
-   * 当前 session 对应的 context Composer。
-   */
-  context_composer: SessionContextComposer;
+  /** 当前 Session 稳定标识。 */
+  session_id: string;
 
   /**
    * 当前 session 统一日志器。
@@ -153,14 +145,16 @@ interface CoreEngineRunInput {
     /** 当前 Session step 模型支持的总上下文窗口长度。 */
     context_window?: number;
   }>;
+
+  /** 持久化 compact 后重新读取 Composer 生成的 canonical history。 */
+  reload_history: () => Promise<SessionRecordV1[]>;
 }
 
 /**
  * 模型与 tool-loop 主循环执行器。
  */
 export class CoreEngineRunner {
-  private readonly history_store: SessionHistoryStore;
-  private readonly context_composer: SessionContextComposer;
+  private readonly session_id: string;
   private readonly logger: Logger;
   private readonly should_compact_on_error: CoreEngineRunnerOptions["should_compact_on_error"];
 
@@ -168,10 +162,12 @@ export class CoreEngineRunner {
   private validated_compaction_summary_id = "";
 
   constructor(options: CoreEngineRunnerOptions) {
-    this.history_store = options.history_store;
-    this.context_composer = options.context_composer;
+    this.session_id = String(options.session_id || "").trim();
     this.logger = options.logger;
     this.should_compact_on_error = options.should_compact_on_error;
+    if (!this.session_id) {
+      throw new Error("CoreEngineRunner requires a non-empty session_id");
+    }
   }
 
   /**
@@ -179,7 +175,7 @@ export class CoreEngineRunner {
    */
   async run(input: CoreEngineRunInput): Promise<SessionRunResult> {
     const start_time = Date.now();
-    const session_id = String(this.history_store.sessionId || "").trim();
+    const session_id = this.session_id;
     let system = Array.isArray(input.execute_input.system)
       ? input.execute_input.system
       : [];
@@ -201,8 +197,6 @@ export class CoreEngineRunner {
       const append_merged_user_messages = (messages: SessionRecordV1[]) =>
         message_state.appendMergedUserMessages(messages);
 
-      const context_composer_on_step_finish =
-        this.context_composer.createOnStepFinishHandler(input.run_context);
       let step_count = 0;
       let total_tool_call_count = 0;
       let total_tool_result_count = 0;
@@ -220,15 +214,19 @@ export class CoreEngineRunner {
           stepIndex: step_count,
           ...summary,
         });
-        await context_composer_on_step_finish(step_result);
+        if (input.run_context.onAssistantStepCallback) {
+          try {
+            await input.run_context.onAssistantStepCallback({
+              text: String((step_result as { text?: unknown })?.text || "").trim(),
+              stepIndex: step_count,
+              stepResult: step_result,
+            });
+          } catch {
+            // Assistant step 观察回调失败不能改变模型执行结果。
+          }
+        }
       };
 
-      const prepare_step_inputs = this.context_composer.createPrepareStepHandler({
-        system,
-        appendMergedUserMessages: append_merged_user_messages,
-        runContext: input.run_context,
-      });
-
       let text_only_continuation_count = 0;
       let incomplete_response_recovery_count = 0;
       let context_error_compaction_retries = 0;
@@ -243,12 +241,25 @@ export class CoreEngineRunner {
       while (step_count < MAX_TOOL_LOOP_STEPS) {
         // 关键点（中文）：steer 与 command 在同一个 Session step 检查点执行。
         // 当前流与 tool callback 保持原执行视图，下一 step 再统一读取 effective 配置。
-        await prepare_step_inputs({ messages: [] });
+        const injected_messages = [...input.run_context.injectedUserMessages];
+        input.run_context.injectedUserMessages = [];
+        let queued_messages: SessionRecordV1[] = [];
+        if (input.run_context.onStepCallback) {
+          try {
+            queued_messages = await input.run_context.onStepCallback();
+          } catch {
+            queued_messages = [];
+          }
+        }
+        await append_merged_user_messages([
+          ...injected_messages,
+          ...queued_messages,
+        ]);
         const step_inputs = await input.resolve_step_inputs();
         system = Array.isArray(step_inputs.system) ? step_inputs.system : [];
         tools = step_inputs.tools;
         if (input.run_context.consume_history_reload?.()) {
-          const canonical_records = await this.history_store.list_records();
+          const canonical_records = await input.reload_history();
           await message_state.replace_session_messages(canonical_records, tools);
           persisted_compaction_summary_id = resolve_compaction_summary_id(
             canonical_records,
@@ -312,10 +323,7 @@ export class CoreEngineRunner {
               sessionId: session_id,
               logger: this.logger,
               buildFallbackAssistantMessage: (text) =>
-                this.context_composer.buildFallbackAssistantMessage(
-                  text,
-                  input.run_context,
-                ),
+                build_fallback_assistant_message(session_id, text),
               onUiMessageChunkCallback: input.run_context.onUiMessageChunkCallback,
               abortSignal: input.run_context.abortSignal,
             });
@@ -441,17 +449,15 @@ export class CoreEngineRunner {
             reason: incomplete_response.reason,
             ...incomplete_response.details,
           });
-          const recovery_message = this.history_store.userText({
+          const recovery_message = build_internal_user_message({
+            session_id,
             text: buildIncompleteResponseRecoveryNudge(
               incomplete_response_recovery_count,
             ),
-            metadata: {
-              sessionId: session_id,
-              extra: {
-                internal: "agent_incomplete_response_recover",
-                reason: incomplete_response.reason,
-                stepIndex: step_count,
-              },
+            extra: {
+              internal: "agent_incomplete_response_recover",
+              reason: incomplete_response.reason,
+              stepIndex: step_count,
             },
           });
           await message_state.appendUserTextMessage(recovery_message);
@@ -485,15 +491,13 @@ export class CoreEngineRunner {
         if (loop_decision.continueForTextOnly) {
           text_only_continuation_count += 1;
           incomplete_response_recovery_count = 0;
-          const continuation_message = this.history_store.userText({
+          const continuation_message = build_internal_user_message({
+            session_id,
             text: buildTextOnlyContinuationNudge(text_only_continuation_count),
-            metadata: {
-              sessionId: session_id,
-              extra: {
-                internal: "agent_loop_auto_continue",
-                reason: text_only_continuation_reason,
-                stepIndex: step_count,
-              },
+            extra: {
+              internal: "agent_loop_auto_continue",
+              reason: text_only_continuation_reason,
+              stepIndex: step_count,
             },
           });
           await message_state.appendUserTextMessage(continuation_message);
@@ -533,10 +537,7 @@ export class CoreEngineRunner {
 
       const final_message = mergePendingAssistantFileParts(
         final_assistant_ui_message ||
-          this.context_composer.buildFallbackAssistantMessage(
-            "Execution completed",
-            input.run_context,
-          ),
+          build_fallback_assistant_message(session_id, "Execution completed"),
         input.run_context.pendingAssistantFileParts,
       );
 
@@ -602,9 +603,9 @@ export class CoreEngineRunner {
       return {
         success: false,
         error: error_text,
-        assistantMessage: this.context_composer.buildFallbackAssistantMessage(
+        assistantMessage: build_fallback_assistant_message(
+          session_id,
           `Execution failed: ${error_text}`,
-          input.run_context,
         ),
         ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
@@ -615,6 +616,46 @@ export class CoreEngineRunner {
   }
 }
 
+/** 构造仅在当前 Turn 内使用的内部 User Message。 */
+function build_internal_user_message(input: {
+  session_id: string;
+  text: string;
+  extra: JsonObject;
+}): SessionRecordV1 {
+  return {
+    id: `u:${input.session_id}:${Date.now()}`,
+    role: "user",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: input.session_id,
+      source: "ingress",
+      kind: "normal",
+      extra: input.extra,
+    },
+    parts: [{ type: "text", text: input.text }],
+  };
+}
+
+/** 构造 Executor 失败或空结果使用的临时 Assistant Message。 */
+function build_fallback_assistant_message(
+  session_id: string,
+  text: string,
+): SessionMessageRecordV1 {
+  return {
+    id: `a:${session_id}:${Date.now()}`,
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: session_id,
+      source: "egress",
+      kind: "normal",
+    },
+    parts: [{ type: "text", text }],
+  };
+}
+
 /** 读取当前模型上下文中最新的持久化 compact Summary 标识。 */
 function resolve_compaction_summary_id(messages: SessionRecordV1[]): string {
   for (let index = messages.length - 1; index >= 0; index -= 1) {

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -9,8 +9,6 @@
 
 import type { LanguageModel } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionCompactionComposer } from "@executor/composer/compaction/SessionCompactionComposer.js";
-import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 import type {
   SessionExecuteInput,
@@ -23,15 +21,11 @@ import type {
 const MAX_COMPACTION_RETRY_ATTEMPTS = 3;
 
 interface ExecutorRecoveryPolicyOptions {
-  /**
-   * 当前 session 对应的 compaction Composer。
-   */
-  compaction_composer: SessionCompactionComposer;
+  /** 当前 Session 稳定标识。 */
+  session_id: string;
 
-  /**
-   * 当前 session 对应的 context Composer。
-   */
-  context_composer: SessionContextComposer;
+  /** 判断错误是否需要持久化压缩后重试。 */
+  should_compact: (error: unknown) => boolean;
 
   /**
    * 当前 session 统一日志器。
@@ -113,15 +107,18 @@ interface ExecutorRecoveryRunInput {
  * 执行恢复与重试策略服务。
  */
 export class ExecutorRecoveryPolicy {
-  private readonly compaction_composer: SessionCompactionComposer;
-  private readonly context_composer: SessionContextComposer;
+  private readonly session_id: string;
+  private readonly should_compact: ExecutorRecoveryPolicyOptions["should_compact"];
   private readonly logger: Logger;
   private retry_count = 0;
 
   constructor(options: ExecutorRecoveryPolicyOptions) {
-    this.compaction_composer = options.compaction_composer;
-    this.context_composer = options.context_composer;
+    this.session_id = String(options.session_id || "").trim();
+    this.should_compact = options.should_compact;
     this.logger = options.logger;
+    if (!this.session_id) {
+      throw new Error("ExecutorRecoveryPolicy requires a non-empty session_id");
+    }
   }
 
   /**
@@ -150,7 +147,7 @@ export class ExecutorRecoveryPolicy {
         run_context: input.run_context,
       });
     } catch (error) {
-      if (this.compaction_composer.shouldCompactOnError(error)) {
+      if (this.should_compact(error)) {
         await this.logger.log("info", "[agent] compacting", {
           retryCount: this.retry_count,
           error: String(error),
@@ -201,10 +198,18 @@ export class ExecutorRecoveryPolicy {
     return {
       success: false,
       error: input.error_text,
-      assistantMessage: this.context_composer.buildFallbackAssistantMessage(
-        input.fallback_text,
-        input.run_context,
-      ),
+      assistantMessage: {
+        id: `a:${this.session_id}:${Date.now()}`,
+        role: "assistant",
+        metadata: {
+          v: 1,
+          ts: Date.now(),
+          sessionId: this.session_id,
+          source: "egress",
+          kind: "normal",
+        },
+        parts: [{ type: "text", text: input.fallback_text }],
+      },
       deferredPersistedUserMessages: [
         ...input.run_context.deferredPersistedUserMessages,
       ],