DSH plugin agent lifecycle: turn/step and event streams

The most common agent-lifecycle mistake is treating two event families as one: agent/* is real-time coordination, while session/event is durable replay. The first tells you what is queued, running, or worth retrying; the second tells you what actually happened. Decide which one you need before writing a plugin, or you will see “it was live but not in replay” and misread it as data loss.

DeepSeek Harness: The shape of a turn

A user input enters the inbox, the driver claims it as a turn, and the turn can run multiple steps. The main sequence:(source)

1. followup(content) — a user or upstream puts a message in the inbox. Expected: agent/inbox/spliced and agent/inbox/inserted.
2. turn/start — the driver wakes and status becomes running. Expected: it claims pending next-step input plus one queued prompt.
3. system-prompt/assemble — the system prompt is assembled. Expected: a waterfall can rewrite it here.
4. agent/pre-step — decides whether to enter a message batch. Expected: reject or enter(messages).
5. step/start — a step begins. Expected: agent/request, request preparation, and message admission follow.
6. assistant/message or assistant/attempt — records success or a failed attempt. Expected: agent/assistant-stream emits chunks first, then a committed end.
7. Tool execution — classified by executionMode and scheduled with barriers and a bounded rolling pool. Expected: tool/call, tool-owned events, and tool/result in order.
8. step/end → turn/end — the turn closes when there is no next-step input and the agent stops naturally. Expected: status returns to idle.

If pre-step rejects, the first batch is empty, or pre-step fails, the claimed batch stays removed and the open turn spends no step. That is a normal refusal, not an error.

DeepSeek Harness: agent/* versus session/event

Real-time state and durable facts are separate channels; consuming the wrong one gives an incomplete history. Compare:(source)

The official guidance is direct: SDK users who need a replayable transcript should consume session/event. agent/* is not history; it is coordination.

Realtime agent/assistant-stream chunks are transient. Replay reads the durable settlement in assistant/message or assistant/attempt. A hard interrupt before settlement leaves no persistent attempt stream.

DeepSeek Harness: Three intervention points

A plugin does not need to modify the driver; pick the right hook: pre-step for admission, request-error for overflow, turn-stopping for closure. Three points:(source)

1. agent/pre-step — intercept or replace messages before the request is built. Expected: reject a batch, add context, or preserve downstream messages.
2. agent/request-error — handle canonical context overflow and retry decisions. Expected: return a retry action or preserve the original error; do not use it as a generic catch-all.
3. agent/turn-stopping — a serial terminal checkpoint when the agent stops naturally with an empty inbox. Expected: close out checks; do not start long work here.

When wrapping next(), preserve downstream messages and startsRequestSeries unless you intend to replace the whole batch.

DeepSeek Harness: Tool concurrency and barriers

Tools do not all run concurrently; the driver classifies by executionMode and controls the pace with barriers and a bounded rolling pool. Key points:(source)

• Classify before start — each pending call gets an execution mode. Expected: read-only and write calls do not interleave arbitrarily.
• Ordered pre, concurrent execute, ordered post — pre and post follow model order, execution may run concurrently. Expected: results still match the model’s request order.
• Tool-owned events — tools may emit their own events during execution. Expected: they do not replace tool/result.
• Barriers reclassify — the rolling pool rechecks before starting. Expected: state changes cannot bypass a barrier.

When writing a tool plugin, do not assume the previous tool has finished; declare ordering explicitly instead of relying on timing.

DeepSeek Harness: Three consumption modes

UI, SDK transcript, and plugin hooks need different streams; choosing wrong adds glue code. Three:(source)

1. UI real-time — consume agent/status and agent/assistant-stream. Expected: status and streaming stay current.
2. SDK transcript — consume session/event. Expected: complete turns, steps, and tool results for replay.
3. Plugin hooks — listen to agent/pre-step, agent/request-error, and agent/turn-stopping. Expected: intervene at the right phase without breaking driver order.

If the two channels disagree, use session/event for history and agent/* for real-time coordination.

DeepSeek Harness: A compact event order

When debugging timing, list the key events in order instead of reading the whole log. Simplified:(source)

If a segment is missing, do not blame the model first; check whether pre-step rejected it, it was cancelled, or the process stopped before settlement.

Three diagnostic rules

Timing problems are easier to locate by “which segment is missing” than by reading every line. Three rules:

1. turn/start without step/start — usually pre-step rejection, an empty first batch, or pre-step failure. Expected: the turn spends no step; this is a normal refusal.
2. step/start without assistant/message — the request failed or was cancelled, possibly leaving assistant/attempt. Expected: check request-error and the cancellation reason.
3. tool/call without tool/result — the tool is still running, blocked by a barrier, or the process stopped. Expected: inspect executionMode and active execution.

These rules point at admission, request, or tool layers instead of a vague “the agent is stuck”.

DeepSeek Harness FAQ

Why is there live output but no replay? Realtime chunks are transient; replay reads settlement. An attempt without settlement leaves no persistent stream.

Can a step appear after turn/end? No. turn/end is the end of the turn; the next input starts a new turn.

Where does compaction happen? Base compaction handles pressure through agent/pre-step; agent/request-error handles canonical context overflow. It prunes tool results before choosing summarization.

The short version: real-time uses agent/*, history uses session/event, and intervention picks the right hook. Mixing them turns coordination state into a false audit trail.