把 Agent Loop 写成可验证的状态迁移

#你将得到什么

第 04 章的 ScriptedModel 能稳定产生模型消息，第 06 章的 executor 能把一次 tool call 变成配对的 ToolResultMessage。现在还缺一个控制器，把这两个能力接起来：

模型提出动作
    → 执行工具
    → 把结果加入消息列表
    → 再次调用模型

这个控制器就是 Agent Loop。本章只修改：

packages/pi-course/src/agent-loop.ts

练习时运行：

npm run practice -w @pi/course -- 07 <新目录>

练习目录会保留第 06 章的源码，注入第 07 章测试，并放入一份只用于学习的代码骨架。 骨架已经声明 LoopEvent、AgentRunResult、AgentLoopOptions 和 runAgentLoop() 的公共表面。五段状态迁移中的分支算法仍留给你完成。

需要重来时，请创建另一个练习目录。隔离目录没有 Git 历史，不要修改注入测试，也 不要运行恢复 commit 的命令。

本章要守住三个不变量：

1. 每轮模型流最终产生的 AssistantMessage 只加入消息列表一次；
2. 下一次模型请求发出前，每个 tool call 都恰好有一条同 id 的 tool result；
3. 一次运行只发出一个 turn_end。

transcript 在本章指本次运行内部维护的消息列表。模型请求、最终返回值和后续重放 都以这份列表为准。

#先建立全景

#把循环写成决策表

不要先写 while。先列出模型消息可能带来的状态迁移：

stop 中出现 tool call 属于协议矛盾，调用不得执行。toolUse 却没有任何 call 也 无法继续，loop 要以 error 结束。明确这两行之后，代码就不需要猜模型“可能想 表达什么”。

循环里还有三种顺序：

两个工具可以并发执行。fast 可以先发出 tool_end，但结果仍要按 assistant 中 slow, fast 的顺序写入消息列表。call id 标识结果回答哪次调用；数组位置规定消息 发送顺序；实际完成先后只决定事件何时出现。

#第一步：完成一次纯文本 stop

一次模型请求包含三部分：

{
  systemPrompt: options.context.systemPrompt,
  messages,
  tools: options.tools.definitions(),
}

messages 不能直接指向调用者的数组。运行开始时先克隆 options.context.messages，之后只修改这份局部副本。systemPrompt 和 tool definitions 也要传给模型；即使当前脚本不调用工具，模型也应看到本次运行 允许的完整动作空间。

模型返回的是 EventStream。loop 先转发流中的 model_event，再通过 stream.result() 取得唯一的最终 AssistantMessage：

model.stream()
    → for await (model events)
    → stream.result()
    → messages.push(assistant)
    → emit assistant_message

最终消息为 stop 且没有 call 时，发出 turn_end(stop) 并返回。不要把流式中间 片段写入消息列表；它们只是过程事件，最终 assistant 才是可以重放的事实。

npm run build -w @pi/course
node --test --test-name-pattern="纯文本 stop" \
  packages/pi-course/dist/test/07-*.test.js

#第二步：把一个工具结果送回模型

先从最终 assistant 中取出 ToolCall：

const calls = assistant.content.filter(
  (block): block is ToolCall => block.type === "toolCall",
);

只有 stopReason === "toolUse" 且 calls.length > 0 时才进入执行阶段。单个调用 按下面的顺序处理：

emit tool_start
    → executor(call, { signal, reportProgress })
    → emit tool_end
    → messages.push(result)
    → 下一轮 model request

reportProgress 要转成带 call id 的 tool_progress，这样 UI 才知道进度属于哪个 动作。signal 也要原样交给 executor。第 06 章已经保证内置 executor 的正常返回值 会保留 call id、name 和错误状态；本章负责把这条结果放回正确的位置。

第二次模型请求应该看到完整的三段因果链：

user
assistant(toolCall id=call-1)
toolResult(toolCallId=call-1)

npm run build -w @pi/course
node --test --test-name-pattern="单工具往返" \
  packages/pi-course/dist/test/07-*.test.js

#第三步：给不会执行的调用也配对

模型消息已经成为 transcript 中的事实，所以不能简单丢弃其中的 call。即使安全规则 禁止执行，也要给每个 call 写入一条错误结果。可以用一个 skippedCall() 统一创建：

{
  "role": "toolResult",
  "toolCallId": "cut",
  "toolName": "echo",
  "content": [{
    "type": "text",
    "text": "Tool call was not executed because the model response was truncated."
  }],
  "details": {"skipped": true, "reason": "length"},
  "isError": true
}

length 最需要这条防线。被截断的 arguments 可能碰巧仍是合法 JSON，也可能通过 schema；一旦执行 write、edit 或 bash，就会改变文件或启动进程。因此，length 中的所有调用都不得执行。

error 和 aborted 中的 call 同样不得执行。stop + calls 是协议矛盾：为调用 生成 unexpected-stop 错误结果，再以 error 结束。toolUse + no calls 没有 需要配对的调用，直接以 error 结束。

每条终态分支都要发一次 turn_end。不要在终态分支里发一次，又在函数末尾补发 第二次。

npm run build -w @pi/course
node --test --test-name-pattern="非执行终态" \
  packages/pi-course/dist/test/07-*.test.js

#第四步：同时执行，按调用顺序写回

一批 calls 可以同时启动。Promise.all() 的返回数组会保留输入 Promise 的顺序， 即使它们完成的先后不同：

调用声明顺序：slow → fast
完成事件顺序：fast → slow
消息写入顺序：result(slow) → result(fast)

每个工具 Promise 完成时立即发出 tool_end；等整批结束后，再按 Promise.all() 的结果顺序追加消息。测试使用可控 Promise gate，先手动放行 fast，再放行 slow。 这样顺序来自明确动作，不依赖 25ms 和 1ms 的定时碰运气。

注入的 executor 还可能 reject。若直接把这些 Promise 交给 Promise.all()，一个 rejection 会让 loop 提前退出，其他工具虽然还在运行，却没有机会写入结果。每个调用 都要单独捕获 rejection，把它转换成同 id/name 的错误 ToolResultMessage。等所有 调用都有结果后，再进入下一轮。

这里不把 stack 写进结果。错误消息仍可能包含调用方自己写入的敏感文本，通用脱敏 不属于本章。

npm run build -w @pi/course
node --test --test-name-pattern="并发工具" \
  packages/pi-course/dist/test/07-*.test.js

#第五步：让控制器有明确边界

loop 在两个位置检查外部 signal：

1. 发起模型请求前；
2. 一批工具完成、结果已经写入 messages 后。

运行开始前 signal 已 aborted 时，不调用模型，返回 steps: 0。若工具执行期间 发生 abort，已经提交的执行最终返回后，loop 会先保留它们的配对结果，再以 aborted 结束，不再请求模型。

maxSteps 限制模型回合数。每次循环最多消费一次模型请求。最后一个允许的 toolUse 回合仍要写完工具结果，然后以 maxSteps 结束；不要伪造一条模型从未 生成的 stop 消息。

这两个边界都不能提供墙钟超时。provider 或工具若忽略 signal，loop 仍可能一直 等待。强制终止进程、清理外部资源和超时策略属于更外层的运行时责任。

npm run build -w @pi/course
node --test --test-name-pattern="取消与上限" \
  packages/pi-course/dist/test/07-*.test.js
node --test packages/pi-course/dist/test/07-*.test.js

#故意把它弄坏

临时把 length 分支改成普通 toolUse 执行路径。测试里的 fake 工具只增加计数， 不会写真实文件：

正确：length + calls → executionCount 0 → skipped results
错误：length + calls → executionCount 2 → 两个副作用都已经开始

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/07-*.test.js

#可选迁移练习

额外挑战：让模型在同一条 assistant 中重复使用 call id。先决定由消息验证层拒绝， 还是由 loop 生成错误结果；无论选择哪一层，都要写测试固定责任边界，不要执行两次。

#小结

Agent Loop 每轮只做三件事：取得最终 AssistantMessage，根据 stopReason 决定 执行工具还是结束，再把结果按 call 顺序加入消息列表。length 会阻止任何工具 执行；executor rejection 会变成配对结果；工具完成事件可以乱序，消息写入顺序必须 稳定。

第 08 章会实现 read、write、edit 和 bash。动作内容会改变，这条反馈回路不需要 重写。