How DeepSeek Harness Redesigns the Agent Runtime: Managing Capabilities, Clean Shutdowns, and Task Recovery

DeepSeek Harness (DSH) provides an architectural sample of an Agent runtime, exposing the core questions of how capabilities are loaded, how they are cleaned up on exit, and where a task stops and can later resume. The Loop is only the middle circle; long‑running stability depends on the surrounding boundaries.

Visualizing DSH as a Runtime Chain

When viewed as a directory tree DSH looks complex, but tracing a single task clarifies the flow:

Bundle + Runtime Profile + Patch
    ↓
Cordis Host Runtime Graph
    ↓
Agent Preset (session capability set)
    ↓
Agent Loop
    ↓
Tool Pipeline / PTC
    ↓
Session Event Stream
    ↓
Stop, Restore & Goal

Two parallel concerns run on this chain: Cordis answers "what can be done now" (which plugins are active, which services are available, and how to clean up on replacement), while Session records "what just happened" (user messages, model requests, tool calls, and turn termination).

Key insight: The runtime graph answers current capabilities; the event stream records past facts.

Two‑Layer Assembly: Profile and Preset

DSH defines several Runtime Profiles ( web, headless, sdk, sdk-minimal, acp) that, together with Bundles, user patches, and command‑line patches, decide what is loaded at process start. Profiles are process‑level, not per‑session.

Agent Presets ( Standard, PTC, Minimal, Cordis) select a set of plugins, tools, and prompts for a session. All Presets share the same Loop, Session, and tool pipeline; switching a Preset merely changes "which capabilities this round carries".

Standard : full Coding Agent capabilities.

PTC : alters how the model sees and organizes tools.

Minimal : narrows prompts and tools for baseline experiments.

Cordis : adds runtime checks and dynamic plugin tools on top of Standard.

Configuration order matters: merge Bundle, then apply Profile‑provided patches, then user patches, and finally command‑line --patch. Later entries overwrite earlier ones; --dump-config prints the effective configuration.

Cordis: A Live Runtime Graph

Cordis goes beyond a static registry. It tracks each plugin’s context (realm), the services it provides, and the lifecycle events (start, stop, cleanup). When a component is removed, Cordis can locate and clean up its side‑effects; when a dependency is replaced, it can stop the old component and start the new one.

Key terminology: Context: defines the realm and service lookup boundary. Service: stable interface offered by a plugin. Fiber: a single plugin execution instance. inject: declares which services a Fiber depends on. effect: bundles listeners, timers, and cleanup functions; a Fiber waits for dependencies and exits when they become invalid.

Agent Loop Boundaries

The minimal Loop is often written as while (hasToolCalls), but a real task may finish a model request without further tool calls, meaning the request ends while the overall task continues.

DSH splits the execution boundary into several layers:

step : one model request plus subsequent tool execution; step end ≠ turn end.

turn : starts with an input and may contain multiple steps; new messages or plugin‑added context can extend the turn.

driver activity : a continuous run segment; the Loop returns to idle only after no further turns.

Goal : sits outside activity; an idle Agent may still have an active Goal (states active, blocked, paused, complete) that drives future activity.

Additional hooks include agent/pre-step (can reject or empty a step) and startsRequestSeries (starts an independent message series). Cancellation reasons ( max‑tokens, aborted, interrupted) are recorded and not overwritten by the final model reply.

Unified Tool Pipeline

When the model decides to call a tool, DSH follows a single pipeline:

Model emits tool call
→ Session writes tool/call
→ tools/pre‑execute decides allow/reject/query
→ guard tightens constraints
→ tools/execute runs the tool
→ tools/post‑execute checks/completes result
→ tools/result publishes real‑time result
→ Session writes tool/result

All tools, including Shell, MCP, and PTC‑generated sub‑calls, pass through the same guards and observation events. Parallel execution is opt‑in; otherwise calls are exclusive and results are ordered as originally requested.

Programmatic Tool Calling (PTC)

PTC lets the model write a short program that invokes multiple tools in sequence, returning only the program’s final output to the model. The model still sees the same permissions, tool registration, and result logging. In dsh-v0.1.1-rc.2 this was called Code Mode; in alpha.2 it became the unified PTC mode.

Example TypeScript snippet:

const [branch, diff] = await Promise.all([
  tools.bash({ command: 'git branch --show-current', description: 'Show current branch' }),
  tools.bash({ command: 'git diff --name-only', description: 'List changed files' })
]);
return { branch, diff };

Each tools.bash() call re‑enters the full tool pipeline, preserving guards and logging. PTC runs in a fresh Worker, leaving no REPL state after completion.

Session Event Log and Model Projection

Session stores an append‑only event log containing turn/start, turn/end, step/start, step/end, user/assistant messages, tool/call, tool/result, request/header, and termination reasons. The model’s next context is derived by projecting these events, keeping the log and model view separate.

Projection utilities include stateOf() for typed state reads and snapshot() for trimmed views. The Agent Loop registers turnBoundary in the same mechanism, allowing UI, audit, and recovery to consume the same event stream without duplicating state.

Only events marked with surfaceOp (user messages, assistant replies, tool results) are fed into the model context; other events remain invisible to the model but are available for replay, audit, or debugging.

Dynamic Cordis: Changing Capabilities at Runtime

Dynamic Cordis introduces a two‑step process: cordis_define registers an immutable package version (syntax and parameter checks only), and cordis_run activates it. Packages can register tools, prompts, services, listeners, or UI components. Deactivation ( cordis_stop, cordis_undefine) removes the package’s resources.

Unlike PTC, which only affects the current execution, Dynamic Cordis changes the runtime graph so that subsequent requests see the new capabilities. If activation fails, the previous package remains defined but inactive; manual recovery is required.

Dynamic Cordis packages are held in process memory; only the defining Session can see and control them. Packages may affect other Sessions in the same process, and definitions disappear on process restart.

Execution Environments and Security Boundaries

DSH runs PTC programs in Worker Threads and evaluates Dynamic Cordis host code via node:vm. Both provide containment (resource limits, time budgets) but are not trusted isolation: they can still access Node APIs, spawn subprocesses, and affect the host process.

Workers have separate state, budgeted CPU/wall‑clock time, and can be terminated, yet a spawned OS process may outlive the worker. The vm sandbox only limits synchronous evaluation; asynchronous code can continue running.

Security therefore requires threat modeling of which agents can invoke which tools, the host’s permissions, and the reach of dynamic code. Neither Worker nor vm alone guarantees a secure sandbox, especially for browser‑enabled dynamic packages that may await manual approval.

What DSH Redesigns

DSH does not invent a new LLM loop; it reorganizes the surrounding concerns:

Profile & Preset : define where capabilities are loaded from.

Cordis : track plugins, dependencies, and clean‑up.

Agent Loop : manage task progression.

Unified Tool Pipeline : handle permissions, execution, and result checks.

Session : persist immutable task facts for projection.

Goal : keep long‑term completion state outside a single activity.

Dynamic Cordis : allow in‑process capability changes.

The trade‑off is added complexity: a live plugin graph, dependency reconnection, event projection, and dynamic permission handling increase the learning and debugging burden. For simple, short‑lived tasks with fixed tools, a straightforward registry and minimal Loop may be preferable. When dynamic composition, cross‑turn goals, audit, recovery, and multi‑host scenarios are required, DSH’s architecture shows its value, though it is not the only possible solution and remains a preview version.