Yichen Jiang
d6bebc5783
The executor seam collapses run()/start() (and the planned begin()) into one
resolve() + execute(): the handle IS the live process, and the foreground
result, the background cursor, and the deadline's promotion offer are
projections over the same spawn. ShellExecSpec.onExpiry ('kill' default /
'offer' / 'none') replaces the implicit method split; one stdout budget applies
everywhere, the 'start ignores timeoutMs' wart dies, and sync spawn throws are
contained into the same settled-killed handle as async rejections (result()
rejects with the original error, identity preserved for the sandbox
classification).
The promotion offer settles exactly once and never rejects — offer at an
'offer' deadline while running, undefined when the process settles first — so
'await execution.promotion' alone distinguishes the outcomes. An offer must be
answered synchronously; an unanswered one auto-declines back to the
kill-on-timeout behavior. accept() ends the deadline and detaches the caller's
abort signal; decline() kills and classifies timedOut.
tool-bash and tool-pwsh promote on timeout by default (promoteOnTimeout: true,
inert without run_in_background or a job registry): at the offer the running
handle registers as a job with the same hooks as run_in_background, mirrors
into ctx.activities (the web task list streams it, stop control included), and
the call returns { kind: 'promoted', jobId, timeoutMs, output } carrying the
output so far — the job cursor continues exactly after it. Any promotion
failure declines and falls back to the plain timeout kill. Descriptions and
the timeoutMs schema text advertise the semantics only when they hold;
recorded-session and web snapshot fixtures re-recorded with them.
Also repairs the four CI failures from the human-kill push: ui-activity's
missing dsh-session peer declaration (static + windows observational), the
observe owner-arm/outer-catch and killJob-stub coverage gaps, tool-workflow's
owned-run arm, and the timing-dependent projection-cache interval flush test
(now poll-based for coarse Windows timers).
Peer evidence and rejected alternatives (Codex's session model, a third seam
method, a second threshold knob) in the Agent Note
2026-08-26-shell-execute-timeout-promotion.
description, kind
| description | kind |
|---|---|
| The bash capability family for deployments and maintainers choosing and composing a shell executor, sandboxing, and the model-facing bash and pwsh tools. | package-group |
shell/ — bash capability family
English | 中文
Summary
The shell group provides command execution to agents: run a foreground command and read its bounded output, or start a background process and poll it, on POSIX with Bash and on Windows with PowerShell. Exactly one executor implementation is mounted per composition; the sandboxing executors confine every command through the sandbox capability, and the model-facing bash and pwsh tools sit on top of whichever executor is mounted. Choose a Bash executor for POSIX, a PowerShell executor for Windows, and pick the sandboxing variant when commands need file-level confinement.
Table of Contents
Packages
| Package | Role | ctx key |
|---|---|---|
shell |
Defines the executor contract: foreground runs, background handles, and request resolution | ctx.shell |
bash-local |
Runs Bash commands as fresh bash -c processes on POSIX |
registers ctx.shell |
bash-sandbox |
Runs Bash commands confined through the sandbox capability, reporting denials as facts | registers ctx.shell |
pwsh-local |
Runs PowerShell commands as fresh pwsh -Command processes on Windows |
registers ctx.shell |
pwsh-sandbox |
Runs PowerShell commands confined through the sandbox capability | registers ctx.shell |
shell-env |
Supplies the managed DSH_* environment every shell command receives |
ctx.shellEnv |
tool-bash |
Exposes Bash execution and background jobs to the model as the bash tool |
registers on ctx.tools |
tool-bash-persistent |
Runs model shell calls in one owner-isolated persistent Bash session | registers on ctx.tools |
tool-pwsh |
Exposes PowerShell execution to the model as the pwsh tool |
registers on ctx.tools |
tool-pwsh-persistent |
Runs model shell calls in one owner-isolated persistent PowerShell session | registers on ctx.tools |
A profile layer selects exactly one executor implementation (the win32 layer swaps the POSIX rows for the pwsh ones; mounting two fails loud on the duplicate service registration) and the model-facing tools it needs. A sandboxed composition also selects a ctx.sandbox provider and ctx.sandboxPolicy; the base bundle owns the shipped wiring.
Related documentation
- Bash executor subsystem — the shared request/spec vocabulary, results, background processes, and the service contract.
- Sandbox subsystem — the confinement capability the sandboxing executors consume.
Dev Note
None.