Agent Turn And Step Lifecycle

This sequence is the visual companion to architecture.md. It keeps durable replay facts on session/event and live control/status on agent/*.

sequenceDiagram participant User participant Agent participant Driver participant Hooks as hook listeners participant Prompt as ctx.systemPrompt participant LLM as ctx.llm participant Tools as ctx.tools participant Session participant SDK as UI or SDK listener User->>Agent: followup(content) Agent-->>SDK: <code>agent/inbox/spliced</code> Agent-->>SDK: <code>agent/inbox/inserted</code> { message } Agent->>Driver: queued work wakes driver Driver-->>SDK: <code>agent/status</code> running Driver->>Session: <code>turn/start</code> Note over Agent,Driver: claim pending next-step input plus one queued prompt Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message Driver->>Hooks: <code>agent/pre-step</code> waterfall Hooks-->>Driver: authoritative reject or enter(messages) alt proposed step rejected or pre-step failed Driver-->>Driver: claimed batch stays removed, the open turn spends no step else enter proposed step Driver->>Session: <code>step/start</code> Driver->>Session: <code>user/message</code> per entered message Driver->>Prompt: <code>system-prompt/assemble</code> waterfall Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall LLM-->>Driver: StreamChunk* Driver->>Session: <code>assistant/chunk</code>* Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>* alt final adapter or terminal in-band request failure Driver->>Session: <code>step/end</code> Driver->>Hooks: <code>agent/request-error</code> waterfall Hooks-->>Driver: return retry action or preserve the original error else model request succeeded Driver->>Session: <code>assistant/message</code> Driver->>Tools: classify pending call by executionMode loop barriers and bounded rolling pool, reclassify before start opt call starts Driver->>Session: <code>tool/call</code> Driver->>Tools: ordered pre, concurrent execute Tools-->>Session: tool-owned events when applicable end opt next model-order result ready Driver->>Tools: ordered post Driver->>Session: <code>tool/result</code> end end Driver->>Session: <code>step/end</code> opt natural stop and next-step inbox empty Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint end opt next-step input is pending Driver-->>Driver: claim pending next-step input Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message Driver->>Hooks: <code>agent/pre-step</code> waterfall Hooks-->>Driver: authoritative reject or enter(messages) end end end Driver->>Session: <code>turn/end</code> Driver-->>SDK: <code>agent/status</code> idle

The assistant/message event records every successful provider call, including content-less and max-tokens finishes. Empty content stays out of derived history, while the durable event keeps usage and sourceEventSeqs listing the exact assistant/chunk events, including an explicit empty list.

dsh-compaction-basic uses agent/pre-step for pressure before request derivation and agent/request-error only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.

The returned agent/pre-step decision is authoritative; listeners wrapping next() preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.

SDK users that need replayable transcript data should consume session/event; agent/* is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.

Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

Agent 轮次与步骤生命周期

此时序图是 architecture.md 的配套图示。持久的回放事实保存在 session/event 中，实时控制与状态则保存在 agent/* 中。

assistant/message 事件会记录每次成功的提供方调用，包括返回空内容或以 max-tokens 结束的调用。空内容不会进入派生历史，但该持久事件仍会保留用量，并通过 sourceEventSeqs 精确列出对应的 assistant/chunk 事件，包括显式空列表。

dsh-compaction-basic 在派生请求之前通过 agent/pre-step 处理压力，而 agent/request-error 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。

以返回的 agent/pre-step 决策为准；通过包装 next() 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。

需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 session/event；agent/* 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。

维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。