deepseek-harness/docs/graphs/agent-lifecycle.md

Agent Turn And Step Lifecycle

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

This sequence is the visual companion to architecture.md. It shows the durable session event path separately from live agent/* notifications.

sequenceDiagram
  participant User
  participant Agent
  participant Loop
  participant Prompt as ctx.systemPrompt
  participant LLM as ctx.llm
  participant Tools as ctx.tools
  participant Session
  participant Persistence
  User->>Agent: send(content)
  Agent->>Loop: queued work wakes driver
  Loop->>Session: turn/start + user/message
  Loop-->>User: agent/turn-start
  Loop->>Prompt: system-prompt/assemble waterfall
  Loop-->>Loop: agent/pre-step serial checkpoint
  Loop->>Session: step/start
  Loop->>LLM: agent/request waterfall, then llm/stream waterfall
  LLM-->>Loop: StreamChunk*
  Loop->>Session: assistant/chunk*
  Loop-->>User: agent/stream-chunk* (master live mirror)
  Loop->>Session: assistant/message
  Loop->>Tools: tools/execute waterfall for each tool-call
  Tools-->>Session: tool-owned events when applicable
  Loop->>Session: tool/result
  Loop-->>Loop: agent/turn-continuation waterfall
  Loop->>Session: turn/end
  Loop->>Persistence: session/flush parallel checkpoint
  Loop-->>User: agent/status idle

Future pressure from the hooks stack: PR #129 removes the live agent/stream-chunk mirror and leaves durable assistant/chunk on session/event as the authoritative token stream. Consumers that need replayable transcript data should already treat session/event as the load-bearing path.