Tianyi Cui
10ef3d4924
A corpus sweep under the doc/prose standards found 15 links whose #fragment named no anchor in its target — reworded headings, one relocated contract (tool-fs → the group README's no-timeout rule), and zh sides citing English slugs their Chinese headings never produce. Fixed all 15 (zh sides get the conventional explicit <a id> + English fragment), fixed the one generator-owned instance at its source (gen-doc-graphs), and extended verify-md-links to resolve fragments onto Markdown targets — same-file anchors included — against heading slugs and explicit <a id>, so the class is gated instead of manually grepped. Remaining probes (narrated history, duplication shingles, comment transcripts, budgets) came back clean; sibling-adapter README symmetry and implemented-note contrasts are deliberate keeps.
83 lines
4.4 KiB
Markdown
83 lines
4.4 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#default-loop-lifecycle). 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 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
|
|
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, no turn opens
|
|
else enter proposed step
|
|
Driver->>Session: <code>turn/start</code>
|
|
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
|
|
Driver->>Session: <code>turn/end</code>
|
|
end
|
|
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.
|
|
|
|
`dsh-compact-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 boundary claims their next-step batch.
|
|
|
|
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.
|