knowledge-agent-execution-and-orchestration-decision-loop-and-completion

## Module Structure 该节点描述一次 Agent run 如何在 Provider 回合、工具副作用、持久化和多重完成条件之间推进，并保证崩溃恢复后不会把未提交状态当成成功。 ### Directory Layout - `packages/cli/src/agent/Agent.ts` — 无状态入口、运行模式切换和 SessionRuntime 适配 - `packages/cli/src/agent/ExecutionEngine.ts` — ContextManager 容器与简单单轮执行兼容入口 - `packages/cli/src/agent/ExecutionSummary.ts` — 运行统计摘要 - `packages/cli/src/agent/loop/` — 主循环、会话状态、工具流、完成策略和恢复检测 - `executeLoopGenerator.ts` — 核心状态机 - `StreamingToolExecutor.ts` — 流式预启动、排队、顺序收集和 epoch 丢弃 - `completionPolicy.ts` — 显式委派、worktree、验证和停止策略 - `conversationPersistence.ts` — 消息、工具调用、工具结果和压缩的 durable commit - `independentVerification.ts` — 非平凡实现的独立验证门禁 - `goalCompletionVerification.ts` — Goal 完成候选门禁 - `actionStationarity.ts` — 重复工具动作的进展感知检测 - `packages/cli/src/prompts/` — 默认提示、Plan 提示、项目指令和 Provider 边界附加内容 - `packages/cli/src/services/StructuredOutputService.ts` — JSON Schema 终态契约与恢复 ### Key Entry Points - `Agent.chatStream()` in `packages/cli/src/agent/Agent.ts` — 统一事件流入口并处理 durable input、follow-up 与 Goal continuation - `executeLoopGenerator()` in `packages/cli/src/agent/loop/executeLoopGenerator.ts` — 完整 agentic loop - `StreamingToolExecutor.addTool()` in `packages/cli/src/agent/loop/StreamingToolExecutor.ts` — 决定流内预启动、排队或拒绝 - `checkIndependentVerificationGate()` in `packages/cli/src/agent/loop/independentVerification.ts` — 主 Agent 独立验证准出 - `createStructuredOutputContract()` in `packages/cli/src/services/StructuredOutputService.ts` — 结构化终态校验入口 ## Gotchas - `stream_end` 是每个 Provider turn 的终止信号，一个完整 run 内可能出现多次；消费者不能把第一次 `stream_end` 当成 Agent 已完成 (`packages/cli/src/agent/loop/types.ts`) - 流式预启动同时要求工具在固定只读 allowlist、声明 `isConcurrencySafe` 且前面没有 exclusive barrier；仅把工具标成并发安全不会让它在 Provider 流提交前启动 (`packages/cli/src/agent/loop/StreamingToolExecutor.ts`) - 工具副作用前必须先按模型调用顺序提交 durable `tool_call`；required commit 失败时工具根本不启动，不能把返回的失败结果解释为“可能已执行” (`packages/cli/src/agent/loop/StreamingToolExecutor.ts`, `packages/cli/src/agent/loop/conversationPersistence.ts`) - 工具执行完成后仍要先提交 durable `tool_result` 才能发布给界面或下一次 Provider 请求；该提交失败时副作用可能已发生，loop 以 `tool_persistence_failed` 停止并要求恢复阶段处理不确定性 (`packages/cli/src/agent/loop/executeLoopGenerator.ts`, `packages/cli/src/agent/loop/conversationPersistence.ts`, `git:b98a073e`) - 成功的显式验证证据会在后续 Edit、Write、ApplyPatch 或 NotebookEdit 成功时清空；独立验证的 mutation revision 也同步失效，PASS 不能跨源码修改复用 (`packages/cli/src/agent/loop/completionPolicy.ts`, `packages/cli/src/agent/loop/independentVerification.ts`) - 非平凡实现门禁只在主 Agent 修改至少 3 个实现文件、触及高风险路径或执行潜在写 Bash 时触发；子代理、禁止委派、exactly-once Task 契约或不可用 Task 工具会跳过这一门禁 (`packages/cli/src/agent/loop/independentVerification.ts`) - 用户明确要求的 test、lint、type-check、build 是另一道完成门禁；它按请求中的具体类别匹配成功 Bash 命令，运行了任意一种检查并不自动满足全部要求 (`packages/cli/src/agent/loop/completionPolicy.ts`) - 合法结构化终态只能通过保留的 `StructuredOutput` 工具提交，JSON prose 不算完成；新 steering 或后续 workspace mutation 会清除已接受对象并重置纠正预算 (`packages/cli/src/agent/loop/executeLoopGenerator.ts`, `packages/cli/src/services/StructuredOutputService.ts`) - `StructuredOutput` 恢复同时校验 schema digest 和对象内容；恢复扫描遇到更新的 user message 会停止，旧 schema 或旧输入下的结果不会被误复用 (`packages/cli/src/services/StructuredOutputService.ts`) - Stop hook 超时或抛错采用保守的“允许停止”结果，而不是无限阻塞完成；只有明确返回 `shouldStop: false` 才注入继续提示并使 Goal 验证失效 (`packages/cli/src/agent/loop/completionPolicy.ts`, `packages/cli/src/agent/loop/executeLoopGenerator.ts`) - Plan 批准后会先持久化 Session permission mode，再把批准内容包进用户消息并重新进入普通 loop；Plan run 的成功结果本身不是任务执行完成 (`packages/cli/src/agent/Agent.ts`) - 默认 Agent 已取消固定 100 回合上限，`-1` 表示无限；防止无界循环依靠输出重复、动作停滞、预算与完成门禁，而不是隐含 turn ceiling (`packages/cli/src/agent/loop/executeLoopGenerator.ts`, `git:85643629`) ## Architecture - `ConversationState` 把根系统提示、可压缩 history 和当前 pending 分开；压缩只替换 history，所有退出路径通过 `writeback()` 提交 pending，避免过去的双消息源漂移 (`packages/cli/src/agent/loop/ConversationState.ts`) - 无工具候选不会直接返回：loop 依次处理 steering、结构化输出、不完整意图、委派/worktree 契约、独立验证、显式验证、Stop hook 和 Goal 验证，调整顺序会改变哪些证据可被后续输入失效 (`packages/cli/src/agent/loop/executeLoopGenerator.ts`) - 流式工具结果虽然按安全条件并行启动，但 `getRemainingResults()` 始终按 Provider tool-call 顺序收集；durable tool-use 写入也由单独 promise tail 串行化 (`packages/cli/src/agent/loop/StreamingToolExecutor.ts`) - `Agent.chatStream()` 在 Session 模式下把一次 run 包在活动操作、顶层任务准入和 durable turn handle 中，并可连续消费 pending follow-up 或 Goal continuation；无 `ChatContext` 的兼容路径只做简单单轮调用 (`packages/cli/src/agent/Agent.ts`) - Loop 的内容增量是临时展示，成功终态以 durable assistant message 和 turn finalization 为准；结构化输出事件、Goal finalize 与成功返回都发生在最终消息提交之后 (`packages/cli/src/agent/loop/executeLoopGenerator.ts`, `packages/cli/src/agent/loop/conversationPersistence.ts`) ## Decisions - 工具执行从多 stage pipeline 迁移为 flat executor 后，loop 只保留流式调度和领域副作用，权限、Hook、验证与锁由统一 ToolExecutor 负责；新逻辑不应恢复已删除的旧 stage 抽象 (`packages/cli/src/agent/loop/StreamingToolExecutor.ts`, `packages/cli/src/agent/Agent.ts`, `git:e6a1bef4`) - 独立验证要求 fresh、内置、前台且由宿主严格解析的 verifier verdict，目的是隔离主模型自证和陈旧 PASS；门禁在写操作后按 revision 重新建立 (`packages/cli/src/agent/loop/independentVerification.ts`, `packages/cli/src/agent/subagents/builtinVerificationAgent.ts`, `git:dfa8904c`) - 系统提示的稳定部分不含 Git 快照和目录列表，并在每个 Provider 边界追加当前 deferred tool 目录，兼顾 Prompt Cache 稳定性与 ToolSearch 后动态 schema 可见性 (`packages/cli/src/agent/loop/providerSystemPrompt.ts`, `packages/cli/src/agent/Agent.ts`, `git:25d5a7d3`) - `replaceDefault` 只替换基础提示，不能绕过 communication style、受信项目规则、Auto Memory、环境或 append；项目指令还受 Workspace Trust 控制 (`packages/cli/src/prompts/builder.ts`, `packages/cli/src/prompts/projectInstructions.ts`) ## Patterns - 完成策略函数返回 action descriptor 而不直接执行副作用；loop 负责持久化 assistant/control 消息后再 retry 或 fail，从而让恢复看到相同控制边界 (`packages/cli/src/agent/loop/completionPolicy.ts`, `packages/cli/src/agent/loop/conversationPersistence.ts`) - 普通文本重复与工具动作停滞使用两套检测器：相同文本连续 3 次触发换策略提示，动作签名连续 8 次提示、16 次终止；`TaskOutput` 的结果进展可打断动作计数 (`packages/cli/src/agent/loop/errorRecovery.ts`, `packages/cli/src/agent/loop/actionStationarity.ts`) - 完成条件依赖的工具成功、验证命令、修改文件和 verifier verdict 都从结构化 ToolResult metadata 累积，不从模型自然语言声明推断 (`packages/cli/src/agent/loop/completionPolicy.ts`, `packages/cli/src/agent/loop/independentVerification.ts`, `packages/cli/src/agent/loop/toolDomainPolicy.ts`) ## Error Handling & Recovery - 输出因 token 长度截断时最多恢复 3 次；若预算判定停止或次数耗尽，只有已提交的有效结构化输出可以继续通过完成门禁，否则返回截断失败 (`packages/cli/src/agent/loop/completionPolicy.ts`, `packages/cli/src/agent/loop/executeLoopGenerator.ts`) - 不完整意图检测只看末尾 200 字符并排除未闭合代码块，代码块且无工具调用也会触发；最多纠正 2 次，避免自然语言模式形成无限重试 (`packages/cli/src/agent/loop/completionPolicy.ts`) - 工具错误恢复按工具名累计连续失败，3 次后提示改换策略；每 5 回合的自检和 3 次相同模型输出检测是独立机制，不能共享或重置彼此计数 (`packages/cli/src/agent/loop/errorRecovery.ts`) - Provider fallback 时 `discard()` 会递增 executor epoch 并取消所有活动工具；迟到的旧世代结果即使正常返回也会转换为 abort 结果，不能泄漏进新模型回合 (`packages/cli/src/agent/loop/StreamingToolExecutor.ts`)