Turn Observation

createTurnObservation() 内部不是一个事件函数，而是一组事实采集器

Symbol	观察对象	Runtime fact
turnStarted()	Turn	start timestamp/event
toolStarted()	Tool	pending + current tool
toolCompleted()	Tool	done / failed
recordToolActivity()	Tool history	recent activity + observed count
beginMcpExecObservation()	MCP execution	stall / error / duration diagnostic
observeAwaitToolCall()	await	completed / timeout / cancelled
flushPendingAwaitsOnUnwind()	cancellation/unwind	给尚未结束的 await 补终态
listAsyncTasks()	subagent / shell / cloud-agent	当前后台工作快照
emitAsyncTasksChanged()	background state	owner + task list event
armDispatchObservation()	model dispatch	dispatch latency / TTFT / resolved model

Tool 生命周期

toolStarted(name)
  ├─ lastTool = name
  ├─ activity = pending
  └─ emit tool-started

executor...

toolCompleted(name, failed)
  ├─ clear lastTool
  ├─ activity = done | failed
  └─ emit tool-completed

Await / Cancellation

observeAwaitToolCall() 会给 await 建立 pending record；完成时根据 cancel / timeout / result 生成 outcome。flushPendingAwaitsOnUnwind() 则处理控制流提前退出时仍悬空的 await。这就是为什么 Observation 不是简单的“工具返回值”。

Background work

listAsyncTasks() 将 subagent、后台 shell、host restart 后重新 attach 的 shell、cloud-agent 统一投影成可观察 task list。它体现的是 execution fact normalization。

本地定位

rg -n "turnStarted|toolStarted|toolCompleted|recordToolActivity|beginMcpExecObservation|observeAwaitToolCall|flushPendingAwaitsOnUnwind|listAsyncTasks|armDispatchObservation" source/host/runner/turn-observation.ts

固定源码

• turn-observation.ts

关联知识文章

• 长 Run 什么时候必须停：Long-running Execution 与 Termination — Observation owner 会枚举 subagent / shell / cloud-agent 后台任务；listAsyncTasks() → emitAsyncTasksChanged()
• 一次 Run 如何被推进：Lifecycle、State Machine 与 Node Transition — Tool 生命周期先变成 Runtime Fact；createTurnObservation() → turnStarted() → toolStarted() → toolCompleted()
• 运行中的并发怎么收住：Concurrency Limit、Cancellation 与 Deadline — Await/Tool Observation 必须感知 cancel/interruption；observeAwaitToolCall() → flushPendingAwaitsOnUnwind()
• 跨进程继续代码任务：Sandbox Session、Snapshot 与 Resume — Restart 后后台 Shell 可以作为 reattached task 被重新观察；listAsyncTasks() → shellRewatchEntries()
• 如何看见 Agent 在做什么：Logs、Metrics 与 Trace — Turn Observation 同时产出生命周期事件和性能事件；createTurnObservation() → armDispatchObservation() → observeFirstToken()
• Graph 怎样被调度并持久化：Scheduler、State Machine 与 StateStore — Observation 是 StateMachine 的输入事实之一；turnStarted() → toolStarted() → toolCompleted()
• 一次 Run 的时间预算怎么传下去：Timeout、Deadline 与 Retry 分类 — MCP stall 使用独立 expiry policy 做诊断；beginMcpExecObservation() → MCP_EXEC_STALL_THRESHOLD_MS
• MCP 进入生产环境后的边界：Tracing、Migration 与 Security — Tool Call 使用稳定 ID 承接跨层诊断；beginMcpExecObservation()
• 一次 Tool 批次如何安全执行：Parallel Call、Error 与 Timeout — Stall Observation 不等于 Retry Decision；beginMcpExecObservation()