DeepSeek Harness Glossary: Plugin, Bundle, Profile, Service, and More
A working glossary of DeepSeek Harness terms: plugin, bundle, profile, service, capability seam, turn, step, round, human command, Ralph loop, and more.
DeepSeek-Harness (dsh) reuses some familiar agent-framework vocabulary and invents a few terms of its own. This glossary defines both, in plain language, with a pointer to where each concept is used in practice.
Core building blocks
Plugin — A TypeScript/JavaScript module that exports apply(ctx, config), optionally name, inject (declared service dependencies), and a Config schema. There's no separate manifest file format — a plugin is just code. See DeepSeek Harness Architecture for how far "everything is a plugin" actually extends.
Bundle — An npm package whose package.json declares a dsh.bundle field pointing at a cordis.patch.yml. The bundle is the distribution unit; the patch is the payload. See Profiles and Bundles, Explained.
Profile — A runnable configuration at $DSH_HOME/profiles/<name>/: an ordered list of bundles (dsh.profile.bundles) plus a personal override layer (cordis.patch.yml). web and headless are reserved, auto-bootstrapped names.
Service — A capability one plugin exposes to others, mounted on ctx.<serviceName> (e.g. ctx.tools, ctx.llm, ctx.subagents). Consumers declare a hard dependency with inject: ['tools'], or query optionally with ctx.get('metrics').
Capability seam — The complete unit around one replaceable capability: a Service definition (a Cordis Service abstract class, e.g. ShellExecutor) + one or more Service Providers (concrete implementations) + one or more Consumers (things that inject the service). Example: the shell seam is dsh-shell (definition) + dsh-bash-local / dsh-bash-sandbox (providers) + dsh-tool-bash (consumer). It's a finer-grained modeling unit than "plugin" — this is the concept behind Cordis Explained.
cordis.patch.yml — A YAML array of entries that either insert new rows into the plugin tree or override an existing row's config by id. Overrides replace the target row's config wholesale rather than deep-merging it — see Configuration Guide for the merge order across bundle, profile, machine, and --patch layers.
Session and execution vocabulary
Turn — One full cycle of a session digesting a submitted input: the model and its tools cycle back and forth until the model stops or an interrupt policy cuts it off.
Step — One model request plus whatever tool execution it triggers. A turn contains zero or more steps.
Round — An outer-loop policy iteration above turn/step — a goal round, or one attempt in a Ralph loop.
Human command — A slash-prefixed instruction (/xxx) interpreted by ctx.commands. It never becomes a model-facing message — distinct from both a model-facing "tool" and a raw shell command.
Goal — A persistent completion objective attached to an existing session, with four states (active / paused / blocked / complete) and a round-count cap. blocked carries a policy code plus explanation. Implemented by the dsh-goal plugin (ctx.goal), with /goal as its human-command entry point.
Ralph loop — A workflow pattern where each round is a brand-new child session with no inherited conversation history from the parent or the previous round. State carries across rounds only through a shared workspace plus a bounded, structured "Ralph handoff" report (status / summary / evidence / next steps / blocker). It's a model-side tool strategy, not a same-session goal and not a general-purpose workflow-engine feature.
Code Mode — One of the two tool-invocation strategies selectable via DSH_TOOLS_MODE: the model writes code that calls tools programmatically, instead of issuing native structured tool calls. DSH_TOOLS_MODE=native | code | both selects between them; any other value fails startup. See DeepSeek Harness CLI Cheat Sheet.
Access control vocabulary
Sandbox mode — One of three tiers: read-only (no writes), workspace-write (writes confined to the workspace root and platform temp dirs — the default for new sessions), danger-full-access (no isolation at all).
Permission preset — A named pairing of sandbox mode + approval policy, surfaced to clients as a dropdown option. The default table has two: workspace-write (that sandbox mode + ask approval) and danger-full-access (that sandbox mode + never approval, i.e. it never asks). Custom presets can be added; custom itself is a reserved name.
Agent-scope — The isolation mechanism for what each agent can see: a registration (a tool, a prompt fragment, a variable, a restriction) is either global (visible to every agent) or scoped (visible only to one). Sub-agents do not inherit their parent's scope — lineage data like parentSession and delegationDepth is tracked separately, not expressed through scope structure.
Full detail on sandbox backends and enforcement strength lives in DeepSeek Harness Permissions and Sandboxing.
MCP and naming
MCP tool naming — Tools exposed through @deepseek-ai/dsh-mcp-client are surfaced to the model as mcp__<serverName>__<rawName>, normalized to DeepSeek's function-name rules (64 characters, [A-Za-z0-9_-]); collisions get a 12-hex-digit hash suffix keyed on (serverName, rawName). This is the same server-qualified naming shape used by Claude Code and Codex.
Subagent providers — dsh's delegation layer (ctx.subagents) is a named provider registry, not a single implementation. Known providers include in-process spawn/fork, ACP (a spawned child process driven over Agent Client Protocol), and — notably — delegation to Codex or Claude Code themselves. Providers declare which optional capabilities they support: outputSchema, depthLimit, toolFilter, persona.
Framework vocabulary
Fiber (state machine) — The lifecycle every plugin instance moves through: PENDING → LOADING → ACTIVE, with a FAILED branch out of LOADING, and ACTIVE → UNLOADING → DISPOSED on teardown. A plugin that declares inject dependencies waits in PENDING/LOADING until those services exist, and unloads automatically if a dependency disappears.
ctx.effect() — The recommended pattern for registering a resource that needs explicit cleanup (a timer, a network connection) inside a plugin's apply function. The cleanup callback you return runs automatically when the plugin unloads — you don't need to hand-write a separate dispose path for it.
Isolate — A cordis.yml mechanism for giving a group of plugins its own independent instance of a shared service, rather than all sharing the process-wide default — useful when, say, two plugin groups need a Bash executor with different timeout settings.
Quick reference table
| Term | One-liner |
|---|---|
| Plugin | A code module exporting apply(); no separate manifest |
| Bundle | An npm package declaring dsh.bundle, distributing a patch |
| Profile | A runnable config directory: ordered bundles + override patch |
| Service | A capability mounted on ctx.<name>, injectable by other plugins |
| Capability seam | Service definition + providers + consumers, as one modeling unit |
| Turn / Step / Round | Session digest cycle / one model+tool exchange / outer policy iteration |
| Human command | A /xxx instruction that never becomes a model message |
| Goal | A persistent, stateful objective attached to a session |
| Ralph loop | Fresh-session-per-round workflow with a structured handoff report |
| Code Mode | Model writes code to call tools, instead of native tool calls |
| Sandbox mode | read-only / workspace-write / danger-full-access |
| Permission preset | Named sandbox-mode + approval-policy pairing |
| Agent-scope | global vs. scoped visibility for a registration |
FAQ
Is "turn" the same as "session"?
No. A session is the whole persistent conversation/task container; a turn is one cycle of digesting a single submitted input within that session. A session can contain many turns.
Does "capability seam" mean the same thing as "plugin"?
Not exactly — a plugin is a distribution/loading unit, while a capability seam is a finer-grained model: one service definition, its provider implementations, and its consumers, which may span more than one plugin.
Is Ralph loop the same thing as a "goal"?
No — a goal is state tracked within a single continuing session; a Ralph loop deliberately starts each round as a brand-new session with no inherited history, coordinating only through the workspace and a handoff report.
Where does "agent-scope" come from — is it the same as sandboxing?
Different layer. Sandbox mode controls what the OS-level execution environment permits (file writes, network). Agent-scope controls which registrations (tools, prompt fragments) a given agent instance can even see, independent of sandboxing.
Next steps
For the microkernel picture this vocabulary describes, read DeepSeek Harness Architecture: What "Everything Is a Plugin" Actually Means, and for the framework underneath dsh itself, Cordis Explained. Browse plugin examples that exercise several of these terms directly in the full catalog or Development & Runtime.