What is the dsh agent loop? How one turn runs

What the agent loop is — and is not

DeepSeek Harness is built on Cordis, a plugin framework where services, typed events, and reversible effects are contributed to one shared context. The official docs state the consequence plainly: every part of the product is a plugin — the model adapter, the tool registry, the session log, and the agent loop itself. core/agent-loop is the default driver implementing the generic Agent interface, and it is replaceable from configuration.

Two definitions do all the work on this page, both from the official turn-flow documentation:

The life of one turn, stage by stage

The official docs publish the exact event sequence of a turn. The diagram below walks it in order — the mono chips are the real identifiers from the docs, the same names you would listen for in a plugin.

Two details are worth remembering: retries inside a step do not repeat prompt assembly or agent/pre-step, and "model-visible means logged" is a hard rule — every model request must be reconstructable from the session log.

Where plugins hook into the loop

The docs never say "hook" — the official word is events, and most of them are waterfalls: listeners receive a context and must call next() to delegate, rewriting the payload first if they need to. Four families matter most, and agent.inject() is the official door for adding model-visible context from outside the loop:

plugin development guide.

Agent loop vs subagents vs Agent Teams

Searches like "dsh agent swarm" mix three different layers. Anchor each layer to the loop and they stop blurring together:

subagents guide.

When the loop misbehaves: loop guards

The loop is designed to end: a turn closes once nothing is owed, and agent/turn-stopping exists precisely so a listener can halt one. Runaway behavior therefore almost always comes from what feeds the loop — usually a plugin that keeps injecting new input.

The best-documented case is official discussion #4819. The community plugin dsh-agent-loop auto-continues when the model answers with reasoning only and no visible text — it injects a notice message to push the loop forward. Those injected messages were written without a message id, so on cold restore the session log failed validation ("session event lacks an identified message") and the whole session became unopenable. The fixes discussed there are the canonical guard set: route synthetic messages through the normal createUserMessage path, and validate event shape at append time — not only at restore.

• ▸Cap the cycles — a round limit per turn is the first invariant of every loop-guard recipe.
• ▸Detect no progress — if two consecutive steps change nothing, stop instead of continuing.
• ▸Trip on the same error twice — a circuit breaker beats an expensive retry storm.
• ▸Keep an explicit exit gate — the loop should always have a human-visible way out.

context compaction guide.

Frequently asked questions

Short answers about the dsh agent loop — the details are in the sections above.

Keep reading

Guides that sit beside the loop or drive it: subagents, modes, presets, and context compaction.

Sources & evidence

Every mechanism on this page follows the official architecture documentation, discussion #4819, and the v0.2.1-alpha.1 release notes — version-specific behavior always defers to the official changelog. The Loop Guard invariants are a community protocol.