Agent 生命周期与执行循环

基本单位

step：一次模型请求 + 它请求执行的全部工具。
turn：零或多个 step；在认领第一条输入前打开（turn/start），在”不再欠任何工作”时关闭（turn/end）。
round：包含一个 turn 的外层策略迭代（goal round、Ralph attempt），计数器属于该策略。
铁律：Model-visible means logged——一切对模型可见的内容必须可从 session log 重建（见 session-model）。

创建与所有权

消费者通过 ctx.agents（AgentRegistry）创建：create()（新 session+agent 共用 caller 指定 SessionId）或 resume()，返回 AgentHandle { agent, dispose() }——disposer 是 capability，只有持有者能拆除。
具体驱动由 ctx.agentLoop（唯一实现公共 Agent 契约的默认 loop）经 ctx.agents.setFactory() 注册；消费者不直接依赖 agent-loop，loop 可替换。
setup 回调在两个 id 发布前组装 agent 的 scoped world；拒绝/抛错/拆除都回滚事务。
每个 driver 运行在 ctx.agents.withInitiator() 内（进程内 initiating Agent 归因，仅归因非授权）。
AgentStatus 只有 'idle' | 'running'，每次翻转发 agent/status；running 描述整个 driver 排空区间，可跨连续排队 turn。disposal 发 agent/disposed，不是第三种状态。

输入路径：Inbox

Agent.send(message, target, wakeup) 统一入口；三个固定预设别名：

别名	语义
`followup`	普通后续 turn：唤醒 driver，成为自己 turn 的唯一普通消息
`steer`	最近 step 的转向输入：idle 时启动 turn，running 时在下一个 step 边界消费
`inject`	面向模型的上下文（不唤醒 driver），等下一次 pre-step 认领

Inbox 是两个有序待处理列表（InboxTarget = 'next-turn' | 'next-step'），是 durable projection；变更记 agent/inbox/spliced。claim(target) 取走拟议 step 的批次：全部 next-step 输入 +（turn 边界时）一条 next-turn 消息。

取消：cancel(cause, { keepInbox })，cause = user | parent | hook | disposed。whenIdle() 等待整 agent 静默；runMaintenance(task) 在真 idle 相位跑非 turn 维护任务（手动 compaction 即用此）。

单 turn 执行序列

turn/start
  claim next-step 输入 + 一条排队消息
  组装 prompt sections + tool schemas
  → agent/pre-step (waterfall)      reject | enter(messages)
     reject/空 enter → 不花 step 直接关 turn（仍关闭 durable turn）
     step/start
     进入的消息逐条 append 为 user/message
     从 log 派生模型历史 (deriveMessages)
     agent/request (waterfall) → llm/stream (waterfall)
       → assistant/chunk* → assistant/message
     tool/call* → tools/pre-execute → tools/execute(并发) → tools/post-execute → tool/result*
     step/end
     工具欠下一次请求、或 next-step 输入到达 → claim → 下一个 step
  → agent/turn-stopping (serial)
turn/end

关键挂点：

agent/pre-step：请求派生前唯一的串行 waterfall；payload 带认领批次、坐标 (turn, step)、turn 的 AbortSignal；返回 PreStepDecision = reject | enter(messages)，决定是权威的。13 个 listener：compaction-basic（pressure）、plan-mode、time-context、tmux-context、agent-instructions、subagent-in-process-driver、hooks-claude-code/codex 等。
agent/request（waterfall）：替换冻结的 LlmCallConfig，不能改消息。
agent/request-error（waterfall）：失败 step 关闭后、turn 关闭前运行；listener 可返回 {kind:'retry'} 接管恢复（llm-retry、compaction-basic）。
agent/turn-stopping（serial，无 next()）：turn 即将关闭的终端检查点；反对者可 agent.steer() 续命，机器重读 inbox，“data decides”。工具结果带 concludesTurn 可在该 step 结束 turn。
工具执行按 executionMode 分类，barrier + bounded rolling pool：pre 有序、execute 并发、post 有序（见 tool-system）。

事件三域

Session events：durable，经 session/event 广播——最大扇出事件（persistence、projection、telemetry、title、token-meter、compaction、goal、workflow、user-approval 约 22 个包监听）。
Agent events（agent/*）：携带活 Agent 的协调 API（队列/状态/拦截/请求构造/steering/续行/错误）。
Capability events（fs/*、tools/*、telemetry/*）：挂在 seam 上，不 import loop 即可挂策略/adapter。

另有 internal/dispatch 内部总线（commands、compaction、goal、plan-mode、schedule、session-title、subagent 等内部路由）。

Context 扩展包（packages/context）

不加工具、只给模型请求追加可见上下文：

agent-instructions（默认含，可关）：per-session 加载 AGENTS.md 兼容文件（$DSH_HOME/AGENTS.md → 项目根到 header.cwd 的目录链）；观察 tools/result（read/write/edit）后在 inbox 排队文件增删改通知。
time-context（opt-in）：当前分区时间 + 时区 + 经过时间，refreshIntervalMs 节流。
tmux-context（opt-in）：每 turn 首 step 采样 tmux session/window/pane 布局。
session-reference：跨会话引用解析——按 cwd 亲和度列候选，把被引用会话 surface 快照聚合成一条 untrusted additionalContext（带预算/自引用限制，错误码 SESSION_REFERENCE_*）。

Wiki AI

目录