@downcity/agent 1.1.437 → 1.1.445

package/src/executor/README.md

@@ -1,92 +0,0 @@
-# Executor Module
-
-`executor/` 是 Session 内部的模型与 Tool Loop 执行内核。普通 SDK 用户只通过 `Session` 调用它。
-
-完整 Session Runtime 设计见 [`docs/session-runtime-architecture.md`](../../../../docs/session-runtime-architecture.md)。
-
-## 边界
-
-- `Session` 拥有输入队列并创建 Command；`SessionLoop` 负责消费、Turn Handle 与 Assistant Message 收口。
-- `SessionTurnContext` 从 Turn 创建起唯一拥有取消信号、Step 快照和执行期资源。
-- `SessionComposer` 根据只读 Session 快照组装 system、messages 和 tools。
-- `Executor` 管理一次 Turn 的输入装配、上下文超限恢复和 Step Plugin Lease；它只对外提供 `execute()`。
-- `ModelRequestRunner` 唯一拥有普通模型请求的五次重试、退避和逐次失败通知。
-- `CoreEngineRunner` 执行 Tool Loop、续写和真实 usage 观测，不自行改写模型历史，也不维护普通请求重试状态。
-- `SessionMessages` 是 Message 唯一事实源；Executor 不写文件、不持有 Store。
-
-## 执行关系
-
-```mermaid
-flowchart LR
-    Loop["SessionLoop"] --> Context["SessionTurnContext"]
-    Context --> Executor
-    Executor --> Composer["SessionComposer"]
-    Composer --> Input["system + messages + tools"]
-    Executor --> Engine["CoreEngineRunner"]
-    Input --> Engine
-    Engine --> Request["ModelRequestRunner"]
-    Request --> Step["ModelStepRunner"]
-    Step --> Model["ModelClient"]
-    Engine --> Tools["Tools / Plugins"]
-    Model -->|"ModelStreamEvent"| Step
-    Step --> Request
-    Engine -->|"ModelStreamEvent / Tool Result"| Context
-    Context --> Messages["SessionMessages"]
-```
-
-每个模型 Step 前，`SessionLoop` 先消费排队的 Steer 和状态 Command。Executor 随后捕获最新 effective state，并调用 Composer 生成完整 Step 输入。
-
-```text
-Session.prompt()
-  -> SessionLoop 持久化 canonical User Message
-  -> Executor 捕获只读 Session 快照
-  -> SessionComposer.compose()
-  -> SessionModelMessages: SessionMessage -> ModelMessage
-  -> CoreEngineRunner.execute()
-  -> Federation / Provider 返回 ModelStreamEvent
-  -> SessionAssistantOutput 直接更新 canonical Assistant Message
-  -> SessionMessages 持久化并发布 Mutation
-```
-
-## 旧 Composer 去向
-
-过去的四个独立 Composer 不再构成执行管线：
-
-| 旧能力 | 当前归属 |
-| --- | --- |
-| `SystemComposer` | `DefaultSessionComposer.compose()` + `SessionSystem` |
-| `HistoryComposer` | `SessionComposer` + `SessionContextPolicy` + `SessionModelMessages` |
-| `ContextComposer` 的 tools | `Session.create_compose_input()` + `SessionComposer.compose()` |
-| `ContextComposer` 的 Step Callback | `SessionLoop` + `CoreEngineRunner` |
-| `ContextComposer` 的 fallback Assistant | `CoreEngineRunner` + `ExecutorRecoveryPolicy` |
-| `CompactionComposer` | `SessionComposer.recover_context()` + Context Policy 派生表 |
-
-统一 Composer 只回答一个策略问题：
-
-1. 当前 Step 的 system、messages 和 tools 是什么？上下文超限时是否能由当前 Policy 推进派生状态？
-
-Queue 消费、Turn 控制、Message 写入和 Mutation 发布都不是 Composer 职责。
-
-## Context recovery
-
-```text
-SessionLoop / CoreEngine
-  -> SessionComposer.recover_context()
-  -> SessionContextPolicy 写入自己的派生表
-  -> Composer 下一次 compose() 读取最新派生上下文
-```
-
-Composer 可以调用模型生成 Summary，但不能修改 canonical Message、Metadata 或发布事件。持久化提交始终由 `SessionStorage` 事务完成。
-
-## 目录
-
-```text
-executor/
-  Executor.ts
-  core-engine/       模型与 Tool Loop
-  composer/system/   可复用的默认 system prompt 领域实现
-  messages/          Session 与 Model Protocol 消息转换
-  services/          执行恢复策略
-  tools/             Tool 运行辅助
-  types/             Executor 内部类型
-```

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

@@ -1,9 +0,0 @@
-/**
- * 自动生成文件，请勿手改。
- * 源文件：由同路径 `*.ts.txt` 生成。
- */
-
-// Source: src/executor/composer/system/default/assets/core.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "# Harness Design\n\nYou are a Downcity 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- For long-running tasks, use `wait_ms` with `shell_session` to wait for output or state changes and avoid frequent polling overhead.\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 a host 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 use the Workspace's persistent isolated Sandbox by default. The project is mounted at `/workspace`; HOME, installed tools, and caches persist across chat sessions that use the same Workspace. Different Workspaces do not share writable Sandbox state.\n- When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.\n- If a task requires host-directory writes or host-level capabilities, invoke the appropriate shell tool directly with `target: \"host\"` 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 a host 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 for host execution.\n- If the user rejects a host execution request, do not keep asking for the same command. Explain the impact and provide a Sandbox alternative when possible.\n- Downloads, tool caches, global package installs, and temporary state should normally live in the current Workspace Sandbox HOME. Do not assume access to the real user's HOME or 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 host access. Use the approved host 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, call `plugin_read({})` to list the plugins actually registered in the current Agent before choosing one. Use `plugin_read({ plugin, action? })` to inspect its action schema and examples.\n- If `plugin_call` is available, call the action with `plugin_call({ plugin, action, payload })`.\n- `plugin_call.plugin` must be a plugin name returned by `plugin_read({})`.\n- `plugin_call.action` must be an action name returned by `plugin_read({ plugin })`.\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 `Global / Env` or the owning Plugin's Mainview. 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/core-engine/CoreEngineLoopDecision.ts

@@ -1,63 +0,0 @@
-/**
- * CoreEngineLoopDecision：模型/tool-loop 核心循环的纯决策模块。
- *
- * 关键点（中文）
- * - 把 “是否继续下一轮” 的分支优先级从 CoreEngine 主流程中拆出。
- * - 保持纯函数，不依赖模型、持久化或 logger，便于直接测试。
- */
-
-import type {
-  SessionLoopDecision,
-  SessionLoopDecisionInput,
-  SessionTailMergeContinuationInput,
-} from "@/executor/types/SessionLoop.js";
-
-/**
- * 评估当前 step 完成后，tool-loop 是否应继续下一轮。
- *
- * 优先级（中文）
- * 1. 不完整响应恢复
- * 2. 已发生的工具调用
- * 3. 停止
- */
-export function evaluate_core_engine_loop_decision(
-  input: SessionLoopDecisionInput,
-): SessionLoopDecision {
-  if (
-    input.hasIncompleteResponse &&
-    input.incompleteRecoveryCount < input.maxIncompleteRecoveries
-  ) {
-    return {
-      kind: "recover_incomplete",
-      continueForToolCalls: false,
-      continueForIncompleteRecovery: true,
-    };
-  }
-
-  if (input.toolCallCount > 0) {
-    return {
-      kind: "continue_for_tool_calls",
-      continueForToolCalls: true,
-      continueForIncompleteRecovery: false,
-    };
-  }
-
-  return {
-    kind: "stop",
-    continueForToolCalls: false,
-    continueForIncompleteRecovery: false,
-  };
-}
-
-/**
- * 评估 stop 前的尾部合并是否应该继续下一轮。
- *
- * 关键点（中文）
- * - 只要最后一次 tail merge 真正并入了新的 user 消息，就必须续跑。
- * - 这样可以覆盖“最后一个 step 结束后，新消息才到达”的收尾窗口。
- */
-export function should_continue_for_tail_merged_user_messages(
-  input: SessionTailMergeContinuationInput,
-): boolean {
-  return input.mergedUserMessageCount > 0;
-}

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

@@ -1,458 +0,0 @@
-/**
- * CoreEngineRunner：模型与 tool-loop 主循环执行器。
- *
- * 关键点（中文）
- * - 每个 Provider Step 都通过回调取得 Composer 生成的完整输入。
- * - 只负责 step 循环、续写恢复与最终 assistant 汇总，不持有历史副本。
- * - 保持失败返回结构稳定，避免对外 Session 行为变化。
- */
-
-import type { RuntimeTool as Tool } from "@downcity/type";
-import { log_assistant_message_now } from "@executor/messages/SessionMessageLog.js";
-import {
-  MAX_INCOMPLETE_RESPONSE_RECOVERIES,
-  MAX_TOOL_LOOP_STEPS,
-  build_incomplete_response_recovery_nudge,
-  detect_incomplete_response,
-  extract_assistant_text,
-  merge_assistant_parts,
-  summarize_assistant_parts_for_debug,
-  summarize_step_for_debug,
-  to_inline_preview,
-} from "@executor/core-engine/CoreEngineSignals.js";
-import {
-  evaluate_core_engine_loop_decision,
-  should_continue_for_tail_merged_user_messages,
-} from "@executor/core-engine/CoreEngineLoopDecision.js";
-import {
-  resolve_effective_core_engine_error,
-} from "@executor/core-engine/CoreEngineError.js";
-import {
-  run_model_step,
-  type ModelStepResult,
-  type ModelStepToolCall,
-} from "@executor/model/ModelStepRunner.js";
-import { execute_model_request } from "@executor/model/ModelRequestRunner.js";
-import {
-  resolve_model_usage_ratio,
-  should_compact_after_usage,
-} from "@executor/core-engine/CoreEngineContextCompaction.js";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
-import type {
-  SessionStepExecutionInput,
-  SessionTurnExecutionResult,
-} from "@/types/session/SessionExecution.js";
-import type { SessionAgentMessagePart } from "@downcity/type";
-import { create_session_agent_content_part } from "@/session/messages/SessionAgentContent.js";
-import { generate_id } from "@/utils/Id.js";
-
-const TURN_STOPPED_MESSAGE = "Turn stopped";
-
-interface CoreEngineRunnerOptions {
-  /** 当前 Session 稳定标识。 */
-  session_id: string;
-
-  /**
-   * 当前 session 统一日志器。
-   */
-  logger: Logger;
-
-  /**
-   * 判断某次执行错误是否应该上抛给外层压缩重试。
-   */
-  should_compact_on_error: (error: unknown) => boolean;
-}
-
-interface CoreEngineTurnInput {
-  /**
-   * 当前显式运行上下文。
-   */
-  turn_context: SessionTurnContext;
-
-  /**
-   * 在统一输入队列提交后解析当前 Session step 的 effective 配置。
-   */
-  resolve_step_input: () => Promise<SessionStepExecutionInput>;
-}
-
-/**
- * 模型与 tool-loop 主循环执行器。
- */
-export class CoreEngineRunner {
-  private readonly session_id: string;
-  private readonly logger: Logger;
-  private readonly should_compact_on_error: CoreEngineRunnerOptions["should_compact_on_error"];
-
-  constructor(options: CoreEngineRunnerOptions) {
-    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");
-    }
-  }
-
-  /**
-   * 执行一次已装配完成的模型/tool-loop 运行。
-   */
-  async execute(input: CoreEngineTurnInput): Promise<SessionTurnExecutionResult> {
-    const start_time = Date.now();
-    const session_id = this.session_id;
-    let last_observed_stream_error: unknown = undefined;
-    let final_assistant_parts: SessionAgentMessagePart[] = [];
-    let compact_required = false;
-
-    try {
-      let step_count = 0;
-      let total_tool_call_count = 0;
-      let total_tool_result_count = 0;
-      const on_step_finish = async (
-        step_result: ModelStepResult,
-      ): Promise<void> => {
-        step_count += 1;
-        const summary = summarize_step_for_debug(step_result);
-        total_tool_call_count +=
-          typeof summary.toolCallCount === "number" ? summary.toolCallCount : 0;
-        total_tool_result_count +=
-          typeof summary.toolResultCount === "number"
-            ? summary.toolResultCount
-            : 0;
-        await this.logger.log("info", "[agent] step.finish", {
-          session_id: session_id,
-          step_index: step_count,
-          ...summary,
-        });
-      };
-
-      let incomplete_response_recovery_count = 0;
-      while (step_count < MAX_TOOL_LOOP_STEPS) {
-        // 关键点（中文）：steer 与 command 在同一个 Session step 检查点执行。
-        // 当前流与 tool callback 保持原执行视图，下一 step 再统一读取 effective 配置。
-        await input.turn_context.input.checkpoint();
-        const step_input = await input.resolve_step_input();
-
-        last_observed_stream_error = undefined;
-        let step_assistant_parts: SessionAgentMessagePart[];
-        let step_result: ModelStepResult;
-        try {
-          const result = await execute_model_request({
-            request_kind: "turn",
-            abort_signal: input.turn_context.lifecycle.abort_signal,
-            should_retry: (error) => !this.should_compact_on_error(error),
-            on_failure: async (notice, error) => {
-              const is_compact_error = this.should_compact_on_error(error);
-              input.turn_context.output.report_model_request_failure({
-                ...notice,
-                ...(is_compact_error
-                  ? {
-                      attempt: 1,
-                      max_attempts: 1,
-                      will_retry: false,
-                    }
-                  : {}),
-              });
-              if (notice.will_retry) {
-                await this.logger.log("warn", "[agent] model_stream.retry", {
-                  session_id,
-                  retry_count: notice.attempt,
-                  error_code: notice.code,
-                  error: notice.message,
-                  provider_request_id: notice.provider_request_id ?? null,
-                });
-              }
-            },
-            execute_attempt: async () => {
-              await input.turn_context.output.assistant?.begin_step();
-              try {
-                return await run_model_step({
-                  model: step_input.model,
-                  system: step_input.system,
-                  messages: step_input.messages,
-                  tools: step_input.tools,
-                  abort_signal: input.turn_context.lifecycle.abort_signal,
-                  ...(input.turn_context.output.assistant
-                    ? { assistant_output: input.turn_context.output.assistant }
-                    : {}),
-                  approve_tool: async (call, tool) => await resolve_tool_approval({
-                    call,
-                    tool,
-                    turn_context: input.turn_context,
-                  }),
-                });
-              } catch (error) {
-                await input.turn_context.output.assistant?.abort_step();
-                throw error;
-              }
-            },
-          });
-          step_assistant_parts = result.assistant_parts;
-          await on_step_finish(result.step_result);
-
-          if (input.turn_context.output.assistant) {
-            await input.turn_context.output.assistant.finish_step(
-              step_assistant_parts,
-            );
-          }
-          const action_assistant_parts =
-            input.turn_context.output.take_assistant_parts();
-          if (action_assistant_parts.length > 0) {
-            const persisted_parts = input.turn_context.output.assistant
-              ? await input.turn_context.output.assistant.append_result_parts(
-                  action_assistant_parts,
-                )
-              : action_assistant_parts.map((part, index) =>
-                  create_session_agent_content_part(
-                    part,
-                    `${part.type}:${generate_id()}`,
-                    index + 1,
-                  )
-                );
-            step_assistant_parts = merge_assistant_parts(
-              step_assistant_parts,
-              persisted_parts,
-            );
-          }
-          final_assistant_parts = merge_assistant_parts(
-            final_assistant_parts,
-            step_assistant_parts,
-          );
-          step_result = result.step_result;
-        } catch (error) {
-          const compact_error = this.should_compact_on_error(error)
-            ? error
-            : last_observed_stream_error;
-          if (this.should_compact_on_error(compact_error)) throw compact_error;
-          throw error;
-        }
-
-        const usage_ratio = resolve_model_usage_ratio(
-          step_result.usage,
-          step_input.context_window,
-        );
-        if (usage_ratio !== null) {
-          const pressure_detected = should_compact_after_usage(usage_ratio);
-          if (pressure_detected) compact_required = true;
-          await this.logger.log("info", "[agent] context.usage", {
-            session_id: session_id,
-            step_index: step_count,
-            usageRatio: usage_ratio,
-            contextWindow: step_input.context_window,
-            compactPending: pressure_detected,
-          });
-        }
-
-        const incomplete_response = detect_incomplete_response({
-          step_result,
-          assistant_parts: step_assistant_parts,
-        });
-        const loop_decision = evaluate_core_engine_loop_decision({
-          hasIncompleteResponse: incomplete_response !== null,
-          incompleteRecoveryCount: incomplete_response_recovery_count,
-          maxIncompleteRecoveries: MAX_INCOMPLETE_RESPONSE_RECOVERIES,
-          toolCallCount: step_result.tool_calls.length,
-        });
-
-        await this.logger.log("info", "[agent] loop.decision", {
-          session_id: session_id,
-          step_index: step_count,
-          continueForToolCalls: loop_decision.continueForToolCalls,
-          continueForIncompleteRecovery:
-            loop_decision.continueForIncompleteRecovery,
-          decisionKind: loop_decision.kind,
-          incompleteResponseReason: incomplete_response?.reason ?? null,
-          incompleteResponseRecoveryCount: incomplete_response_recovery_count,
-          toolCallCount: step_result.tool_calls.length,
-          toolResultCount: step_result.tool_results.length,
-          finishReason: step_result.finish_reason,
-          textPreview: to_inline_preview(step_result.text),
-        });
-
-        if (
-          loop_decision.continueForIncompleteRecovery &&
-          incomplete_response
-        ) {
-          incomplete_response_recovery_count += 1;
-          await this.logger.log("warn", "[agent] incomplete_response.recover", {
-            session_id: session_id,
-            step_index: step_count,
-            recoveryCount: incomplete_response_recovery_count,
-            reason: incomplete_response.reason,
-            ...incomplete_response.details,
-          });
-          await input.turn_context.input.append_internal([{
-              type: "text",
-              text: build_incomplete_response_recovery_nudge(
-                incomplete_response_recovery_count,
-              ),
-            }]);
-          continue;
-        }
-
-        if (incomplete_response) {
-          await this.logger.log("error", "[agent] incomplete_response", {
-            session_id: session_id,
-            step_index: step_count,
-            reason: incomplete_response.reason,
-            recoveryCount: incomplete_response_recovery_count,
-            ...incomplete_response.details,
-          });
-          throw new Error(
-            `Agent received incomplete response (${incomplete_response.reason})`,
-          );
-        }
-
-        if (loop_decision.continueForToolCalls) {
-          incomplete_response_recovery_count = 0;
-          continue;
-        }
-
-        // 关键点（中文）：stop 前做 tail merge，覆盖最后一个 step 后才入队的新 user 消息。
-        const tail_merged_message_count = input.turn_context.input.has_pending()
-          ? 1
-          : 0;
-        if (
-          should_continue_for_tail_merged_user_messages({
-            mergedUserMessageCount: tail_merged_message_count,
-          })
-        ) {
-          incomplete_response_recovery_count = 0;
-          await this.logger.log("info", "[agent] loop.tail_merge_continue", {
-            session_id: session_id,
-            step_index: step_count,
-            mergedUserMessageCount: tail_merged_message_count,
-          });
-          continue;
-        }
-
-        break;
-      }
-
-      if (step_count >= MAX_TOOL_LOOP_STEPS) {
-        await this.logger.log("warn", "[agent] loop.max_steps_reached", {
-          session_id: session_id,
-          stepCount: step_count,
-          totalToolCallCount: total_tool_call_count,
-          totalToolResultCount: total_tool_result_count,
-        });
-      }
-
-      const final_parts = final_assistant_parts.length > 0
-        ? final_assistant_parts
-        : build_fallback_assistant_parts("Execution completed");
-
-      await this.logger.log("info", "[agent] final.message", {
-        session_id: session_id,
-        ...summarize_assistant_parts_for_debug(final_parts),
-      });
-      await log_assistant_message_now(this.logger, final_parts);
-
-      const duration = Date.now() - start_time;
-      await this.logger.log("info", "[agent] finish", {
-        session_id: session_id,
-        duration,
-        stepCount: step_count,
-        totalToolCallCount: total_tool_call_count,
-        totalToolResultCount: total_tool_result_count,
-      });
-
-      return {
-        success: true,
-        text: extract_assistant_text(final_parts),
-        ...(compact_required ? { compact_required: true } : {}),
-      };
-    } catch (error) {
-      if (input.turn_context.lifecycle.abort_signal.aborted) {
-        const error_text = TURN_STOPPED_MESSAGE;
-        await this.logger.log("info", "[agent] stopped", {
-          session_id: session_id,
-        });
-        return {
-          success: false,
-          text: extract_assistant_text(final_assistant_parts),
-          error: error_text,
-          ...(compact_required ? { compact_required: true } : {}),
-        };
-      }
-
-      if (this.should_compact_on_error(error)) {
-        throw error;
-      }
-
-      const error_text = resolve_effective_core_engine_error({
-        error,
-        streamError: last_observed_stream_error,
-      });
-
-      await this.logger.log("error", "CoreEngine execution failed", {
-        error: error_text,
-      });
-
-      return {
-        success: false,
-        text: extract_assistant_text(final_assistant_parts),
-        error: error_text,
-        ...(compact_required ? { compact_required: true } : {}),
-      };
-    }
-  }
-}
-
-/** 在工具执行前接入 Session canonical Interaction 生命周期。 */
-async function resolve_tool_approval(input: {
-  call: ModelStepToolCall;
-  tool: Tool;
-  turn_context: SessionTurnContext;
-}): Promise<boolean> {
-  const needs_approval = input.tool.needs_approval;
-  const required = typeof needs_approval === "function"
-      ? await needs_approval(input.call.input as never, {
-        tool_call_id: input.call.tool_call_id,
-        messages: [],
-      })
-    : needs_approval === true;
-  if (!required) return true;
-  const interactions = input.turn_context.interactions;
-  if (!interactions) {
-    throw new Error("Tool approval requires a Session Interaction port");
-  }
-  const approval_id = `approval:${input.call.tool_call_id}`;
-  const handle = await interactions.request({
-    interaction_id: `interaction:tool-approval:${approval_id}`,
-    turn_id: input.turn_context.session.turn_id,
-    type: "approval",
-    source: {
-      type: "tool",
-      tool_call_id: input.call.tool_call_id,
-      tool_name: input.call.tool_name,
-    },
-    payload: {
-      operation: "tool",
-      validated_input: to_session_json_value(input.call.input),
-      ...(input.tool.description ? { tool_description: input.tool.description } : {}),
-    },
-    created_at: Date.now(),
-  });
-  const result = await handle.result;
-  const payload = result.status === "resolved" && result.response.type === "approval"
-    ? result.response.payload as { decision?: unknown }
-    : undefined;
-  return result.status === "resolved" &&
-    result.response.type === "approval" &&
-    result.response.outcome === "resolved" &&
-    payload?.decision === "approved";
-}
-
-/** 构造成功执行但缺少最终内容时使用的 canonical Assistant Parts。 */
-function build_fallback_assistant_parts(
-  text: string,
-): SessionAgentMessagePart[] {
-  return [{
-    part_id: "fallback-text:1",
-    sequence: 1,
-    type: "text",
-    text,
-    state: "done",
-  }];
-}