deepseek-harness/packages/core/agent-loop/README.md

dsh-agent-loop

English | 中文

THE concrete agent plugin and loop driver. Its package-internal implementation satisfies the Agent interface and drives the session/turn/step lifecycle.

This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension seams — new behavior goes into plugins, not here.

Service: AgentLoop (ctx key: agentLoop)

Public API

Creation and resume are one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; synchronously invoke its optional publication commit; enter both registries; announce session/created then agent/created; emit agent/session-start; and only then start the driver. Setup receives the full scoped Context as trusted same-process composition code and must not drive the unpublished agent. Its optional commit revalidates mutable provisioning after every setup await and immediately before registry entry; a throw rolls the private transaction back without publishing either id. Ordinary typed identity and option inputs are borrowed under their readonly contract, while seed events and session metadata are validated and snapshotted because they cross the durable session boundary. An optional AbortSignal cancels only load/setup/publication and is detached before the returned handle becomes visible.

The caller fiber and the AgentLoop provider are co-owners. AgentFactory.createAgent(ownerCtx, options) and resume(ownerCtx, options) receive caller ownership explicitly, while the factory keeps its own dependency context for sessions/llm/tools/systemPrompt; this lets a caller inject only agents without shrinking the new agent's service surface. Caller unload, handle disposal, or provider unload converge on one memoized quiescence boundary. Provider shutdown waits both resource teardown and the public create/resume wrapper that observed deactivation, so no continuation can publish after dependencies disappear.

Each agent and its session share one caller-chosen SessionId, assumed globally unique; accidental UUID collisions are outside the supported model. Two concurrent operations with the same id may both prepare, but the final enter() calls arbitrate publication and every loser rolls its private resources back. Each detach is bound to the exact entered object, so a stale disposer cannot remove a later same-id replacement. A detach requested during a synchronous creation notification waits for that dispatch to unwind, preserving created/disposed pairing. Teardown runs stop and drain → unwind scope → detach agent → detach session; the id becomes reusable after private scope cleanup. Ordinary non-vetoing agent/* notifications go through agentEvents(ctx, agent), and per-step assembly goes through assembleContextFor(agent).

• ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent — synchronous no-setup create under the exact shared agent/session id, disposed with the calling fiber. Declarative config treats agents[].id as a stable label and normally mints ${label}-session-<uuid> before calling this boundary. An app may instead supply a stable exact sessionId: first use creates it, while a remount with persistence already present resumes its materialized history. resumeSessionId requires and loads an existing persisted id and is mutually exclusive with sessionId. This keeps default fresh restarts collision-free without retaining a second live routing identity.

AgentLoop also implements the AgentFactory seam and registers itself via ctx.agents.setFactory(this), so plugins create/resume agents through ctx.agents (the interface):

• ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle> — programmatic create under the caller-supplied shared id. It awaits unpublished setup, invokes its optional synchronous commit at the publication boundary, and then enters both registries; meta carries cwd/lineage/seed-boundary metadata and seed reconstructs a forked child prefix after the session boundary validates and snapshots the durable values. signal applies only until this promise settles. The resolved AgentHandle owns exact teardown.
• ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle> — load a persisted session via ctx.sessionPersistence (session persistence), reconstruct its history under the same id, await setup against a fresh unpublished agent scope, invoke its optional synchronous commit, then use the same rollback-covered publication sequence. Turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; resume rejects with a clear error when persistence is absent). signal is creation-only. Returns an AgentHandle.

The config-driven ctx.agentLoop.create() path keeps its agent owned by the loop fiber (it discards the handle). For a programmatic agent, the handle holder is the only consumer-facing teardown capability; AgentLoop provider unload is the independent structural teardown edge, not another handle exposed to application code.

Injected services

agents, sessions, llm, tools, systemPrompt — all five interface services.

Invariant companion

The optional @deepseek-ai/dsh-agent-loop/invariant companion registers request reconstruction with ctx.invariants. The loop records each exact frozen request in the process-local identity set owned by dsh-llm; the companion then requires a live session and independently rebuilds the message boundary and folded request header from the log. Direct one-shot calls remain outside this contract even when callers freeze them or attach a session id.

Configuration (schemastery)

interface Config {
  maxParallelToolCalls?: number // default 10; 1 is serial
  agents: Array<{
    id: string                 // required
    provider?: string
    model?: string
    maxTokens?: number         // positive per-request output-token cap
    resumeSessionId?: string   // load this persisted session instead of creating one
    cwd?: string               // optional workspace cwd for the fresh session
  }>
}

Configured agents start automatically. A model call requires both provider and model; agent/request may supply a missing pair before dispatch. An optional positive maxTokens seeds each conversation request's output cap and is logged in its request header. maxParallelToolCalls bounds every agent's rolling pool for parallel-safe calls and defaults to 10. cwd applies only to fresh sessions, while resumeSessionId retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent provider, model, and cwd prompt variables; harness identity and deployment persona belong to dsh-system-prompt.

Internal concrete driver

The concrete ReactLoopAgent, its queued input, outbox, and run controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no ./src/* escape hatch; lifecycle owners create agents through ctx.agents rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the agent/* event taxonomy.

The unified send() primitive routes content and source by (target × wakeup); followup/steer/inject are its fixed-preset aliases. A next-turn item joins the queued FIFO, waking the driver unless wakeup: false; admission happens before any turn opens. reserveTurnAdmission() can synchronously hold that idle boundary for a standalone durable operation: accepted waking work has right of way, later sends keep their ordinary queue identity and FIFO position, release re-arms the same driver path, and whenIdle() waits for the reservation without making teardown await it. The loop opens a private next-step acceptance window before agent/prompt-submit and closes it before turn/end. During that window, steer() and inject() stage in one outbox; an allowed admission opens the turn, records the prompt and returned additionalContexts, then drains the staged input before the first request. A blocked or failed admission writes no prompt or hook-produced context. A caller-staged context-only batch then takes idle injection's immediate append, while steering and context staged beside it remain pending for retry or a later admitted prompt. Outside the window, steering becomes a waking queued prompt and injection immediately appends user/message without opening a turn or running the model.

steer() attaches a one-shot admission receipt to its exact accepted message. After agent/step and asynchronous prompt assembly succeed, the loop commits a stable pending batch as steering/message, snapshots derived history, and opens step/start; only then does each receipt resolve admitted with that turn and step. Later arrivals remain pending. Idle steering enters the ordinary FIFO and uses the first request of its eventual turn as the same admission boundary. A turn-concluding tool result, broad cancellation, disposal, or a claimed idle-steering turn that never reaches a request resolves affected receipts rejected; cancel(..., { keepInbox: true }) and non-terminal routing preserve pending delivery. Open-turn inject() still commits after all tool results, including accepted context finalized during an interrupted batch, while steering remains provisional until a request admits it.

Every FIFO acceptance mints an InboxItemId and publishes agent/inbox/enqueue with the complete occurrence. updateInbox() owns the synchronous queued-item boundary: edit freezes replacement content without changing message identity or position, remove publishes discard, and strict steer transfers the immutable message into an open next-step window as a new steering occurrence. A closed window returns steer-unavailable without mutation; pending steering and claimed occurrences return not-found. Claim publishes agent/inbox/dequeue and irrevocably removes the live address before prompt admission, so a racing update cannot rewrite durable history; cancel() without keepInbox publishes agent/inbox/discard.

Loop lifecycle (agent.ts)

The driver owns one agent for its lifetime and runs inside ctx.agents.withInitiator(agent, ...). Package-private orchestration entry points recover the exact Agent, derive agent.session once, and let operation-local helpers capture it instead of forwarding the concrete driver or per-operation Session through shallow interfaces. A helper keeps an explicit Session when that is its actual interface, while creation, persistence load, unpublished setup, services, workers, processes, persistence, and wire protocols retain their explicit identities. The agent service owns propagation, teardown, and detached-work rules.

Every provider call that reaches a successful finish appends exactly one assistant/message completion anchor, including content-less calls and max-tokens finishes. The anchor records the assembled content as-is, retains exact chunk provenance ([] for a stream with no chunks), and includes usage when available; empty content stays out of derived message history.

After agent/request returns a provider/model call config, the loop asks ctx.llm.prepareCall() to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, request/header logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an llm/stream listener can own and short-circuit it; unhandled terminal dispatch still fails with NO_ADAPTER. A new loop instance applies the same provenance rule when resuming.

Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter agent/request-error; middleware, result processing, tools, and other extension failures close directly. Recovery receives the exact live error, immutable provider facts, immutable prior failures, the immutable retry policy of the adapter registration that served the request, and the turn signal after the failed step closes; the policy is absent if no final adapter served it. A handling listener returns { kind: 'retry' }; the loop closes the failed turn with its error and opens one numbered retry turn without an intervening idle notification. Success clears the consecutive history, and an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective cancel(cause) clears pending work unless keepInbox is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable turn/end records aborted for user and parent, while disposal records disposed; undispatched model tool calls receive synthetic tool/call and ABORTED_BEFORE_DISPATCH result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The explicit-cancellation decision owns the lifecycle and race contract.

Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, and retains their finalized result context without distinguishing the cancellation cause. An internal scheduler failure stops new dispatches, waits for already-started dispatches, and reaches the turn error boundary without fabricating tool results.

What belongs to plugins

Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:

• Hooks and policy: the relevant agent/* checkpoints plus the guarded tools/pre-execute → tools/execute → tools/post-execute → definition-owned finalizeContent → tools/result pipeline; exact event signatures and modes live in the generated event catalog
• Compaction: pressure on agent/step; canonical overflow repair on agent/request-error
• Model-request recovery: dsh-llm-retry records and waits exact-provider normal or unbounded backoff on agent/request-error, emits non-surface llm/retry status, then returns a retry action
• Sandbox, permission, plan mode: tools/pre-execute for extensible deny/ask, tools.guard() for monotonic owner policy, tools/post-execute for result decisions, and tools/result for final observation
• Sub-agents: implemented outside the loop as ctx.subagents providers; in-process providers use ctx.agents.create() and owned AgentHandle teardown, while generic ctx.tasks plus dsh-tool-subagent own background collection.
• Persistence: eager write-behind from session/event; session/flush is an explicit observation barrier
• UI: session/event (assistant token stream, boundaries, tool activity) + agent/* control events (agent/status, agent/created/agent/disposed)

Model Experience

Complete conversation request

What the model sees

For each step, the loop sends the rendered per-agent system prompt, visible tool schemas, and the session's derived messages. It supplies provider, model, and cwd variable values but no additional fixed prose.

Token effect

System text and schemas are paid again on every step. Per-agent scoping chooses the contributions, while the authoritative assembly waterfall can alter the final request and makes its listener responsible for protocol coherence.

KV Cache effect

Append-only only while system text, schemas, and earlier history remain byte-identical under the same provider and model route. A token-bearing assembly rewrite or composition change may invalidate reuse from the first altered request token.

Retained message history

What the model sees

Accepted user messages, assistant messages, tool calls and results, injected context, and steering are logged and sent on later steps. Raw stream chunks, lifecycle boundaries, and other log-only events are excluded.

Token effect

Input grows with every surface message until a compaction replacement shadows older nodes; a multi-step tool turn resends the accumulated history each step.

KV Cache effect

Ordinary history growth is append-only and preserves reusable entries. A surface replacement or compaction invalidates reuse from the first shadowed history token.

Undispatched calls after cancellation

What the model sees

If a later request replays an aborted step, each tool call that cancellation prevented from dispatching has error code ABORTED_BEFORE_DISPATCH and result text Error: tool call aborted before dispatch.

Token effect

One fixed error result per skipped call remains in history until compaction shadows it.

KV Cache effect

Append-only; each synthetic result follows the reusable request prefix and does not invalidate existing KV-cache entries.

Known Limitations and Deferred Work

• Classification is unary — calls whose safety depends on comparing siblings or resources must remain exclusive (rationale).
• Config labels are fresh by default — omitting sessionId creates a fresh ${id}-session-<uuid> on every startup; exact resume-or-create behavior requires an explicit stable sessionId, while resumeSessionId requires existing persisted history.
• Config agents have no per-agent persona field or setup hook — they use the deployment persona; scoped persona/tool composition is available only through the programmatic ctx.agents.create() / resume() factory options.
• No built-in turn budget — tool calls or steering continue the current turn; a policy that bounds runaway turns must cancel from an existing lifecycle seam such as agent/turn-stopping.