DSH plugin agent loop: how one DeepSeek Harness turn runs

One DeepSeek Harness turn passes through six packages — agent-loop, system-prompt, the llm seam, tools, session and the agents service — and this piece traces that order (source). Understand it and you can see who does what for every message you send: who assembles the input, who calls the model, who executes tools, who writes the result back. This piece is about the flow itself; each part's internals are covered in the system prompt, the tool pipeline and session persistence.

The full chain of one DeepSeek Harness turn

One DeepSeek Harness turn passes through six packages in a fixed order: agent-loop, system-prompt, the llm seam, tools, session and the agents service (source). Each link does one thing:

1. agent-loop opens the turn: it starts a round and walks it forward step by step — it organises, it does not execute.
2. system-prompt assembles the input: it gathers fragments into a prefix and hands it to the model — this is the opening of what the model reads.
3. the llm seam calls the model: model access is made a seam, so providers can be swapped; this link turns "assembled input" into an actual request.
4. tools executes the requested calls: the model can only request a tool, so actual execution lands here, and its result becomes part of the turn.
5. session writes the result back: the turn's outcome is recorded in the session log, which is also what the next round reads.
6. agents handles delegation: when a turn needs to hand a subtask to a sub-agent, that goes through this service and returns its result to the flow.

In one sentence: this chain is the "one full response" you see in the UI — written down as six cooperating DSH plugin packages.

The opening link: agent-loop and conversation nodes

agent-loop is the opening link of a DeepSeek Harness turn: it starts a round and advances it through conversation nodes rather than calling the model or tools itself (source). Four points:

1. It only organises: agent-loop's job is to keep the round moving — the model call and tool execution are each handed to the package responsible for them.
2. It advances in conversation nodes: think of a node as one step in the flow; the loop moves through nodes so a turn has explicit staging rather than one monolithic function.
3. It decides when the turn ends: whether to continue, whether to let the model produce the final answer, whether any tool result still needs handling — all orchestrated here.
4. It is the natural place for extension: if a DSH plugin wants to intervene in the flow, conversation nodes are a well-defined place to hook in; concrete interface details are in how to work with conversation nodes.

The middle three links: prompt, model, tools

In the middle of the chain, system-prompt assembles the prefix, the llm seam makes the model call, and tools executes the requested calls — each doing exactly one job (source). Three points:

1. Assemble: system-prompt gathers tool descriptions, system instructions and plugin-contributed fragments into a prefix; how it is built is in the system prompt explained.
2. Call: the llm seam turns the assembled input into a model request. Because model access is a seam, swapping providers does not touch the rest of the chain.
3. Execute: whatever tool the model requests is actually run by the tools layer, with schema constraints and the execution pipeline applying; the details are in the tool pipeline.

The three are sequential: what is assembled decides what the model can reference, what the model returns decides whether a tool is needed, and what the tool returns decides what enters the next round.

The closing link: writing back to the session

The closing link is session writing the turn's result back into the session log, which is the context the next round reads and the record you review afterwards (source). Three points:

1. The next round depends on it: a turn without a written-back result leaves the next round without context, which shows up as the model "forgetting" what just happened.
2. It is where history comes from: the session history you browse is exactly these written-back records, not a separate copy; the data model is in sessions, stored and queried.
3. It closes the loop: after writing back, one turn is complete and the next can start reading the log.

Why the order of the chain matters

The order matters because each link's input is the previous link's output: assembling precedes calling, calling precedes execution, and execution precedes writing back (source). Consequences:

1. Changing the order breaks the flow: a tool cannot run before the model asks for it, and the model cannot reference a prefix that has not been assembled.
2. A broken link surfaces later: a prompt-assembly problem shows up as a model behaving oddly, and a write-back problem as the next round losing context.
3. Troubleshooting locates by link: "the model is not following instructions" is most likely in assembly, "the tool is not running" in execution, "it forgot the last step" in write-back.
4. Each link is replaceable on its own: because the order is fixed and the interfaces are stable, swapping providers, tools or session storage does not require rewriting the whole flow.

Notes on the agent loop

Read this chain as "one full response split into six cooperating packages" and locating a problem becomes a matter of finding the link.

1. It is a chain, not a single function: agent-loop, system-prompt, llm, tools, session and agents each do one job.
2. agent-loop only organises: it does not call the model and does not run tools.
3. Middle three are sequential: assemble → call → execute, each depending on the one before.
4. Write-back is not optional: without it the next round loses context.
5. A broken link surfaces indirectly: prompt problems look like model misbehaviour, tool problems like a silent tool.
6. Troubleshoot by link: locate the stage first, then look at that package.
7. Extension goes through conversation nodes: to join the flow, use the node interface — see how to work with conversation nodes.

Source: DeepSeek Harness docs - core subsystems, docs - architecture overview.