DSH plugin user commands: DeepSeek Harness ctx.commands

To give users a slash command, a DSH plugin goes to a registry entirely separate from tools: the user command service provided by dsh-commands lets interactive adapters discover plugin-owned commands and execute them against the exact agent, creating no model message (source). This article covers the CommandDefinition field rules, the log-only command lifecycle, scoped shadowing, and the ctx.commands API; event dispatch modes are in DSH plugin events, and tool registration and contracts are in the tool execute contract.

CommandDefinition in a DSH plugin: what to fill in to register a user command

CommandDefinition is the plugin-owned registration definition, and the registry validates and freezes an effective definition detached from the original registered object (source). The fields:

1. name — a lowercase command name without the leading slash. To offer /plan, register plan.
2. description — a human-readable summary used in discovery UI.
3. input (optional) — a CommandInputDescriptor that currently carries only hint: a placeholder shown before the user supplies free-form input, advertised to capable clients. Command availability is decided by plugin composition — every adapter consuming the registry sees all effective definitions.
4. recordInput (optional, defaults to true) — whether command/run records rawInput. When the command's domain event already owns that payload, set it to false to avoid duplicating the payload in the session log.
5. handler — (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>, which executes against the receiving agent without sending the command to the model.

Invocation and results in a DSH plugin user command: direct execution without the model

Cancellation is the adapter's job and the adapter passes the exact target agent; results render directly in the UI, not as a tool result or session event (source). The CommandInvocation a handler receives has four fields:

1. commandId — the pairing id already written to this invocation's command/run event.
2. agent — the exact agent whose UI received the command.
3. rawInput — the text right after the registered command name, preserving the separator and trailing whitespace the adapter passed.
4. signal — the cancellation signal owned by the dispatching UI request.

The returned CommandResult is one of two branches: { kind: 'success', text?, sourceEventSeq? } or { kind: 'error', text }. sourceEventSeq is optional and only used on success: when present it points to an earlier non-command event in the receiving session log, and command/done persists the same reference so clients can merge the command lifecycle with that domain projection without parsing text or relying on adjacent lines.

Discovery, scope, and lifecycle logging for DSH plugin user commands

Scope is layered and the lifecycle is log-only (source).

1. Scope and shadowing — definitions on a plain context are global; definitions registered through a commands-injected child of an agent context shadow globals for that agent. ctx.commands.register(definition) returns the exact effect disposer; ctx.commands.list(agent) returns name-sorted immutable CommandDescriptors (handler-free) after scoped shadowing; ctx.commands.find(agent, name) returns the shadow or the global definition.
2. Log-only lifecycle — ctx.commands.execute(agent, line, signal) parses and executes a known command: command/run is appended before the handler is invoked and command/done after settlement (a thrown or aborted handler settles as kind: 'error'). Both are direct log-only appends with no turn wrapping them, drained by persistence at ordinary checkpoints.
3. Admission and failure semantics — admission misses (syntax errors or unknown names) log nothing, because they never entered a handler; a command/run append failure fails the execution loudly, while a command/done append failure on the handler-failure path is contained so the handler's own error stays the reported failure.
4. Parse view — parseCommand() returns a ParsedCommand before registry resolution, so a syntactically valid input may still point to a command that is not currently available.
5. Registry change notification — commands/change is an unfiltered registry notification (a global or scoped change may affect any UI view); observer failures are contained and cannot veto the registry mutation.

Three self-checks when done: is name lowercase with no leading slash; is recordInput set to false when a domain event already carries the payload; and does the handler return a CommandResult directly instead of trying to push the command into a model turn. To find community implementations of command plugins, you can search the DSH Plugin Hub; for how commands differ from tools see the feature-to-mechanism map.