# Interfaces

The public API is declared in [`packages/clientvm/src/types.ts`](https://github.com/Reflex-Gravity/client-vm/blob/main/packages/clientvm/src/types.ts)
and implemented by `createClientVM()` in [`controller.ts`](https://github.com/Reflex-Gravity/client-vm/blob/main/packages/clientvm/src/controller.ts). Changes to that file must update this page.

## Refinements over the original API sketch

| Change | Why |
|---|---|
| `InstanceId` and `SnapshotId` are branded strings | Prevents mixing ids with names or paths at compile time |
| Added `Disposable`, `Signal`, `ProcessType`, `FileTree`, `Limits`, `InstanceInfo`, `DirEntry`, `Stat`, `FsEvent`, `MountSource`, `SpawnOptions`, `ExecOptions`, `ExecResult` | The sketch referenced them without defining them |
| `ProcessType = 'js' \| 'builtin' \| 'wasi' \| 'vm'` | Reserves the future tiers (there is no CPU emulator in v1, but the interface is kept) |
| `Limits.quotaBytes`, `Limits.maxCpuMs` | Per-instance budgets from the security model |
| `ExecOptions.timeoutMs`, `ExecOptions.stdin` | Agents need bounded, non-interactive exec |
| `MountSource` is a union of instance-dir and snapshot mounts | Mounting needs a source and a read-only flag that a capability can check |

## Implementation status (Phase 2b)

| API | Status |
|---|---|
| `createClientVM({ sandboxOrigin, instancePath?, container?, bootTimeoutMs? })` | done |
| `createInstance`, `getInstance`, `listInstances` | done. `id` + `fs.persist` reattach to persisted storage |
| `InstanceOptions.fs.persist`, `Instance.flush()`, `destroy({ purge })` | done (2c): write-behind OPFS persistence, one tab per persistent instance (`EBUSY` otherwise) |
| `InstanceOptions.fs.from` (`FileTree` or `SnapshotId`), `fs.quotaBytes`, `limits.maxProcesses` | done |
| `InstanceOptions.preset` (`'vite-react-ts'`), `ClientVMOptions.presetStore`, `cachePresetStore`, `memoryPresetStore` | done (ADR 0018): a ready project in `/home/user/app`, built once in a hidden instance and cached in the host origin's Cache Storage; `ERR_INVALID_PRESET` for unknown names or with `fs.from`, `ERR_PRESET_BUILD` if setup fails |
| `InstanceOptions.onPresetBuild` | done: the hidden builder's `ProcessEvent`s (`npm ci`, warm-up build) while a call waits on a preset build, with history replayed to callers that join late; not called when the image is already stored |
| `Instance.fs`: `readFile writeFile readdir stat mkdir rm rename symlink watch` | done (`watch` is recursive) |
| `Instance.fs.mount`/`unmount` | done (4c): read-only mirrors of another instance's directory (kept in step from its watch events) or of a snapshot; needs a `mount` capability; writes under a mount fail with `EROFS`, including through symlinks; writable mounts reject with `ERR_NOT_SUPPORTED` |
| `Instance.spawn` → `Process` with streaming `stdout`/`stderr`, `stdin`, `kill`, `exit` | done. `stdin` writes reach the process (`process.stdin`, `fs.read(0)`); closing it sends EOF. Unread output is buffered up to 8 MiB per stream, then dropped with a note on that stream (5c) |
| `Limits.maxCpuMs` | done (5c): a watchdog pings each process; one that runs JavaScript for `maxCpuMs` without yielding (time blocked in syscalls does not count) is killed with `SIGXCPU` (exit 152) |
| `Limits.maxMemoryMB` | accepted, not enforced (open-questions.md) |
| `Instance.measureMemory()` | done (5c): bytes for the instance page and kernel worker via `performance.measureUserAgentSpecificMemory()` on the instance origin; process workers are not attributed by Chromium. Tracked by the benchmark gate |
| `Instance.snapshot()` → `"<instanceId>:<n>"` | done. Held by the source kernel; gone when it is destroyed |
| `Instance.createChild(opts)` | done (4e): a child instance with a fresh filesystem; needs `spawn-instance` like `fork` |
| `@clientvm/agent-api` `createAgentTools({ instance })` | done (4e): LLM tool definitions and a dispatcher ([agent-api.md](https://clientvm.joeldsouza.me/docs/agent-api.md)). Since T1, `call(name, input, { tag })` tags the processes a tool starts with `{ source: 'agent', tool, ...tag }` |
| `Instance.fork()` | done: image export → new origin. Since 4a it needs a `spawn-instance` capability, whose limits bound the child's |
| `Instance.destroy()` | done |
| `Instance.exec` | done (3c): `sh -c` to completion with `cwd`, `env`, `stdin`, `timeoutMs` (SIGTERM to the shell and every process it started). Since T1 it runs on `spawn`, so its output streams to `onProcess` |
| `SpawnOptions.pty`, `Process.resize`, `WindowSize`; `Signal` extended to HUP INT QUIT KILL USR1 USR2 PIPE ALRM TERM CHLD XCPU WINCH | done (T2, ADR 0017): a process on a pseudo-terminal (TTY stdio, keystrokes on `stdin`, output on `stdout`, SIGWINCH on resize). `Process.kill` delivers signals: a handler may take one; otherwise the default action applies, and a process that does neither within 1 s is terminated. `resize` on a process without a terminal throws `ERR_NOT_A_TERMINAL` |
| `@clientvm/terminal` `attachShell(term, instance, opts)` | done (T2): `bash -i` on a pty connected to an xterm.js-compatible terminal (keys, sanitized output, resize); `dispose()` hangs up |
| `Instance.onProcess`, `SpawnOptions.tag`, `ProcessInfo`, `ProcessEvent` | done (T1, ADR 0016): spawn/output/exit of processes started with `spawn` or `exec`, replaying the last 100 (256 KiB of output each) to new listeners. `tag` is a host-side label, never sent to the instance |
| `@clientvm/terminal` | done (T1, T3): `createActivityFeed`, `attachActivityView`, `createSanitizer`, `displayCommand`, `stripAnsi`; both views take `OutputOptions` (`throttle`, `linkPorts`, `persist`) ([terminal-plan.md](https://github.com/Reflex-Gravity/client-vm/blob/main/docs/terminal-plan.md)) |
| `Instance.onPortOpen` | done (3d): fires for open and future virtual ports with the port's own origin, `https://<id>-p<port>.<sandbox-domain>/` (ADR 0008), once its service worker is linked |
| `Instance.onPortClose` | done (3d): fires when a reported port stops listening (its server closed or its process exited) |
| `InstanceOptions.name`, `Instance.name` | done (4a): a DNS label, unique among live instances; the instance's `<name>.internal` host name |
| `ClientVM.grant`/`revoke`, `Instance.grant`/`revoke`/`capabilities`, `InstanceOptions.capabilities` | done (4a): the controller's capability table. Instances grant what is about themselves or delegate what they hold; children get no more than their parent could grant (docs/phase4-plan.md) |
| `Instance.mailbox` | done (4a): `send` needs a `channel` capability; JSON values up to 1 MiB; delivery goes to host listeners and to the kernel inbox, which processes read at `http://mailbox.internal/` |
| `Instance.openPreview(port, opts)` → `Preview` | done (4d): an iframe on the port origin driven through the injected agent: `snapshot` (outline with `[ref=eN]` targets, optional HTML), `click`, `type`, `press`, `waitFor`, `evaluate`, `screenshot` (PNG via SVG `foreignObject`), `console` (captured from the first script of each page, across navigations), `navigate`, `reload`, `close` |
| `Instance.networkLog(since)` | done (4d): the last 500 requests served on virtual ports (method, path, status, time to headers, requesting instance) |
| `http://<name>.internal:<port>/` from processes | done (4b): needs a `net` capability for the peer (and port); HTTP only, responses stream |

Instances that crash (their renderer process dies) are detected by a heartbeat
(`ClientVMOptions.heartbeatMs`, default 5000; a kernel silent for four intervals is gone): the
instance is torn down, its processes exit with `SIGKILL`, and pending and later calls reject with
`ERR_INSTANCE_CRASHED`. At most 64 ports per instance get a port origin (bridge iframe); further
ports are not reported by `onPortOpen`.

Errors raised by the controller are `ClientVMError` with a `code` (`ERR_NOT_ISOLATED`, `ERR_INSTANCE_CRASHED`,
`ERR_BOOT_TIMEOUT`, `ERR_INSTANCE_PROTOCOL`, `ERR_DESTROYED`, `ERR_NO_CAPABILITY`,
`ERR_NO_INSTANCE`, `ERR_INVALID_CAPABILITY`, `ERR_INVALID_MESSAGE`, `ERR_RATE_LIMITED`, ...). Errors from inside an instance
keep the system error `code` (`ENOENT`, `EAGAIN`, ...).

## Internal interfaces (not public API)

- **Syscall channel** (`@clientvm/protocol`): `SyscallClient.call(op, bytes) → bytes` and
  `SyscallServer(sab, handler)`. Bytes in, bytes out, so it can be replaced by Rust/WASM if
  profiling demands.
- **Process runtime** (`@clientvm/process`): `type Runtime = (ctx: ProcessContext) => number | void
  | Promise<…>`. `ctx` provides `argv`, `env`, `cwd`, `syscall`, `stdout`, and `stderr`.
- **Instance RPC** (`@clientvm/protocol` `InstanceRpc` / `InstanceEvents`): what an instance kernel
  serves to the controller over its MessagePort, plus the handshake messages.
- **Controller RPC** (`ControllerRpc`): requests a kernel makes of the controller on the same
  port (`mailboxSend`, `netFetch`). They run with the calling instance's capabilities.