README.md 11 KB
description: "The subprocess service (ctx.subprocess) for composition authors and capability consumers starting, observing, and terminating managed child processes and terminal sessions."
kind: "package-reference"
@deepseek-ai/dsh-subprocess
English | 中文
Summary
Any composition that runs child processes can start a fully specified child process or a real terminal session through ctx.subprocess, receive a live handle with streams and direct exit facts, then terminate and wait for the provider-managed range. The service provides executable lookup, the shared environment scrub, and bounded output capture, while every default — argv, deadlines, shell semantics — stays explicit on the request, so the consuming capability seams decide what a process means. A composition mounts one provider implementation (such as dsh-subprocess-local) that registers the service; the seam package itself is an abstract contract, not a loadable plugin. Nothing here reaches a model directly: process output and lifecycle are rendered by the consuming tools.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount a subprocess provider in any composition that must run child processes, and call ctx.subprocess from the capability that owns the command. The common path is explicit: resolve the executable, spawn with a fully specified request, read the output you asked for, and terminate the managed range when the work is done.
Mounting the service
One provider registers ctx.subprocess per composition; load it beside the consumers that spawn through it — the bash executors, the LSP host, the PTY shell backend, or an out-of-process subagent backend. Loading a second provider fails loudly (one service per context, cordis standard).
- name: '@deepseek-ai/dsh-subprocess-local'
- name: '@deepseek-ai/dsh-bash-local'
Starting a managed process
The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. Target and managed-range identities remain provider-private. done resolves with the direct command's exit facts (exitCode and signal) and rejects for spawn or provider failures; collected output stays readable after exit.
const executable = await ctx.subprocess.resolveExecutable('bash')
const handle = ctx.subprocess.spawn({
argv: [executable, '-c', 'echo hello'],
cwd: '/workspace',
stdio: { stdin: 'ignore', stdout: { maxBytes: 64 * 1024 }, stderr: 'inherit' },
graceMs: 5000,
})
const { exitCode, signal } = await handle.done
const output = handle.collected.stdout?.readFrom(0)
Choosing how output is delivered
'pipe'hands you the raw stream for your own protocol framing — JSON-RPC for the LSP host, ndjson for the ACP backend.'inherit'lets the child write to the parent's own stream, for pass-through diagnostics.- A collect object buffers a bounded in-memory tail; add a
spillcap and the complete stream is also recoverable from a spill file.
Reads are offset-based and non-consuming: a background reader and a final batch read can share one stream without stealing each other's bytes.
Managing process lifetime
Termination and waiting use one provider-managed range. terminate() starts the provider's documented procedure, is idempotent, and becomes a no-op after that range is empty; the request's abort signal starts the same procedure. waitForExit() observes the same range and resolves only after the provider proves it quiescent, so direct command completion does not hide a surviving descendant. It rejects when the selected owner can no longer prove quiescence. Providers document their native owners and weaker fallbacks; callers own deadlines, teardown ladders, and cause classification.
Running a terminal session
For interactive programs, spawnTerminal allocates a real PTY: write text, read UTF-8 output, inspect and signal the current foreground process group, and await one terminate() that settles every session member the provider can still observe. Readiness, scrollback, and prompt policy stay with the PTY consumer.
Environment every child starts from
Children never inherit the harness's ambient secrets: credential-shaped names and ambient DSH_* facts are scrubbed, and the caller's explicit env merges after that scrub. A deliberately forwarded credential or a current DSH_* deployment fact still reaches the child; an explicit undefined tombstone removes an ordinary ambient entry.
What can go wrong
An executable that cannot be resolved fails loud with a stable error. A spawn that never starts rejects done; there is no buffered output for a process that never ran. waitForExit() also rejects when the provider cannot prove its selected range is empty, and a provider fallback may not own descendants that escape its process group or observed session. When a transport owns its own spawn (the SDK client, MCP), route around the service and import scrubbedParentEnv directly so environment policy stays single-sourced.
Understand the implementation
Implementation internals — click to expand
This section explains the design decisions behind the seam and points at the code that realizes them; the observable behavior is covered in [Use this package](#use-this-package). ### Design concept The seam is built on one separation: the service owns process coordinates and lifetime; consumers own what a process means and every default that shapes one. That is why the spawn request is fully explicit — no hidden subprocess-service default — and why `SubprocessOutcome` carries exit facts only: callers own deadlines, teardown ladders, and cause classification. The `dsh-shell` request/spec split is the owning template. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: abstract `SubprocessRuntime`, `ctx.subprocess` registration, the shared `scrubbedParentEnv` scrub | | [`src/types.ts`](src/types.ts) | Vocabulary: spawn spec, stdio modes, handles, readers, outcomes, `DSH_*` namespace | | — | No runtime invariant companion is published; this stateless Service Definition owns spawn-spec/handle types, while Service Providers own observations. | ### Data model and flow A spawn returns a live handle immediately without exposing target identity. `done` independently reports the direct command outcome or failure, while `waitForExit()` reports managed-range quiescence. The request's abort signal drives the same termination procedure as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members. ### Lifecycle and invariants One implementation registers per context; loading a second throws (cordis standard). Disposal of the service terminates every still-running managed process and awaits its exit, so process lifetime survives consumer reloads. `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself. Terminal allocation cancellation (the spec signal) is separate from the published handle's lifetime.Further Exploration
Read these pages when the package-level contract is not enough. They move from the exhaustive type reference to the providers and the decision evidence behind the seam.
- Subprocess subsystem — spawn specs, output readers, outcomes, and the
DSH_*environment in full. - dsh-subprocess-local — the local host provider that implements this contract.
- dsh-subprocess-e2b — the remote E2B provider for the same seam.
- dsh-bash-local — the largest consumer: bash commands over this service.
- Subprocess seam Agent Note — why the process half became its own seam and what moved with it.
Model Experience
Indirectly, through consumer seams such as the bash executor family, which own all model-facing rendering of process output and lifecycle.
KV Cache effect
No direct invalidation; the named consumers own any request-prefix changes.
Known Limitations and Deferred Work
These limits define when the seam is a poor fit or leaves work to its consumers. They are current package constraints, not a comparison or a backlog.
- SDK-managed spawns remain outside — a transport that owns its internal spawn (the SDK client, MCP) cannot route that call through this service; it can still import
scrubbedParentEnvso environment policy stays single-sourced. - Teardown ladders are consumer-owned — the seam ships signalling verbs and the managed-range wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template).
- Observability is provider-specific — native providers may own escaped descendants through systemd scopes or Windows Jobs, while fallback providers expose weaker process-group, tree, or session visibility. The seam adds no continuous process-table monitor.