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

/**
 * The sandbox mode this executor applies by default, or `undefined` when it
 * does not sandbox commands.
 * @returns the configured default sandbox mode, when supported.
 */
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)

/**
 * Apply implementation-owned defaults and caps to a request before execution.
 * @param request - the caller's request; omitted fields get this
 *   implementation's defaults, capped fields are clamped.
 * @returns the fully-specified spec to hand to {@link run}/{@link start}.
 */
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)

/**
 * Run a command in the foreground; resolves when it finishes.
 * @param spec - a resolved spec from {@link resolve}, never a raw request.
 * @returns the outcome; nonzero exits, timeout kills, and abort kills
 *   resolve with a descriptive result rather than reject.
 */
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)

/**
 * Start a background process and return its handle immediately.
 * @param spec - a resolved spec from {@link resolve}, never a raw request.
 * @returns the live process handle (reads, kill, quiescence promise).
 */
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