deepseek-harness/docs/architecture.md

DeepSeek Harness Architecture

The DeepSeek Harness SDK builds agent harnesses on Cordis; everything, including the shipped loop, is a plugin.

Overview

A harness is one Cordis context. Packages add services (ctx.llm, ctx.tools, ctx.sessions), typed events (agent/request, tools/pre-execute, session/event), and disposable prompt, tool, provider, adapter, and listener registrations.

packages/core/ groups the default agent flow; surrounding capabilities are equally first-class Cordis plugins.

Default Services

ctx key	Package	Role
—	dsh-scope	scoped-context registration primitive (library)
ctx.sessions	dsh-session	in-memory event-sourced sessions
ctx.systemPrompt	dsh-system-prompt	ordered prompt sections, tool schemas, and prompt variables
ctx.tools	dsh-tools	tool registry and execution pipeline
ctx.agents	dsh-agent	live agents, delegated creation, agent/* events, and process-local initiator scope
ctx.agentLoop	dsh-agent-loop	concrete Agent driver

Capability Services

ctx key	Package family	Role
ctx.llm	llm/	adapter registry and streaming model calls
ctx.tokenMeter	llm/token-meter	singleton replay-aware request/surface pressure
ctx.bash	bash/	foreground/background command execution
ctx.pty	pty/	owner-scoped persistent terminal sessions
ctx.sandbox	sandbox/	same-world process confinement (argv wrapping, per-call policy)
ctx.sandboxPolicy	sandbox/	shared sandbox policy home
ctx.codeRuntime	code-runtime/	model-written program execution
ctx.fs	fs/	filesystem provider primitives and policy events
ctx.skills	skill/	skill provider registry and progressive disclosure
ctx.web	web/	search/fetch provider registries
ctx.compact	compact/	session-log compaction
ctx.subagents	subagent/	named delegation providers
ctx.tasks	tasks/	background task registry + generic task_* control tools
ctx.workflows	workflow/	script-driven multi-agent orchestration
ctx.sessionPersistence	session-persistence/	durable storage for session logs
ctx.sessionQuery	session-query/	live-preferred logical-corpus exact reads and relationship traces

Event

Events form the service extension API; see the exhaustive events catalog and producer/consumer map.

Event Domains

• Session events are durable, replayable facts: boundaries, messages, tool activity, steering, compaction, and tool-owned records append to the log and flow through session/event.
• Agent events carry the live Agent handle for status, diagnostics, prompt admission, request shaping, result validation, and continuation policy.
• Capability events belong to their owning seam; tools/*, llm/*, system-prompt/*, fs/*, and subagent/* attach policy and adapters without importing the loop.

Interception Semantics

Waterfall events behave like around-middleware: a listener delegates by calling next(); returning without it vetoes or takes over. Full rule: Cordis waterfall semantics.

Default Loop Lifecycle

The shipped loop drains work from prompt through checkpoint. Every pause is a service call or event available to plugins.

A session is an append-only event log. A turn drains queued input until the model stops asking for tools and no plugin requests continuation. A step is one model request plus the tool executions caused by that response. In the flow below (sequence companion), quoted names are durable session events and event names are extension points.

Startup resolves identity. No id mints <config-id>-session-<uuid>; sessionId resumes or creates; resumeSessionId requires history. Active failures emit agent-loop/config-start-failed(sessionId, error), so front doors reject work; teardown stays silent.

Turn Flow

choose declarative identity and fresh/resume path
  -> prepare private session + agent.ctx -> await unpublished setup
  -> enter session + agent -> session/created -> agent/created
  -> enable driving -> agent/session-start(source) -> start driver
forever:
  wait for queued messages
  emit agent/status(running)
  TURN:
    'turn/start'
    each queued message -> agent/prompt-submit
      allowed prompt -> 'user/message' plus injected context
    every prompt blocked -> 'turn/end'(rejected)
    STEP loop:
      drain steering
      assemble system prompt and tool schemas
      agent/session-prefix (first step)
      agent/pre-step
      snapshot the derived messages (the reconstruction boundary)
      'step/start'
      agent/request (config only) -> log request/header -> llm/stream (frozen)
      on final adapter-path or terminal in-band failure:
        'step/end'
        agent/request-error(original error, consecutive retry attempt, signal)
        retry in the next numbered step or preserve the original error
      otherwise:
        'assistant/chunk'
        agent/step-result
        'assistant/message' (transformed content or empty success anchor after step-result rejection)
        schedule tool calls by ctx.tools.executionMode:
          exclusive -> one-call barrier
          parallel -> rolling pool, <= maxParallelToolCalls in flight; reclassify before start
          each start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute
          each model-order result -> ordered tools/post-execute -> 'tool/result'
        append accepted tool-batch context after all recorded results, then steering
        agent/post-step
        'step/end'
        agent/turn-continuation
        agent/turn-stop (terminal policy)
        stop unless tools or continuation policy ask for another step
    'turn/end'
    checkpoint persistence and notify idle/running status

Each step assembles ordered prompt sections, tool schemas, and {{name}} variables; unknown or valueless references fail the turn. dsh-system-prompt owns the harness identity and default persona, which an agent scope may shadow. The loop supplies model and cwd (prompt ownership).

Tool-time context—including async agent.inject() notices and post-tool additionalContexts—settles, then follows recorded results. Steering drains before agent/post-step, which observes durable output, results, context, and steering before signal closure. Leftovers become queued input. Terminal agent/turn-stop runs after continuation and steering folding, stays authoritative through turn close and flush, and discards later steering but preserves queued prompts.

dsh-compact-basic handles pressure and canonical overflow at checkpoints; retry requires a balanced surface replacement (decision).

Failure Boundaries

The turn is the containment boundary. Final adapter-path and terminal in-band failures close the step before agent/request-error; retry opens a numbered step; otherwise, the provider error survives. Attempts reset on success.

Other failures use agent/error. Cancellation and disposal beat recovery; undispatched model tool calls receive synthetic tool/call and ABORTED result pairs before turn/end. cancel() clears queues and aborts active work; disposal awaits quiescence before unregistering.

Every session event is turn-enclosed. Reloading preserves an interrupted tail and closes it with a synthetic interrupted turn end. Failures after durable turn close report only through agent/error because no safe in-turn position remains. Each turn has one TurnEndReason; TurnEndReasonMap owns the variants.

Agent Handles

ctx.agents owns live agents and returns AgentHandle { agent, dispose() }. Plugins drive Agent through send(), steer(), inject(), cancel(), and whenIdle(). The caller fiber and factory provider structurally co-own programmatic lifecycles; the consumer handle is the only other teardown capability. All owners await one disposer.

Agent Scope

Every live agent owns a scoped agent.ctx. Its registrations shadow globals, receive only that agent's dispatches, and unwind with it; async effects such as background-task cleanup are awaited. CreateAgentOptions.setup(agentCtx) composes the scope before publication. Typed resolvers derive carrier checks from merged Events signatures and scopeTarget (semantic gates). See agent scope and subagent composition controls. AgentLoop runs drivers inside ctx.agents.withInitiator(); private orchestration derives agent.session; other identities stay explicit (decision).

State

Session Log

The session log is the source of truth. deriveMessages() projects session events into the Message[] sent to the model; raw assistant/chunk events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream.

Model-visible ⟺ logged: the log reconstructs every request — messages at step/start fronted by the header's session prefix, headers by folding request/header — and dev invariants assert this (reconstructability).

Durability is a plugin concern. Persistence backends buffer synchronous session/event notifications and the loop awaits a turn-end checkpoint before moving on. The SessionPersistence seam stores SessionEvent directly, with metadata in SessionHeader; JSONL and SQLite share one contract suite.

Model Content

Messages contain typed blocks (text, reasoning, tool-call, tool-result) derived from merge-extensible ContentBlockMap; the same pattern types MessageSource, FinishReason, TurnTrigger, and TurnEndReason. New block types coordinate adapters, UI bridges, compaction pricing, token metering, and persistence as one repo-wide contract; replay measurement types live in token-meter.md.

Streaming uses raw chunks (block-start through finish) and BlockAssembler. The loop logs and assembles chunks, storing provider/model provenance plus replay state. An LlmAdapter implements stream(), registers provider routes, and may expose selector metadata; it resolves and validates model ids. Replay state reaches targets only when both routes map to one adapter instance, which owns validation and conversion. The contract lives in llm-streaming.md.

Extension And Composition

Capability Pattern

A swappable capability usually splits into interface / implementation / consumer: the interface owns its ctx key and events, an implementation registers a backend, and a consumer exposes model behavior through tools or prompts. Bash is the reference; the capability graph shows every family.

Exceptions combine layers deliberately: LLM joins interface and consumer; filesystem wraps providers with policy; web unifies search/fetch registries; skills and subagents use named providers. Subagents spawn fresh, fork a completed-turn prefix, or use ACP children (subagent.md).

dsh-workspace-context composes baselines on agent/session-prefix and appends ctx.fs-discovered nested changes on tools/post-execute; its decision records isolation. dsh-paths owns shared paths.

Bundles And Apps

dsh-agent-spine-demo bundles the default spine (README). dsh-stdio-demo selects dsh-tui for interactive terminals and line-oriented dsh-stdio for pipes; dsh-cli-demo runs one persisted headless turn with format-pure stdout; dsh-acp-demo adds stdout-pure ACP over JSON-RPC (ui/). dsh-jsonrpc-agent boots external cordis.yml; the Python SDK supplies its default only without an explicit config channel and drives dsh-jsonrpc over line-delimited JSON-RPC (Python SDK). Deployments remain thin leaves with swappable backends and optional product tools (examples/, runnable wirings, graph atlas).

Where New Behavior Goes

New behavior should attach to a documented extension point; changing the shipped loop requires updating this map.

Goal	Mechanism
Add a model provider	register an adapter on ctx.llm
Add a model-facing capability	register a tool on ctx.tools; schemas flow into prompt assembly
Add command execution	implement and register a ctx.bash backend
Add persistent terminal execution	register a ctx.pty backend and dsh-tool-pty
Add a long-running/background capability	register the work on ctx.tasks; the generic task_* tools collect/stop it
Add filesystem access or policy	implement a ctx.fs provider or listen on fs/* policy events
Confine spawned processes	a ctx.sandbox backend; consumers wrap their argv before spawning
Intercept prompts, requests, model completion/failure, tool use, or continuation	listen on the relevant agent/* or tools/* event; use serial agent/turn-stop for a monotonic terminal stop
Add a session-stable request prefix outside history	compose it on agent/session-prefix, once per loop instance; logged on the request header
Add UI or editor integration	drive ctx.agents and render from session/event
Add durable session state	add a SessionEventMap member and render/replay from the log
Fork a live session	use ctx.sessions.fork(source, boundary?, childSessionId?)
Scope a tool, prompt section, or listener to ONE agent	register it through that agent's agent.ctx (see Agent Scope)

The extension cookbook carries plugin skeletons and the feature-to-seam map; step-by-step guides cover packages, tools, LLM adapters, and vendored packages.

Quick Reference

• Domain terms in the glossary
• Type definitions in core-data-structures/
• Exact event and service signatures in events
• services catalogs
• package contracts in the package map
• Agent Notes