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)