dsh-gpu

GPU-aware execution layer for DeepSeek Harness (dsh). Out-of-tree plugin; no harness patches required.

Agents get three tools — gpu_status, gpu_exec, gpu_run_bg — plus an optional per-step GPU context line. Cards are selected automatically (freest first) with CUDA_VISIBLE_DEVICES set in the command environment; pin a card explicitly when you care.

8 GPU(s), free: [0,1,2,3,4,5,6,7]
GPU0 Tesla V100-SXM2-32GB: 4264/32768MiB 0%util 40C
...
[gpus 1 — GPU 1 (auto: freest 1)] exit 0

How it works

• gpu_status — one query, every device: memory used/total, SM utilization, temperature, and a free/busy verdict. A device is busy at or above 80% memory used or 50% utilization (both configurable).
• gpu_exec — one-shot command with a selected card: CUDA_VISIBLE_DEVICES=<freest> is passed through the mounted ctx.shell executor's environment. Auto-select or pin gpuIndex; select count cards for multi-GPU commands.
• gpu_run_bg — long-running GPU jobs (training, inference servers, benchmarks) register as a gpu job in ctx.jobs: returns a job id immediately, read with job_output, stop with job_kill.
• Per-step context (optional, on by default) — injects a one-line GPU snapshot into eligible steps (the time-context pattern), rate-limited to one sample per minute.

All execution rides the mounted shell executor. Local host, or any remote execution world (e.g. an SSH provider plugin) — dsh-gpu doesn't know or care where the GPUs are; it queries and launches through the same seam the bash tool uses.

Install

dsh-gpu is an out-of-tree bundle plugin. Install and activate it in a profile with the official plugin command:

dsh plugin --profile <name> add dsh-gpu

The package's bundled cordis.patch.yml registers the plugin automatically. To override its configuration, add an entry with the same id to the profile's cordis.patch.yml:

- insert:
    - id: gpu
      name: dsh-gpu
      config:
        stepContext: true

Load order note: place it after your execution-world plugins (e.g. an SSH provider) so the shell seam it queries is the one you intend.

Configuration

- id: gpu
  name: dsh-gpu
  config:
    stepContext: true      # per-step GPU snapshot line (default true)
    refreshIntervalMs: 60000  # min spacing between injected snapshots
    queryTimeoutMs: 10000     # nvidia-smi timeout
    busyMemoryPct: 80         # >= this % memory used => busy
    busyUtilPct: 50           # >= this % SM util => busy

Notes & gotchas

• nvidia-smi ignores CUDA_VISIBLE_DEVICES — it always reports physical indices. gpu_exec selection still works as intended for CUDA programs; just don't use nvidia-smi output inside gpu_exec to verify the pinning.
• Selection is advisory, not a reservation: two concurrent agents can still pick the same card. For exclusive claims, pin gpuIndex from a gpu_status read in the same step.
• gpu_run_bg requires the jobs service in the composition (@deepseek-ai/dsh-jobs + @deepseek-ai/dsh-tool-jobs), the same dependency background bash has.
• Hosts without NVIDIA GPUs: gpu_status reports a clean no-gpu result instead of failing.

Development

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest unit and plugin lifecycle tests
pnpm build       # tsdown -> lib/
pnpm check:package  # publint + Are the Types Wrong
node tests/live-v100.mjs   # optional live probe (edit SSH target first)

Test fixtures are recorded from a live 8× Tesla V100-SXM2-32GB host (including one occupied card) — no mocking of nvidia-smi output formats.

License

MIT