mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
44fd93fd06
Replace send/steer/inject with one Agent.send primitive over the (target × wakeup) matrix; followup/steer/inject become fixed-preset alias methods on the now-abstract Agent class. Coalesce context/message into user/message (injected context is a non-user source). Replace agent/queued with agent/inbox/enqueue/dequeue/discard, add cancel keepInbox, and add a FIFO-conservation invariant.
74 lines
4.0 KiB
Markdown
74 lines
4.0 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/inbox/enqueue</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: authoritative 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>*
|
|
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: retry in a new step or preserve the original error
|
|
else model request succeeded
|
|
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: post-tool context and steering (no prompt-submit)
|
|
Driver->>Hooks: <code>agent/post-step</code> serial checkpoint
|
|
Driver->>Session: <code>step/end</code>
|
|
Driver->>Hooks: <code>agent/turn-continuation</code> waterfall
|
|
Driver->>Hooks: <code>agent/turn-stop</code> serial terminal checkpoint
|
|
end
|
|
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.
|
|
|
|
`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts 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 a fresh retry step, and returns retry only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
|
|
|
|
The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.
|
|
|
|
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.
|