deepseek-harness/docs/glossary.md

Glossary

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.

FIXME(glossary-completeness): Expand this glossary before the first release so it covers the SDK's other core and capability subsystems, not only agent scope.

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, subagentDepth); never affects visibility.

goal

• goal — one durable completion objective attached to an existing session, with a revisioned lifecycle phase and a goal-round cap. 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 multiple 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.
• command surface — the adapter identity used to filter definitions, such as tui or acp; one scoped definition may shadow a same-named global command for its exact agent.
• 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 one 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.