@downcity/agent 1.1.287 → 1.1.310

package/src/executor/Executor.ts

@@ -3,26 +3,29 @@
  *
  * 关键点（中文）
  * - SDK 对外对象叫 `Session`，这里是内部执行层。
- * - 一个 Executor 只对应一个固定的 `sessionId`。
- * - 负责 history 写入、显式运行上下文、executing 状态、Composer 编排与 tool-loop 执行。
+ * - 一个 Executor 只对应一个固定的 `session_id`。
+ * - 负责显式 Turn 上下文消费、executing 状态、Composer 编排与 Tool Loop 执行。
  */
 
 import type { LanguageModel, Tool, ToolExecutionOptions } from "ai";
 import { CoreEngineRunner } from "@executor/core-engine/CoreEngineRunner.js";
 import { ExecutorRecoveryPolicy } from "@executor/services/ExecutorRecoveryPolicy.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type {
+  SessionCompactHistory,
+  SessionExecutor,
+} from "@/types/session/SessionExecution.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import { inject_read_image_user_message } from "@executor/tools/file/ReadImageToolBridge.js";
+import { is_action_result } from "@/types/action/ActionResult.js";
+import { generate_id } from "@/utils/Id.js";
 import type {
-  SessionExecuteInput,
-  SessionRunResult,
-} from "@/executor/types/SessionRun.js";
+  SessionStepExecutionInput,
+  SessionTurnExecutionResult,
+} from "@/types/session/SessionExecution.js";
 import type {
   SessionComposer,
-  SessionCompactionPlan,
   SessionComposeInput,
   SessionStepInput,
 } from "@/types/session/SessionComposer.js";
@@ -31,30 +34,27 @@ type ExecutorOptions = {
   /**
    * 当前会话 ID。
    */
-  sessionId: string;
+  session_id: string;
 
   /** 当前 Session 使用的统一 Composer。 */
   composer: SessionComposer;
 
   /** 为 Composer 创建当前 Step 的只读输入快照。 */
   get_compose_input: (
-    run_context: SessionRunContext,
+    turn_context: SessionTurnContext | undefined,
     retry_count: number,
   ) => Promise<SessionComposeInput>;
 
   /** 应用 Session 级固定 system snapshot。 */
   apply_system_snapshot?: (input: SessionStepInput) => SessionStepInput;
 
-  /** 提交 Composer 生成的持久化压缩计划。 */
-  commit_compaction: (
-    plan: SessionCompactionPlan,
-    run_context: SessionRunContext,
-  ) => Promise<void>;
+  /** 请求 Session 领域生成并提交 canonical 历史压缩。 */
+  compact_history: SessionCompactHistory;
 
   /**
    * 读取当前 session 使用的模型实例。
    */
-  getModel: () => LanguageModel | undefined;
+  get_model: () => LanguageModel | undefined;
 
   /**
    * 统一日志器。
@@ -72,42 +72,41 @@ export class Executor implements SessionExecutor {
   /**
    * 当前 session 标识。
    */
-  readonly sessionId: string;
+  readonly session_id: string;
 
   private readonly composer: SessionComposer;
   private readonly get_compose_input: ExecutorOptions["get_compose_input"];
   private readonly apply_system_snapshot?: ExecutorOptions["apply_system_snapshot"];
-  private readonly commit_compaction: ExecutorOptions["commit_compaction"];
-  private readonly getModel: ExecutorOptions["getModel"];
+  private readonly compact_history: ExecutorOptions["compact_history"];
+  private readonly get_model: ExecutorOptions["get_model"];
   private readonly get_plugins: ExecutorOptions["get_plugins"];
   private readonly logger: Logger;
   private readonly recovery_policy: ExecutorRecoveryPolicy;
   private readonly core_engine_runner: CoreEngineRunner;
 
   private executing = false;
-  private abort_controller: AbortController | null = null;
 
   constructor(options: ExecutorOptions) {
-    const sessionId = String(options.sessionId || "").trim();
-    if (!sessionId) {
-      throw new Error("Executor requires a non-empty sessionId");
+    const session_id = String(options.session_id || "").trim();
+    if (!session_id) {
+      throw new Error("Executor requires a non-empty session_id");
     }
 
-    this.sessionId = sessionId;
+    this.session_id = session_id;
     this.composer = options.composer;
     this.get_compose_input = options.get_compose_input;
     this.apply_system_snapshot = options.apply_system_snapshot;
-    this.commit_compaction = options.commit_compaction;
-    this.getModel = options.getModel;
+    this.compact_history = options.compact_history;
+    this.get_model = options.get_model;
     this.get_plugins = options.get_plugins;
     this.logger = options.logger;
     this.recovery_policy = new ExecutorRecoveryPolicy({
-      session_id: this.sessionId,
+      session_id: this.session_id,
       should_compact: (error) => this.composer.should_compact(error),
       logger: this.logger,
     });
     this.core_engine_runner = new CoreEngineRunner({
-      session_id: this.sessionId,
+      session_id: this.session_id,
       logger: this.logger,
       should_compact_on_error: (error) =>
         this.composer.should_compact(error),
@@ -117,103 +116,61 @@ export class Executor implements SessionExecutor {
   /**
    * 返回当前 session 是否正在执行。
    */
-  isExecuting(): boolean {
+  is_executing(): boolean {
     return this.executing;
   }
 
   /**
-   * 请求停止当前执行。
-   */
-  stop(): boolean {
-    if (!this.executing || !this.abort_controller) return false;
-    if (!this.abort_controller.signal.aborted) {
-      this.abort_controller.abort(new Error("Turn stopped"));
-    }
-    return true;
-  }
-
-  /**
-   * 获取当前 session 的执行端口。
-   *
-   * 关键点（中文）
-   * - 兼容 runtime/service 端口语义：Executor 自己就是执行端口。
-   */
-  getExecutor(): SessionExecutor {
-    return this;
-  }
-
-  /**
-   * 运行当前 session 的一次请求。
+   * 执行当前 Session 的一次 Turn。
    *
    * 关键点（中文）
-   * - 这里直接承接单个 Session 实例的一次 run 外层编排。
+   * - 这里直接承接单个 Session 实例的一次 Turn 执行编排。
    * - scope 绑定、assistant step 持久化、executing 状态都收在实例内部。
    */
-  async run(params: {
+  async execute(params: {
     query: string;
-    runContext?: SessionRunContext;
-  }): Promise<SessionRunResult> {
+    turn_context: SessionTurnContext;
+  }): Promise<SessionTurnExecutionResult> {
     if (this.executing) {
-      // 关键点（中文）：同一个 Session 实例只允许一个活跃 run，
+      // 关键点（中文）：同一个 Session 实例只允许一个活跃 Turn 执行，
       // 否则 step 回调、scope 与执行器状态都会互相污染。
-      throw new Error("Executor.run does not support concurrent execution");
+      throw new Error("Executor.execute does not support concurrent execution");
     }
     const query = String(params.query || "").trim();
-    const run_context = this.createRunContext(params.runContext);
-    const upstream_abort_signal = run_context.abortSignal;
-    const abort_controller = new AbortController();
-    const abort_from_upstream = () => {
-      if (!abort_controller.signal.aborted) {
-        abort_controller.abort(upstream_abort_signal?.reason);
-      }
-    };
-    if (upstream_abort_signal?.aborted) {
-      abort_from_upstream();
-    } else {
-      upstream_abort_signal?.addEventListener("abort", abort_from_upstream, {
-        once: true,
-      });
-    }
-    this.abort_controller = abort_controller;
-    run_context.abortSignal = abort_controller.signal;
+    const turn_context = params.turn_context;
     this.executing = true;
-    this.recovery_policy.reset_run_state();
+    this.recovery_policy.reset_execution_state();
     try {
-      const result = await this.recovery_policy.run_with_retry({
+      const result = await this.recovery_policy.execute_with_retry({
         query,
-        model: this.resolveModelOrThrow(),
-        run_context,
+        model: this.resolve_model_or_throw(),
+        turn_context,
         prepare_execute_input: async ({
           query: next_query,
           model,
-          run_context: next_run_context,
+          turn_context: next_turn_context,
           retry_count,
         }) =>
-          await this.prepareExecuteInput(
+          await this.prepare_execute_input(
             next_query,
             model,
-            next_run_context,
+            next_turn_context,
             retry_count,
           ),
-        execute_prepared_run: async ({
+        execute_prepared_input: async ({
           execute_input,
           model,
-          run_context: next_run_context,
+          turn_context: next_turn_context,
         }) =>
-          await this.executePreparedRun(
+          await this.execute_prepared_input(
             execute_input,
             model,
-            next_run_context,
+            next_turn_context,
           ),
       });
       return result;
     } finally {
-      await this.release_step_plugins(run_context);
-      this.recovery_policy.reset_run_state();
-      if (this.abort_controller === abort_controller) {
-        this.abort_controller = null;
-      }
-      upstream_abort_signal?.removeEventListener("abort", abort_from_upstream);
+      this.recovery_policy.reset_execution_state();
       this.executing = false;
     }
   }
@@ -221,19 +178,21 @@ export class Executor implements SessionExecutor {
   /**
    * 调用 Composer 组装当前轮执行输入。
    */
-  private async prepareExecuteInput(
+  private async prepare_execute_input(
     query: string,
     _model: LanguageModel,
-    run_context: SessionRunContext,
+    turn_context: SessionTurnContext,
     retry_count: number,
-  ): Promise<SessionExecuteInput> {
+  ): Promise<SessionStepExecutionInput> {
     if (retry_count > 0) {
       await this.logger.log("info", "[agent] compacting", {
         retryCount: retry_count,
       });
-      await this.compact_history(run_context, retry_count);
+      await this.compact_history({
+        turn_id: turn_context.session.turn_id,
+      });
     }
-    const step = await this.compose_step(run_context, retry_count, true);
+    const step = await this.compose_step(turn_context, retry_count, true);
     return {
       query,
       system: step.input.system,
@@ -243,57 +202,24 @@ export class Executor implements SessionExecutor {
   }
 
   /**
-   * 执行一次已装配完成的运行材料。
+   * 执行一次已装配完成的 Step 输入。
    */
-  private async executePreparedRun(
-    input: SessionExecuteInput,
+  private async execute_prepared_input(
+    input: SessionStepExecutionInput,
     model: LanguageModel,
-    run_context: SessionRunContext,
-  ): Promise<SessionRunResult> {
-    return await this.core_engine_runner.run({
+    turn_context: SessionTurnContext,
+  ): Promise<SessionTurnExecutionResult> {
+    return await this.core_engine_runner.execute({
       execute_input: input,
       model,
-      run_context,
+      turn_context,
       resolve_step_inputs: async () =>
-        await this.resolve_step_inputs(run_context),
+        await this.resolve_step_inputs(turn_context),
       reload_history: async () =>
-        (await this.compose_step(run_context, 0, false)).input.messages,
+        (await this.compose_step(turn_context, 0, false)).input.messages,
     });
   }
 
-  /**
-   * 在 Assistant writer 完成后归档当前 canonical 历史。
-   *
-   * 关键点（中文）：持久化 compact 不能发生在流式 Assistant 草稿仍打开时，
-   * 因此由 SessionTurn 在 writer complete/fail 之后显式调用。
-   */
-  async compact_history(
-    run_context: SessionRunContext,
-    retry_count = 0,
-  ): Promise<{
-    compacted: boolean;
-    reason?: string;
-  }> {
-    try {
-      const composed = await this.compose_step(
-        run_context,
-        retry_count,
-        true,
-      );
-      const plan = await this.composer.compact({
-        ...composed.compose_input,
-        force: true,
-      });
-      if (!plan) return { compacted: false, reason: "nothing_to_compact" };
-      await this.commit_compaction(plan, run_context);
-      return { compacted: true };
-    } catch (error) {
-      return { compacted: false, reason: "compact_failed" };
-    } finally {
-      await this.release_step_plugins(run_context);
-    }
-  }
-
   /**
    * 解析下一 Session step 实际使用的运行配置。
    *
@@ -301,19 +227,19 @@ export class Executor implements SessionExecutor {
    * - 调用方必须先提交 Session 统一输入队列，再调用本方法。
    * - 每次调用只读取一次 model、system 与 tools，并把它们传给同一个 `streamText()`。
    */
-  private async resolve_step_inputs(run_context: SessionRunContext): Promise<{
+  private async resolve_step_inputs(turn_context: SessionTurnContext): Promise<{
     model: LanguageModel;
-    system: SessionExecuteInput["system"];
-    tools: SessionExecuteInput["tools"];
+    system: SessionStepExecutionInput["system"];
+    tools: SessionStepExecutionInput["tools"];
     context_window?: number;
   }> {
-    const composed = await this.compose_step(run_context, 0, true);
+    const composed = await this.compose_step(turn_context, 0, true);
     return {
       model: composed.model,
       system: composed.input.system,
-      tools: this.bind_run_context_to_tools(
+      tools: this.bind_turn_context_to_tools(
         composed.input.tools,
-        run_context,
+        turn_context,
       ),
       ...(composed.compose_input.state.model_context_window !== undefined
         ? {
@@ -326,7 +252,7 @@ export class Executor implements SessionExecutor {
 
   /** 读取只读 Session 快照并交给统一 Composer。 */
   private async compose_step(
-    run_context: SessionRunContext,
+    turn_context: SessionTurnContext | undefined,
     retry_count: number,
     refresh_plugins: boolean,
   ): Promise<{
@@ -334,17 +260,17 @@ export class Executor implements SessionExecutor {
     input: SessionStepInput;
     model: LanguageModel;
   }> {
-    if (refresh_plugins) await this.refresh_step_runtime(run_context);
+    if (refresh_plugins && turn_context) await this.refresh_step_runtime(turn_context);
     const compose_input = await this.get_compose_input(
-      run_context,
+      turn_context,
       retry_count,
     );
     const model = compose_input.state.model;
     if (!model) throw new Error("requires a configured model.");
-    run_context.agentEnv = Object.freeze({ ...compose_input.state.env });
-    run_context.agentSystems = Object.freeze([
-      ...compose_input.state.systems,
-    ]);
+    turn_context?.step.commit({
+      workspace_env: compose_input.state.env,
+      agent_systems: compose_input.state.systems,
+    });
     const raw_input = await this.composer.compose(compose_input);
     return {
       compose_input,
@@ -359,26 +285,9 @@ export class Executor implements SessionExecutor {
    * 刷新当前 Session step 的 effective Agent 运行视图。
    */
   private async refresh_step_runtime(
-    run_context: SessionRunContext,
-  ): Promise<void> {
-    await this.release_step_plugins(run_context);
-    if (this.get_plugins) {
-      run_context.agentPlugins = this.get_plugins().acquire();
-    } else {
-      delete run_context.agentPlugins;
-    }
-  }
-
-  /**
-   * 释放当前 Session step 持有的 Plugin execution lease。
-   */
-  private async release_step_plugins(
-    run_context: SessionRunContext,
+    turn_context: SessionTurnContext,
   ): Promise<void> {
-    const plugins = run_context.agentPlugins;
-    if (!plugins) return;
-    delete run_context.agentPlugins;
-    await plugins.release();
+    await turn_context.step.replace_plugins(this.get_plugins?.().acquire());
   }
 
   /**
@@ -388,18 +297,20 @@ export class Executor implements SessionExecutor {
    * - 每个 step 使用独立包装工具，不会在并行 Session 间共享可变指针。
    * - Agent 与 Shell 工具通过 ToolExecutionOptions.experimental_context 读取显式快照。
    */
-  private bind_run_context_to_tools(
+  private bind_turn_context_to_tools(
     tools: Record<string, Tool>,
-    run_context: SessionRunContext,
+    turn_context: SessionTurnContext,
   ): Record<string, Tool> {
     const execution_context: SessionToolExecutionContext = {
-      session_run_context: run_context,
+      session_turn_context: turn_context,
       shell_run_context: {
-        ownerContextId: String(run_context.sessionId || "").trim() || undefined,
-        turnId: String(run_context.turnId || "").trim() || undefined,
-        ...(run_context.agentEnv ? { env: run_context.agentEnv } : {}),
-        ...(run_context.shell_approval_gateway
-          ? { approval_gateway: run_context.shell_approval_gateway }
+        ownerContextId: turn_context.session.session_id,
+        turnId: turn_context.session.turn_id,
+        ...(turn_context.step.workspace_env
+          ? { env: turn_context.step.workspace_env }
+          : {}),
+        ...(turn_context.shell.approval_gateway
+          ? { approval_gateway: turn_context.shell.approval_gateway }
           : {}),
       },
     };
@@ -415,8 +326,8 @@ export class Executor implements SessionExecutor {
         ...tool,
         execute: async (args: unknown, options: ToolExecutionOptions) => {
           const tool_call_id = String(options.toolCallId || "").trim();
-          if (tool_call_id && run_context.on_tool_input_ready) {
-            await run_context.on_tool_input_ready({
+          if (tool_call_id && turn_context.output.assistant) {
+            await turn_context.output.assistant.prepare_tool_input({
               tool_call_id,
               tool_name: name,
               input: args,
@@ -426,60 +337,43 @@ export class Executor implements SessionExecutor {
             ...options,
             experimental_context: execution_context,
           });
-          return inject_read_image_user_message({
-            tool_name: name,
-            output,
-            run_context,
-          });
+          if (!is_action_result(output)) return output;
+          for (const message of output.messages) {
+            if (message.role === "assistant") {
+              turn_context.output.enqueue_assistant_parts(message.parts);
+              continue;
+            }
+            turn_context.input.inject_user_message({
+              id: `u:${turn_context.session.session_id}:${generate_id()}`,
+              role: "user",
+              metadata: {
+                v: 1,
+                ts: Date.now(),
+                session_id: turn_context.session.session_id,
+                turn_id: turn_context.session.turn_id,
+                source: "ingress",
+                kind: "normal",
+                extra: {
+                  internal: "action_result",
+                  tool_name: name,
+                  ...(tool_call_id ? { tool_call_id } : {}),
+                },
+              },
+              parts: [...message.parts],
+            });
+          }
+          return output.output;
         },
       };
     }
     return wrapped;
   }
 
-  /**
-   * 归一化本轮显式运行上下文。
-   */
-  private createRunContext(
-    input?: SessionRunContext,
-  ): SessionRunContext {
-    const source = input || {
-      sessionId: this.sessionId,
-      injectedUserMessages: [],
-      deferredPersistedUserMessages: [],
-      pendingAssistantFileParts: [],
-    };
-    const {
-      sessionId,
-      projectRoot,
-      injectedUserMessages,
-      deferredPersistedUserMessages,
-      pendingAssistantFileParts,
-      ...runtime_context
-    } = source;
-    return {
-      ...runtime_context,
-      sessionId: String(sessionId || this.sessionId).trim(),
-      ...(typeof projectRoot === "string" && projectRoot.trim()
-        ? { projectRoot: projectRoot.trim() }
-        : {}),
-      injectedUserMessages: Array.isArray(injectedUserMessages)
-        ? [...injectedUserMessages]
-        : [],
-      deferredPersistedUserMessages: Array.isArray(deferredPersistedUserMessages)
-        ? [...deferredPersistedUserMessages]
-        : [],
-      pendingAssistantFileParts: Array.isArray(pendingAssistantFileParts)
-        ? [...pendingAssistantFileParts]
-        : [],
-    };
-  }
-
   /**
    * 读取当前 session 模型。
    */
-  private resolveModelOrThrow(): LanguageModel {
-    const model = this.getModel();
+  private resolve_model_or_throw(): LanguageModel {
+    const model = this.get_model();
     if (!model) {
       throw new Error("requires a configured model.");
     }

package/src/executor/README.md

@@ -6,9 +6,10 @@
 
 ## 边界
 
-- `SessionTurn` 拥有输入队列、Turn Handle、取消信号与 Assistant Message 收口。
+- `Session` 拥有输入队列并创建 Command；`SessionLoop` 负责消费、Turn Handle 与 Assistant Message 收口。
+- `SessionTurnContext` 从 Turn 创建起唯一拥有取消信号、Step 快照和执行期资源。
 - `SessionComposer` 根据只读 Session 快照组装 system、messages 和 tools。
-- `Executor` 管理单次模型执行、上下文超限重试和 Step Plugin Lease。
+- `Executor` 管理单次模型执行、上下文超限重试和 Step Plugin Lease；它只对外提供 `execute()`。
 - `CoreEngineRunner` 执行 `streamText()`、Tool Loop、续写和内存上下文折叠。
 - `SessionMessages` 是 Message 唯一事实源；Executor 不写文件、不持有 Store。
 
@@ -16,26 +17,27 @@
 
 ```mermaid
 flowchart LR
-    Turn["SessionTurn"] --> Executor
+    Loop["SessionLoop"] --> Context["SessionTurnContext"]
+    Context --> Executor
     Executor --> Composer["SessionComposer"]
     Composer --> Input["system + messages + tools"]
     Executor --> Engine["CoreEngineRunner"]
     Input --> Engine
     Engine --> Model["LanguageModel"]
     Engine --> Tools["Tools / Plugins"]
-    Engine -->|"Chunk / Callback"| Turn
-    Turn --> Messages["SessionMessages"]
+    Engine -->|"Chunk / Callback"| Context
+    Context --> Messages["SessionMessages"]
 ```
 
-每个模型 Step 前，`SessionTurn` 先消费排队的 Steer 和状态 Command。Executor 随后捕获最新 effective state，并调用 Composer 生成完整 Step 输入。
+每个模型 Step 前，`SessionLoop` 先消费排队的 Steer 和状态 Command。Executor 随后捕获最新 effective state，并调用 Composer 生成完整 Step 输入。
 
 ```text
 Session.prompt()
-  -> SessionTurn 持久化 User Message
+  -> SessionLoop 持久化 User Message
   -> Executor 捕获只读 Session 快照
   -> SessionComposer.compose()
-  -> CoreEngineRunner.run()
-  -> SessionTurn 接收 Stream Chunk
+  -> CoreEngineRunner.execute()
+  -> SessionTurnContext 接收 Stream Chunk
   -> SessionMessages 完成 Assistant Message
 ```
 
@@ -48,9 +50,9 @@ Session.prompt()
 | `SystemComposer` | `DefaultSessionComposer.compose()` + `SessionSystem` |
 | `HistoryComposer` | `SessionMessages.context_snapshot()` + `SessionMessageCodec` |
 | `ContextComposer` 的 tools | `Session.create_compose_input()` + `SessionComposer.compose()` |
-| `ContextComposer` 的 Step Callback | `SessionTurn` + `CoreEngineRunner` |
+| `ContextComposer` 的 Step Callback | `SessionLoop` + `CoreEngineRunner` |
 | `ContextComposer` 的 fallback Assistant | `CoreEngineRunner` + `ExecutorRecoveryPolicy` |
-| `CompactionComposer` | `SessionComposer.compact()` + `should_compact()` |
+| `CompactionComposer` | `SessionComposer.compact()` + `should_compact()`，由 Session 提交计划 |
 
 统一 Composer 只回答两个策略问题：
 

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

@@ -7,7 +7,7 @@
  */
 
 import type { SystemModelMessage } from "ai";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { SessionComposeInput } from "@/types/session/SessionComposer.js";
 
 /**
  * Session system Composer 协议。
@@ -21,5 +21,5 @@ export interface SessionSystemComposer {
   /**
    * 解析本轮 system messages。
    */
-  resolve(run_context: SessionRunContext): Promise<SystemModelMessage[]>;
+  resolve(input: SessionComposeInput): Promise<SystemModelMessage[]>;
 }