deepseek-harness/docs/core-data-structures/commands.md

Human Commands

English | 中文

The human-command seam of dsh-commands. Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The command Agent Note owns dispatch and lifecycle rationale; the package README owns composition and limitations.

Source: packages/interaction/commands/src/index.ts

Input metadata

The seam exposes one optional unstructured-input hint. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.

/** Immutable metadata for a command's optional unstructured input. */
interface CommandInputDescriptor {
  /** Placeholder shown before the user supplies free-form input. */
  readonly hint: string
}

Definition

CommandDefinition is the plugin-authored registration. The registry validates and freezes a detached effective definition.

/** Plugin-owned command registration. */
interface CommandDefinition {
  /** Lowercase command name without the leading slash. */
  readonly name: string
  /** Human-readable summary used in discovery UI. */
  readonly description: string
  /** Optional free-form input hint advertised to capable clients. */
  readonly input?: CommandInputDescriptor
  /**
   * Whether `command/run` records `rawInput`. Defaults to true. A command
   * whose domain event owns the payload sets this false to avoid duplicating
   * that payload in the session log.
   */
  readonly recordInput?: boolean
  /** Execute against the receiving agent without sending the command to the model. */
  readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
}

Invocation and result

The adapter owns cancellation and passes the exact target agent. rawInput begins immediately after the parsed name and retains the adapter-delivered separator and suffix. Results are direct UI outcomes, not tool results or session events.

/** Invocation passed to one registered command handler. */
interface CommandInvocation {
  /** Exact agent whose human-facing surface received the command. */
  readonly agent: Agent
  /** Exact text following the registered command name, including separator whitespace. */
  readonly rawInput: string
  /** Cancellation signal owned by the dispatching UI request. */
  readonly signal: AbortSignal
}

/** Expected command outcome rendered directly by the dispatching UI. */
type CommandResult =
  | {
    readonly kind: 'success'
    readonly text?: string
    /** Earlier authoritative domain event that owns a richer presentation. */
    readonly sourceEventSeq?: number
  }
  | { readonly kind: 'error'; readonly text: string }

sourceEventSeq is optional and success-only. When present, it names an earlier non-command event in the receiving session log; command/done persists the same reference so a client can combine the command lifecycle with that domain projection without parsing text or relying on adjacent rows.

Discovery and parsing views

Adapters receive handler-free immutable descriptors after scope resolution. parseCommand() returns ParsedCommand before registry resolution; syntax-valid input can still name an unavailable command.

/** Handler-free immutable command view returned to UI adapters. */
interface CommandDescriptor {
  /** Lowercase command name without the leading slash. */
  readonly name: string
  /** Human-readable summary used in discovery UI. */
  readonly description: string
  /** Optional free-form input hint advertised to capable clients. */
  readonly input?: CommandInputDescriptor
}

/** Syntactically valid slash command before registry resolution. */
interface ParsedCommand {
  /** Lowercase command name without the leading slash. */
  readonly name: string
  /** Exact text following the command name. */
  readonly rawInput: string
}