zidane/contexts

Can open a bidirectional byte stream to a long-lived process through ExecutionContext.execStream. Absent / false = the context only supports the buffered ExecutionContext.exec and (maybe) the write-to-a-log-file ExecutionContext.execBackground.

Consumers that NEED live stdin (stdio MCP servers routed into the context) must check this before calling; the seam is optional so contexts backed by a request/response-only API stay valid.

Execute a shell command in the context.

signal propagates abort all the way down to the underlying child process — the implementation is expected to wire it into whatever spawn primitive it uses so the OS receives a SIGTERM (or equivalent) when the caller aborts. Without it, a cancelled tool returns its cancellation marker to the model but the underlying process keeps running in the background, orphaning compute / locks / IO. Pass ctx.signal from a tool body to inherit the per-call + run-level abort union; pass a freshly-built one for a host-driven kill.

Implementations are free to ignore signal (the contract degrades gracefully — the process simply won't be killed), but the process context honors it.

timeout is in SECONDS (default 30) — every implementation converts internally (process ×1000 to ms, docker wraps with coreutils timeout, sandbox SDKs take seconds/ms per their API). Documented here because the unit is invisible at call sites and a caller assuming milliseconds would set an instant-kill timeout.

onOutput hears the output as it arrives, decoded, before the result settles (a UI showing a running command). Optional for implementations: one that cannot stream calls it never, and the result is the same.

Start a process in the background. Settles as soon as spawn returns — does NOT wait for the child to exit. Stdout + stderr stream interleaved to the file at the returned outputPath. The caller (typically the agent) reads incremental output via the regular ExecutionContext.readFile seam.

Optional — contexts without background support (some remote sandboxes) just don't implement it. The shell tool surfaces a clean "background mode is not supported in this execution context" error when this is undefined.

onExit is called once when the child terminates (natural, killed, or error). The same instance that called execBackground is the exclusive owner of the callback — it's not a multi-cast bus. Hosts wire this to the agent's pending-notification queue so the model gets a <task-notification> on its next turn.

onExit is OPTIONAL: remote / durable contexts may have no legal way to push a callback from a timer back into the host (a replay journal, for instance, forbids out-of-band writes). Such contexts record the exit in their registry; the agent loop reconciles by polling ExecutionContext.listBackground at run boundaries, where a host journal wrapper is legal (the background:reconcile hook is the journalable seam).

See docs/RUN_IN_BACKGROUND.md for the broader design contract (file location, replay semantics, suppression rules).

Open a LIVE bidirectional byte stream to a long-lived process in the context. The third execution mode, alongside the buffered exec (request/response) and execBackground (fire-and-forget into a log file): neither of those can carry a protocol that interleaves reads and writes over the child's lifetime.

Motivating consumer: stdio MCP servers. An MCP server is an ordinary process doing fs.readFileSync / fs.writeFile against whatever filesystem it was spawned on. Spawned on the host (the default — see McpServerConfig.scope) it sees the HOST filesystem while the agent's own tools see the context's, so the two disagree about what a path means. Routing the server through this seam puts both on the same filesystem.

Optional — a context backed by a request/response-only API can't implement it. Advertise support via capabilities.stream; callers check that (or execStream !== undefined) and degrade with a clear error rather than silently falling back to a host spawn, which would reintroduce exactly the split this seam exists to close.

IMPLEMENTOR CONTRACT — the shape is deliberately the SUPERSET of what the backing APIs can do, because they do not agree:

• stdout / stderr are byte streams, never pre-decoded strings. A provider SDK that hands back string has already destroyed any multibyte codepoint split across a chunk boundary; the caller needs the raw bytes to run its own streaming decoder.
• stderr is OPTIONAL because a PTY-backed context physically cannot separate it — one terminal, one stream. Such contexts redirect the child's stderr to a file; they may then surface it here out-of-band (the Daytona context polls that file back), but they are not obliged to, so consumers must tolerate its absence.
• A PTY-backed context MUST also neutralise terminal semantics before the child's first byte (echo of everything written to stdin, \n→\r\n rewriting, and the ~4096-byte canonical-mode line cap that arbitrary protocol frames exceed). In practice: launch through stty raw -echo; exec <cmd> 2><file>.
• exited resolves with the exit code. On a PTY the child is an interactive shell that never exits on its own, so kill() is the normal termination path, not an abnormal one.
• Providers that impose a default command timeout (E2B and Daytona both default to 60s) MUST disable or maximise it here. A stream opened by this method is expected to live for the whole session.

Cheap size probe for a file in the context's filesystem, in bytes. null = unknowable (missing file, not a regular file, probe failed, or containment rejected the path — a probe must not leak even the size of files outside the workspace root).

Exists because readFile has no partial-read form: tools that must materialize a whole file (read_file's text path, edit/multi_edit, grep's no-rg fallback) consult this first to refuse multi-GB targets instead of OOMing the HOST — the read lands in host memory no matter where the file lives. Per-context posture:

• process — implements it (local stat, µs).
• docker — implements it via wc -c through its exec; its readFile gets transport headroom above the tool ceiling so the probe (tool policy), not the 10MB exec cap, decides read limits — same experience as every other context.
• sandbox (and the e2b / daytona providers behind it) — implements it via wc -c through the provider's exec: one extra round-trip per whole-read tool call, paid so a multi-GB sandbox file is refused BEFORE the SDK transfers it into host memory.

KNOWN RESIDUAL (sandbox providers): this guards the readFile path only. Their exec output is buffered inside the provider SDKs (e2b commands.run, daytona executeCommand), which we cannot cap from this side — a command that streams GBs to stdout within its timeout window can still balloon host memory. Docker doesn't share the residual (we own its transport; see output-cap.ts). A shell wrapper (| head -c) was considered and rejected: preserving exit codes, stderr separation, and timeout semantics through a pipe for EVERY command is fragile, and the timeout already time-bounds the exposure.

Resolve the host-side port that a container port was published on (docker context only, and only when the matching entry was created with host omitted in SpawnConfig.ports).

Resolves to null if the container port isn't published. Other contexts (process, sandbox) don't implement this; they don't have a port-mapping concept.

SIGTERM the whole process group of a running background task. Idempotent — second call returns null (or the cached exit info). Resolves once the process has exited AND its output stream has been flushed + closed.

null return on miss (unknown id, already cleaned up) so the shell_kill tool can surface a clean "no such task" message without throwing.

List files in the context filesystem.

Plain paths list immediate directory entries. Paths that contain glob metacharacters (*, ?, [], {}) request matched file enumeration inside the target context. Contexts that cannot support globbing should throw a clear error rather than silently returning no matches. metadata is best-effort and only required when the context can provide it without expensive per-file shell calls.

Open an interactive terminal (a PTY running the user's login shell) in the context: on the host, in the container, in the sandbox. For people, not protocols: the opposite of execStream, which defeats every terminal semantic this one keeps (echo, line editing, job control, window size).

Optional: a context without a PTY primitive (or a runtime without one: the local contexts need Bun) leaves it undefined, and callers offer no terminal rather than falling back to a host shell.

Read a file from the context's filesystem as raw bytes.

Used by read_file to dispatch image / binary files into the multimodal ToolResultContent[] route. Optional — when not implemented, the tool falls back to base64 < path via the exec seam, which works in any shell-capable context. Implementations that already have a native binary read (in-process fs.readFile without encoding, container API, sandbox SDK) should override for the latency win.

Transfer ownership of every still-running task from fromHandle to toHandle. Used by the spawn tool to "promote" a subagent's background tasks up to the parent's handle so they outlive the subagent's destroy() — matching shell semantics, where a &-ed command outlives the parent process.

With fromHandle === toHandle ownership stays put and only the callbacks are rebound: a host that keeps one handle across agent rebuilds (chat/execution-cache.ts) hands the running tasks to the freshly built agent this way.

Side effects:

• The task's handleId is rewritten, so subsequent listBackground(toHandle) / killBackground(toHandle, …) / destroy(toHandle) see it (and fromHandle-scoped operations don't).
• When newOnExit / newOnStall are provided, the task's OWNER callbacks are REPLACED with them. Critical: they were captured against the spawning agent's hook bus, which is about to be destroyed; without rewiring, the new owner never learns when the task terminates or stalls. Pass closures that fire the new owner's background:exit / background:stall hooks. In-flight killBackground / waitBackground resolvers are not owner callbacks and keep firing.

Returns the entries that were actually reassigned (running tasks only; terminated ones stay where they are). Implementations that don't support reassignment can leave this undefined; the caller (spawn.ts) falls back to the current behavior of killing child tasks at subagent shutdown.

Block until a background task terminates, then resolve with its exit info. Resolves immediately for already-terminated tasks.

Returns null when:

• the task id is unknown (or owned by another handle — same isolation contract as killBackground), OR
• timeoutMs elapsed / signal aborted before the task exited.

Callers that need to distinguish "unknown" from "still running" should consult listBackground first (the wait_task tool does).

This is the injectable wait seam for the wait_task tool: in-process contexts implement it on the existing onExit machinery; durable hosts implement it as an awakeable park (runner fires task-exit over their bridge → resolveAwakeable).

Write a file to the context's filesystem.

encoding applies only when content is a string (how its bytes are produced; defaults to utf-8) and is ignored for a Buffer, which is written verbatim.

How long destroy() waits for a SIGTERM'd background task to settle before escalating to SIGKILL and abandoning the wait (process context only). Bounds agent.destroy() against tasks that trap SIGTERM or whose stdio pipes are held open by escaped grandchildren.

Default: 5000.

Container hardening options (docker context only).

All fields are opt-in and OFF by default to preserve existing behavior (containers run with the image's default user/capabilities). Enable them for untrusted workloads. dropAllCapabilities and a non-root user (see SpawnConfig.user) can break images that expect root or specific capabilities, so they are not applied unless requested.

Whether spawned shells inherit the parent process.env (process context).

Default true (preserves existing behavior — children see the parent environment including anything Bun auto-loaded from .env). Set false for untrusted workloads so secrets in the parent environment aren't readable by tool commands; only env / per-call env plus a minimal base (PATH, HOME, SHELL, LANG, LC_ALL, USER, TERM, TMPDIR) are passed through.

OS-level sandboxing of shell commands (process context only). When set, every exec / execStream / execBackground runs /bin/sh -c under macOS sandbox-exec or Linux bwrap: filesystem writes are limited to writableRoots, credential directories are hidden, and network is allowed or denyed as a whole. writeFile applies the same writableRoots check in-process (reads are unrestricted — this is the Claude Code / Codex boundary, not a full jail; use workspaceRoot for read containment).

Fails closed: when the backend is unavailable on the host, every command returns exit 127 with the reason instead of running unsandboxed.

Build the policy with resolveWritableRoots from contexts/isolation.

Docker labels to attach to the container (docker context only).

Useful for ownership tracking — callers can sweep abandoned containers (e.g. from a crashed parent process) by filtering on a label they own: docker ps -aq --filter label=my-app=true.

User-defined Docker network to join (docker context only).

Defaults to Docker's default bridge. Use a user network when you need multiple sibling containers (e.g. agent + database + dev server) to discover each other by name.

Publish container ports on the host (docker context only).

Each entry maps a container port to either an explicit host port or (when host is omitted) a Docker-assigned random port. Retrieve the actual host port at runtime via getMappedPort(handle, containerPort) on the docker context.

UID/GID the container should run as (docker context only).

Accepts the same forms Docker's --user does: uid, uid:gid, or a named user that exists in the image. Default is the image's default user (typically root). Setting this to the host user's uid:gid avoids the EACCES-on-cleanup problem when sharing a workspace via a shared mount.

Optional workspace-containment root for the file methods (readFile, writeFile, listFiles) of the process context.

When set, a resolved path that escapes this root (via absolute path, .., or a symlink pointing outside) is rejected before any I/O. Default unset = no containment (back-compat; the agent can read/write anywhere the host process can). Set this for untrusted workloads to confine file tools to a directory. Shell commands are not covered — use a sandbox / docker context for full isolation.

Child's stdout as raw byte chunks, in emit order.

CONSUMER OBLIGATION: drain this (and stderr) for the stream's lifetime. Nothing here is bounded, and the consequence of ignoring it varies by backend and by host runtime, none of it good:

• process / docker hand back real OS pipes. Under Node an unread stream stops draining the fd and the child BLOCKS once the pipe fills (~64 KiB) — a deadlock, not a slowdown. Under Bun the runtime buffers eagerly instead, so it presents as unbounded host memory (measured: 32 MiB of unread stderr never blocked the child).
• e2b / daytona buffer in a StreamQueue, which grows without limit. It cannot do otherwise: both SDKs push output through a synchronous (data) => void callback, so there is no channel to apply backpressure, and dropping bytes would desynchronise a framed protocol permanently. The queue logs a one-shot warning once the unread backlog passes 8 MiB so a stalled consumer is diagnosable.

createContextStdioTransport satisfies this for both streams.