DeepSeek Harness

DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI. It is an agent runtime plus a CLI (dsh) and a Web UI for driving LLM agents: chat, tool calls, subagents, filesystem, shell, and web workflows. It is currently a _developer preview_ and is iterating rapidly, with explicit compatibility-breaking changes.

The defining idea is that there is no privileged core. The README states the architecture plainly: everything is a plugin. That is enforced by the underlying framework, Cordis, whose design is described in _A Programming Paradigm for Spatiotemporal Composability_. In Cordis, a plugin contributes services, typed events, and reversible effects to a shared context. dsh mounts its capabilities as plugins into that context, so the model adapter, the tool registry, the session log, and even the concrete agent loop are replaceable from configuration rather than hard-coded.

You do not patch a core. You extend dsh by mounting a plugin beside the others. Because a registration is an effect, it unwinds when its plugin unloads — which is what makes any of it, including the loop, swappable at runtime.

A running dsh is a plugin tree composed at boot from ordered layers. A profile is a named composition (e.g. web, headless) that lists the bundles it stacks and holds the user's cordis.patch.yml. A bundle is a distribution format for Cordis config rows and the code they mount. Each declares itself in its own package.json under a dsh field: dsh.profile lists a profile's bundles and dsh.bundle points at a bundle's patch file. dsh-base is the first layer of every profile; dsh-web-app adds the browser application; dsh-headless adds a one-shot serverless runner.

The core runtime lives in a small set of packages/core/* packages. Each owns a capability and exposes it under a shared-context (ctx) key: core/session (the append-only SessionEvent log, ctx.sessions), core/system-prompt (prompt-section and tool-schema assembly, ctx.systemPrompt), core/tools (the scoped tool registry and guarded execution pipeline, ctx.tools), core/agent (the Agent interface and live registry, ctx.agents), core/agent-loop (the concrete default driver, ctx.agentLoop), and llm/llm (message and stream vocabulary plus the adapter seam, ctx.llm). The one package with real loop logic is core/agent-loop; everything else hangs off the seams.

Work flows through events in three domains. Session events are durable facts appended to the log and broadcast over session/event. Agent events (agent/*) carry a live Agent — inbox, step, status, request, validation, continuation. Capability events attach policy and adapters to a seam (fs/*, tools/*, telemetry/*) without importing the loop. A turn is zero or more steps; a step is one model request plus the tools it calls. The durable spine of one step is: assemble prompt + tool schemas, stream from ctx.llm, run every tool call through tools/pre-execute → tools/execute → tools/post-execute, and append the results to the log.

The CLI is apps/cli (the dsh bin). dsh web boots the web profile; the boot path composes the profile, mounts the plugin tree, and activates it. Running dsh --profile web --dump-config prints the exact config tree your machine boots, and any printed row can be replaced by your own patch.