Tianyi Cui
50f0291b93
# Conflicts: # docs/architecture.md # examples/acp-agent/tests/snapshots/bash-spill/session.jsonl # examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # packages/core/agent-loop/src/loop.ts
62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
|
|
Run `pnpm run gen-doc-graphs` to regenerate. -->
|
|
|
|
# Agent Turn And Step Lifecycle
|
|
|
|
This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
|
|
|
|
```mermaid
|
|
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 Persistence
|
|
participant SDK as UI or SDK listener
|
|
User->>Agent: send(content)
|
|
Agent-->>SDK: <code>agent/queued</code>
|
|
Agent->>Driver: queued work wakes driver
|
|
Driver-->>SDK: <code>agent/status</code> running
|
|
Driver->>Session: <code>turn/start</code>
|
|
Driver->>Hooks: <code>agent/prompt-submit</code> waterfall
|
|
Hooks-->>Driver: allow, block, or add context
|
|
Driver->>Session: <code>user/message</code> or rejected <code>turn/end</code>
|
|
Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
|
|
Driver-->>Driver: <code>agent/pre-step</code> serial checkpoint
|
|
Driver->>Session: <code>step/start</code>
|
|
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>*
|
|
Driver->>Hooks: <code>agent/step-result</code> waterfall
|
|
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>
|
|
Driver->>Hooks: <code>agent/turn-continuation</code> waterfall
|
|
Driver->>Hooks: <code>agent/turn-stop</code> serial terminal checkpoint
|
|
Driver->>Session: <code>turn/end</code>
|
|
Driver->>Persistence: <code>session/flush</code> parallel checkpoint
|
|
Driver-->>SDK: <code>agent/status</code> idle
|
|
```
|
|
|
|
The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.
|
|
|
|
SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.
|
|
|
|
Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.
|