Tianyi Cui
6520f71f94
# Conflicts: # .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml # docs/core-data-structures/session.md # docs/module-graph.md # package.json # packages/sdk/scripts/tsconfig.json
sandbox/ — process-sandbox capability family
The confinement half of the capability-seam split: an abstract provider interface and platform backends. Consumers hand ctx.sandbox the exact argv they are about to spawn and spawn the returned (wrapped) argv instead; policy (SandboxPolicy: mode + workspace root) rides each call, so different consumers confine under different policies at the same instant. All product packages.
| Package | Role | ctx key |
|---|---|---|
sandbox/ |
Abstract process-sandbox seam (the SandboxProvider contract + the mode/enforcement/policy vocabulary) |
ctx.sandbox |
sandbox-local/ |
Local backends by platform chain: Linux bwrap else the landlock-run launcher (the npm-distributed node-addon-landlock-run family, built and released from its own repository), darwin sandbox-exec/Seatbelt — multi-candidate chains functionally probed, sole candidates selected directly, verdict cached, fail-closed |
(registers ctx.sandbox) |
The seam confines SAME-WORLD subprocesses only (shared filesystem and kernel). Containers, microVMs, and remote executors are NOT backends here — they replace whole capability implementations (ctx.bash, ctx.fs) as environment-coherent groups; the boundary is recorded in the sandbox Agent Note.
Consumers today: bash/bash-sandbox (wraps ['bash', '-c', command]; see the acp-agent example's default composition for the composed leaf). In-process tools (fs/web) cannot be confined by an OS wrapper — their sandbox semantics are policy at their own seams (the sandbox Agent Note's cross-family phase).