DSH plugin shell: resolve split, jobs, and sandbox facts
Dropping a ShellExecRequest straight into the executor is the most common way to get shell integration wrong. DSH plugin splits "what the caller wants" from "what the executor actually runs" into two types, with a mandatory resolve() between them. Skip it and foreground and background behavior diverge.
resolve splits request from spec
Requests may omit fields; specs must be complete, and defaults plus caps are all applied in resolve().(source)
ShellExecRequest is the model- or plugin-facing shape: command is required, while workdir, timeoutMs, onExpiry, stdoutMaxBytes, signal, stdin, env, dshEnv, and sandboxPolicy are all optional. ShellExecSpec is the fully resolved spec the executor consumes, with workdir, timeoutMs, onExpiry, and stdoutMaxBytes all mandatory.
The correct tool-layer order is ctx.shell.resolve(request) then execute(spec). That mirrors the repository's "explicit at package boundaries" rule: defaults are not quietly filled in by the executor but completed explicitly at the boundary.
onExpiry defaults to 'kill'. When it resolves to 'none', the resolved timeoutMs arms no timer and is merely echoed into ShellRunResult.timeoutMs. That explains "I set a timeout and nothing got killed": the value exists but does nothing.
DSH_* environment is a harness-owned fact
DSH_* variables are not ordinary environment variables; the framework rebuilds them and inherited values must not pollute them.(source)
The model-facing bash tool collects these through ctx.shellEnv and passes them via ShellExecRequest.dshEnv; the subprocess service strips inherited DSH_* names before merging the current snapshot. An unavailable current fact therefore never inherits a stale value from the harness process.
The DshEnvironmentKey and DshEnvironment vocabulary belongs to the subprocess seam and is re-exported by dsh-shell. The registry itself is narrow: register(contributor) adds a contributor (unique name and keys, built-in keys reserved, disposed with the calling fiber), collect(execution) produces one trusted snapshot per execution, and list() enumerates declarations without running resolvers.
stdin and env are trusted in-process plugin inputs and are not exposed by dsh-tool-bash. The local executor clears credentials from the environment before merging caller-provided env; dshEnv merges last, so env entries can never override managed facts. When the model needs stdin, use a heredoc or a pipe rather than relying on that field.
Foreground results: four orthogonal fields
Timeout, cancellation, exit code, and signal are reported independently, never collapsed into one boolean.(source)
ShellRunResult is shaped to prevent misreading:
exitCode— the exit code, ornullwhen preparation expired or the process died from a signal;signal— the terminating signal, ornullwhen none was reported;timedOut—truewhen the executor's own timeout was the first cause;aborted—truewhen the caller'sAbortSignalwas the first cause;timeoutMs— the timeout actually in effect for this run, after defaults and caps;stdout/stderr— twoCollectedOutputstreams;sandbox— sandbox facts, absent when unsandboxed.
timedOut and aborted are mutually exclusive: one fused deadline drives both the executor timeout and caller cancellation, and whichever wins the race before the process closes is reported as the first cause. But timedOut and exitCode are not exclusive — a process can time out and exit 0 because it caught the signal. That is what "four orthogonal fields" means.
Each stream is a CollectedOutput: possibly truncated text plus recovery information. On truncation, text is the tail and the full stream spills to a private file. These fields belong to the subprocess seam and are re-exported by dsh-shell.
The background handle has no id and no owner
start() returns a process handle, not a job; job identity is taken over by the runtime above.(source)
start() returns a handle after asynchronous launch preparation completes; cancellation or preparation failure rejects before publication. The handle has no id or owner — dsh-tool-bash adapts it to the ctx.jobs.start() hook, and the generic runtime owns job identity and lifecycle from then on.
done settles when the underlying process settles and never rejects; a subprocess-provider rejection yields a process with status killed and the non-declaring-phase error written to stderr. Output remains readable after settlement, and sandbox facts are written before done completes.
The three reading-related methods have distinct boundaries:
readOutput()— consuming incremental reads that never redeliver; on data loss it setslossyand suppliesstdoutSpillPathorstderrSpillPath;observed— non-consuming offset reads, so an independent observer never steals bytes fromreadOutputand can still read the provider failure explanation left on stderr by a rejected spawn;kill()— terminates the provider-managed scope, returnsfalsewhen already finished, and is idempotent.
Foreground and background differ by what the caller waits for
"Foreground" is not a spawn property; it is where the caller waits.(source)
The reference is direct: callers that await ShellExecution.result run foreground; callers that keep the handle run background. A caller waiting briefly uses onExpiry: 'none' with its own deadline, and the handle stays valid after the caller stops waiting.
result rejects only on infrastructure failure. Non-zero exits, timeout kills, and cancellation kills all resolve with a descriptive result carrying the first cause and the echoed timeoutMs. So "the command failed" must not be caught with try/catch — read exitCode and timedOut instead.
One lifecycle fact is worth remembering: still-running processes are stopped and awaited when their owning composition tears down. Alongside the subprocess seam that boundary is ctx.subprocess disposal, so reloading only the executor does not kill processes.
Sandbox facts and rejection classes
Sandbox information is reported independently of exit status; rejection and failure are separate readings.(source)
A sandboxed executor exposes its configured mode fallback through sandboxMode. The tool layer asks @deepseek-ai/dsh-sandbox-policy to resolve each call's persistent sandbox/mode override plus the immutable cwd into ShellExecRequest.sandboxPolicy; user-approved, strictly looser calls replace only the mode. The mode governs file effects only.
ShellSandboxInfo reports four things: the mode actually run, whether file operations were denied, enforcement completeness, and whether the sandbox runner had already failed before the command ran (runnerFailed).
Keep the two failure paths apart: foreground execution throws SANDBOX_UNAVAILABLE when a restricted mode has no usable backend, while an already-finished background process can only report runnerFailed through the facts channel. The model receives denial and runner facts in the result, learning the effective mode only when the denial flag names it.
Verification: one command, both modes
Verification must cover field orthogonality and the differing read semantics of the two handles.(source)
- Resolve a request supplying only
commandand assertworkdir,timeoutMs,onExpiry, andstdoutMaxBytesare filled in. - Run a foreground command that exceeds
timeoutMsand asserttimedOutis true,exitCodeisnull, and output is a truncated tail. - Run a foreground command that catches the signal and exits 0 and assert
timedOutandexitCodeare both present. - Start a background command emitting continuously, call
readOutput()twice, and assert the second call omits the first call's bytes. - Run a sandbox-denied command in the background and assert
deniedis true, while the foreground equivalent throwsSANDBOX_UNAVAILABLE. - Reload only the executor and assert background processes keep running; dispose
ctx.subprocessand assert they are stopped and awaited.
If step 3 does not show both values, the implementation merged timeout and exit code into one state, hiding the fact that the process handled the signal itself.
For the division of labor across shell and subprocess, see the shell and subprocess seam; for spawn spec details see subprocess spawn spec.
One line to close: a request becomes a spec only through resolve, DSH_* is rebuilt by the framework, result fields report orthogonally, background handles carry no identity, and sandbox denial must be read apart from command failure.
FAQ
No. DSH plugin requires resolve first. DSH plugin's execute takes only a fully resolved ShellExecSpec, with defaults and caps filled in by resolve, so a tool layer must not skip that step.
No. DSH plugin reports fields orthogonally. DSH plugin allows a process to time out and still exit 0, for example after catching the signal, so timedOut and exitCode are independent facts.
No. DSH plugin's ShellProcess has neither id nor owner. DSH plugin adapts it to ctx.jobs.start() through dsh-tool-bash, after which job identity and lifecycle belong to the generic runtime.
No. DSH plugin's readOutput is consuming: consecutive reads never redeliver bytes. If truncation dropped unread bytes, DSH plugin sets lossy and provides a usable spill file path.
Related Terms
- ShellExecRequest
- ShellExecRequest is the model- or plugin-facing request whose workdir, timeoutMs, and stdoutMaxBytes are optional and filled by resolve.— packages/shell/shell/src/types.ts
- ShellExecSpec
- ShellExecSpec is the fully resolved spec the executor uses, with workdir, timeoutMs, onExpiry, and stdoutMaxBytes all required.— packages/shell/shell/src/types.ts
- ShellRunResult
- ShellRunResult is the foreground outcome, reporting exitCode, signal, timedOut, aborted, timeoutMs, and two output streams orthogonally.— packages/shell/shell/src/types.ts
- ShellProcess
- ShellProcess is the background handle with status, exit facts, done, readOutput, observed, and kill, but no id or owner.— packages/shell/shell/src/types.ts
Sources
- DeepSeek Harness reference - Shell executor· deepseek-ai
- packages/shell/shell/src/types.ts· deepseek-ai