deepseek-harness/website/zh-CN/api/harness/bash.md

ctx.bash

BashExecutor (abstract seam) — provided by @deepseek-ai/dsh-bash.

Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as ctx.bash (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). Implementations must honor these semantics:

• run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
• start returns immediately; no timeout applies to background processes. done settles at process close and never rejects; spawn failures settle as killed with the error on stderr.
• BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
• Disposal kills all running background processes and awaits their exit.

Source

ctx.bash.sandboxMode

get sandboxMode(): SandboxMode | undefined

The sandbox mode this executor applies by default, or undefined when it does not sandbox commands.

Source

ctx.bash.resolve(request)

abstract resolve(request: BashExecRequest): BashExecSpec

Apply implementation-owned defaults and caps to a request before execution.

• request — the caller's request; omitted fields get this implementation's defaults, capped fields are clamped.

Returns the fully-specified spec to hand to run/start.

Source

ctx.bash.run(spec)

abstract run(spec: BashExecSpec): Promise<BashRunResult>

Run a command in the foreground; resolves when it finishes.

• spec — a resolved spec from resolve, never a raw request.

Returns the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject.

Source

ctx.bash.start(spec)

abstract start(spec: BashExecSpec): BashProcess

Start a background process and return its handle immediately.

• spec — a resolved spec from resolve, never a raw request.

Returns the live process handle (reads, kill, quiescence promise).

Source