deepseek-harness/docs/glossary.md

Glossary

English | 中文

Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per concept. Terms link to their entries with standard Markdown anchors; implementation detail stays in package READMEs and Agent Notes.

capability-seam

• seam — a swappable capability packaged as a trio: a Service Definition (the Cordis Service that owns its ctx.<key> and vocabulary types — an abstract class such as BashExecutor, or a concrete registry such as WebService, never a TypeScript interface), one or more Service providers (the implementation plugins that register a backend), and a Consumer (the model- or plugin-facing surface that injects the service). packages/bash is the canonical example: dsh-bash (Service Definition), dsh-bash-local / dsh-bash-sandbox (providers), dsh-tool-bash (consumer). The seam is all three together; the interface package alone is the Service Definition, one member — calling it "the seam" is the misuse this entry names. Fold roles only when they are genuinely one concern (dsh-llm folds the Service Definition and consumer); never split preemptively.

agent-scope

• scope — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either global (visible to every agent) or scoped (owned by exactly one scope key). Two levels, flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with lineage data, never scope structure.
• scope key — the opaque identity a scope is keyed by, compared by object identity. The harness convention: a live agent is the key of its own scope.
• agent context (agent.ctx) — the agent's scoped context; registrations through it are scope-visible AND scope-lifetime (one fact drives both), and listeners on it participate in that agent's scope-filtered dispatches. Registry-subject events may remain deliberately unfiltered under their own event contracts.
• scope carrier — the thisArg a scope-filtered dispatch carries (built by scopeTarget); its filter admits untagged listeners plus the subject's own. A subject-less carrier (no key) admits untagged listeners only.
• scoped dispatch — the rule: an event about one agent's activity dispatches with that agent's carrier. Events about a registry itself (a tool was added) are registry-subject and stay unfiltered.
• shadowing — most-specific-wins name resolution: a scoped tool/section/variable replaces its same-named global twin for that scope alone. The per-agent persona and per-agent tool-variant mechanism.
• restriction / scope-local registration — a restriction (tools.restrict) filters the GLOBAL tool surface for one scope (compose by intersection); scope-local registrations are merged after that filter. A filtered-away global tool is absent from the prompt AND refuses execution, indistinguishably from a nonexistent one.
• setup window — the creation slot where a creator composes an agent's scoped world (CreateAgentOptions.setup): after the scope and agent object exist but before the agent or session is published, agent/session-start fires, or the first prompt is assembled. Setup registers; it never drives the agent.
• lineage — parent/child facts carried as data (parentSession, durable delegationDepth, runtime subagentDepth); never affects visibility.

goal

• goal — one durable completion objective attached to an existing session, with a revisioned active / paused / blocked / complete phase and a goal-round cap; blocked retains a policy code and explanation. A goal is state, not a scheduler or a separate conversation; the session log remains its source of truth.
• goal round — one continuation cycle admitted for the current goal. The same-session driver materializes a goal round as one goal-sourced turn, which can contain zero or more steps; unrelated human turns in the same session do not consume the goal-round cap.
• goal activation — process-local permission for a continuation consumer to admit another goal round. Activation is either armed or disarmed; it is deliberately absent from durable replay, so resume and fork require a later human-authorized resume mutation through /goal or the model tool before automatic work.

human command

• human command — a slash-prefixed instruction interpreted and executed by a human-facing adapter through ctx.commands, without becoming a model message. It is distinct from a model-facing tool and from shell command execution through ctx.bash.
• command plane — discovery, parsing, dispatch, cancellation, and result rendering owned by UI adapters and command plugins. Command output is UI state unless the handler separately mutates a durable domain.
• goal command — the /goal human command contributed by dsh-command-goal; it observes or mutates the current goal directly while the goal domain owns every durable, model-visible record.

loop hierarchy

• turn — one drain of admitted input in a session, ending after the model and its tools stop or a terminal policy intervenes.
• step — one model request plus the tool executions caused by its response; a turn contains zero or more steps.
• round — an outer policy iteration containing a turn, such as a goal round or one fresh-agent Ralph attempt. Round counters belong to that policy and do not count every turn in a session.

Ralph

• Ralph loop — one foreground fresh-agent workflow run toward an immutable objective. It is a model-facing tool policy composed from workflow and subagent primitives, not a same-session goal, agent-loop mode, scheduler, or generic workflow-script feature.
• Ralph round — one fresh child session in a Ralph loop. The child receives no parent or prior-child conversation seed; the shared workspace and one bounded Ralph handoff carry cross-round state.
• Ralph handoff — the normalized bounded structured report passed from one continuing Ralph round to the next, containing status, summary, evidence, next steps, and blocker text. It supplements the shared workspace rather than replacing it as authority.