ADR 0016: process events and a dependency-free terminal package
- Status: accepted (2026-10-22)
- Context: A builder app needs to show what runs in an instance: each command the agent or
the user starts, its output while it runs, and how it ended (docs/terminal-plan.md). Only the
caller of
spawn saw a process’s output, and exec ran through the kernel’s run method,
which returned all output at exit. Terminal emulators (xterm.js) are large and their choice
belongs to the host app, and core packages have no runtime dependencies.
- Decision:
Instance.onProcess(cb) reports spawn (pid, argv, cwd, tag, start time), output (fd 1
or 2, bytes) and exit (code, signal, exit time) for processes started with spawn or
exec. Their children’s output reaches listeners through them, as it does on a terminal.
- The controller keeps a bounded history and replays it to each new listener: the last 100
processes (running ones are never dropped) and the last 256 KiB of output each, with a note
of how much was dropped. Instance output is hostile and must not grow host memory without
limit. Teardown reports every running process as exited with
SIGKILL.
SpawnOptions.tag (and so ExecOptions.tag) labels a process for listeners, e.g.
{ source: 'agent', tool: 'exec', toolUseId }. It stays in the controller and is never sent
to the instance. AgentTools.call(name, input, { tag }) tags what each tool starts.
exec is built on spawn: the spawn RPC now accepts stdin (fed then closed; empty
starts at end-of-file), and the controller enforces timeoutMs with SIGTERM, as the
kernel’s run did. So exec output streams to listeners. If the instance is destroyed or
crashes mid-command, exec still rejects with ERR_DESTROYED/ERR_INSTANCE_CRASHED.
- New package
@clientvm/terminal, depending only on @clientvm/clientvm:
createActivityFeed (immutable CommandBlock snapshots with subscribe/getSnapshot,
the shape React’s useSyncExternalStore takes), attachActivityView(term, instance)
(writes to any { write(data: string) }, which an xterm.js Terminal is), and
createSanitizer, which the view applies to output.
- Consequences:
- Hosts choose their UI: DOM blocks from the feed (the playground), or xterm.js.
exec output now goes through the 8 MiB per-stream handle buffer. exec reads it as it
arrives, so this only drops output that arrives faster than the host page can read it.
- Every
exec and spawn costs a little host memory for the history while listeners are
absent; the bounds above cap it at about 25 MiB per instance in the worst case.
- The kernel’s
run method remains for debugRun (tests and benchmarks).
- Output is not a TTY yet, so most tools print plain text. PTYs are ADR 0017.
Edit this page on GitHub ↗Markdown