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