Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions packages/process-daemon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ terminals. Observer commands connect to an existing daemon without taking owners
The service uses a private authenticated local byte stream (Unix socket or Windows
named pipe) and an atomic registration file.

Integrations launch `opencode-pty daemon --name NAME [--runtime-dir DIR]` (protocol 7).
Integrations launch `opencode-pty daemon --name NAME [--runtime-dir DIR]` (protocol 8).
The server must claim the daemon within 5 seconds by sending the authenticated
framed envelope `{"token":"...","request":{"op":"own","instance_id":"..."}}`.
The response is `{"type":"owned"}`; that connection stays open as the sole
Expand Down Expand Up @@ -70,7 +70,7 @@ socket pair until a connection arrives, a stop or ownership change wakes it, an
ownership deadline is due, or a two-second safety net elapses. Windows still
polls every 25 ms.

The Windows named-pipe backend keeps protocol 7 and the registration fields
The Windows named-pipe backend keeps protocol 8 and the registration fields
`instance_id`, `pid`, `protocol`, `socket`, `token`, and `features`. Treat `socket` as an opaque
local endpoint: on Windows it is `\\.\pipe\opencode-pty-<instance_id>`, not a
filesystem socket. A random per-instance name, exclusive first pipe instance,
Expand Down Expand Up @@ -111,7 +111,7 @@ so the runtime directory must be on a local NTFS volume (Windows 10 1709 or
later); there is no non-atomic fallback.

The Windows Rust `TerminalClient` and interactive CLI are not ported. Integrations
can use protocol 7 directly and the minimal `daemon::PipeConnection` byte-stream
can use protocol 8 directly and the minimal `daemon::PipeConnection` byte-stream
helper. Connect with `PipeConnection::connect_to(socket, pid)`, which rejects a
pipe whose server is not the registered daemon process: after a crash the stale
registration's pipe name is free for another local user to create. Integrations
Expand Down Expand Up @@ -211,9 +211,9 @@ return all available rows. Soft-wrapped rows stay separate, trailing whitespace
is trimmed, and blank rows (including trailing blank rows) are empty strings.
The alternate screen never exposes primary-screen history.

The protocol 7 request is `{"op":"read_rows","id":1,"rows":30}`;
The protocol 8 request is `{"op":"read_rows","id":1,"rows":30}`;
omitted or `null` `rows` uses the current height. Its response is
`{"type":"rows","terminal":{...},"lines":[...],"cursor_x":0,"cursor_y":0}`.
`{"type":"rows","process":{...},"lines":[...],"cursor_x":0,"cursor_y":0}`.
Metadata, lines, and zero-based active-screen cursor coordinates come from one
actor snapshot. Reading does not move the viewport, change selection, or take
control. Existing snapshots, checkpoints, and replay are unchanged.
Expand Down Expand Up @@ -311,7 +311,7 @@ can consume application terminal queries itself; the tests also check its
cursor-inheritance query reaches our reader and Ghostty parser.

The reusable fixture in `tests/support/terminal_fixture.rs` returns a
`CreateTerminal` request and uses a separate control/observation channel, so
`CreatePty` request and uses a separate control/observation channel, so
daemon tests can reuse it without a shell or Rust client. Include it as
`terminal_fixture`, call `Fixture::request`, create the terminal, then call
`Fixture::connect`. `Command::Output` writes real console stdout; `Command::Read`
Expand Down
178 changes: 128 additions & 50 deletions packages/process-daemon/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ No borrowed libghostty object crosses a thread boundary.
## Row Reads

`Request::ReadRows { id, rows: Option<u16> }` (`op: "read_rows"`) returns
`Response::Rows { terminal, lines, cursor_x, cursor_y }` (`type: "rows"`). Both
`Response::Rows { process, lines, cursor_x, cursor_y }` (`type: "rows"`). Both
the service and Rust client expose `read_rows(id, rows)`. Omitted or null rows
defaults to the current terminal height; zero is rejected. A larger count
includes retained history, up to all available rows of the active buffer.
Expand All @@ -86,15 +86,14 @@ checkpoint, or replay state is changed.
Row reads have a 1 MiB budget for JSON-escaped row strings, array punctuation,
and owned-string slots (including blank rows); formatting buffers are also
bounded. Results exceeding that budget fail rather than truncate. Complete
responses remain subject to the transport's 8 MiB frame limit. Protocol 7
supports `read_rows` alongside the existing snapshot and replay operations.
responses remain subject to the transport's 8 MiB frame limit.

## Titles

`TerminalInfo.title` is the effective title: the user title, else the latest
`pty.title` is the effective title: the user title, else the latest
OSC 0/2 title, else the title given at creation. An empty OSC title (a program
resetting it) or an empty user title counts as unset. `TerminalInfo.user_title`
is always serialized, as `null` when unset.
resetting it) or an empty user title counts as unset. `pty.user_title` is
always serialized, as `null` when unset.

`Request::Rename { id, title: Option<String> }` (`op: "rename"`) sets the user
title, or clears it when `title` is null or empty, and returns `Response::Ok`.
Expand All @@ -105,45 +104,117 @@ once it is cleared.
Rename and OSC updates publish `TitleChanged` with the effective title only
when it changes; an OSC change hidden behind a user title publishes nothing.

`list` returns terminals in creation order.
## Processes

Every process, PTY or pipe, is described by `ProcessInfo`:

- `id`, `mode` (`"pty"` or `"pipe"`), `pid`, `command` (program and
arguments), `cwd`, `group_id` (an opaque string), `lifecycle`,
`output_head` and `output_tail` (absolute byte offsets), `started_at` and
`exited_at` (milliseconds since the Unix epoch; `exited_at` is `null` until
the exit is final, that is until `Exited` is sent, and never before
`started_at`).
- `pty`, set only for PTYs: `title`, `user_title`, `foreground_process`,
`cols`, `rows`.
- `pipe`, set only for pipe processes: `output_path`, `output_lines`,
`output_error` (left out when there is none) and `metadata`.

Exactly one of `pty` and `pipe` is present, matching `mode`; the other key is
left out.

`list { mode }` (`mode` required) returns the processes of that mode in
creation order as `Response::Processes { processes }`. `get { id }` returns one
process of either mode as `Response::Process { process }`, or an error for an
unknown id. Both refresh a PTY's foreground process first.

`Created`, `Snapshot`, `Rows` and `Attached` carry the info as `process`.

## Pipe Processes

`Create` takes `mode: "pty" | "pipe"` (default `"pty"`). A pipe process runs
any command without a terminal; it is Unix-only for now, and only daemons that
list the `pipe` feature accept it. Older daemons ignore `mode` and would start
a PTY instead, so clients check `features` first.
`create_pty { program, args, cwd, env, group_id, title, cols, rows }` starts a
PTY. `create_pipe { program, args, cwd, env, group_id, output_path, metadata }`
starts a pipe process: any command without a terminal. Both return
`Created { process }`. Pipe processes are Unix-only for now; a Windows daemon
answers `create_pipe` with an error.

- `title`, `cols` and `rows` are optional for pipe processes; the title
defaults to the program's file name and the size is reported as `0x0`.
- The child gets exactly `env`: the daemon's own environment is not
inherited, and no `TERM` or `COLORTERM` is added. `cwd` must be absolute.
- The child gets its own process group, an empty signal mask with default
actions (the daemon blocks SIGTERM and SIGINT, and std keeps the mask across
exec), stdin on `/dev/null`, and one pipe for
both stdout and stderr, so their bytes stay in order. No `TERM` or
`COLORTERM` is added, and nothing parses the output: there is no emulator,
exec), stdin on `/dev/null`, and one pipe for both stdout and stderr, so
their bytes stay in order. Nothing parses the output: there is no emulator,
no terminal replies, no OSC title and no foreground process.
- Output goes through the same raw replay and subscriptions as a PTY, with the
same absolute offsets. A pipe has no controller or observer distinction for
writing, since it accepts no input.
- `output_path` must be absolute. The daemon opens it before spawning,
truncating an existing file or creating one with mode `0666` minus the
daemon's umask, and refuses a symlink as the final path component. The
request is validated (program, absolute paths, metadata size) before the
file is opened, so such a rejected request never creates or truncates it; a
path that cannot be opened fails the request without starting the process.
A missing program or `cwd` fails at spawn, after the file was opened.
- The reader writes every output byte to the file before handing it to the
actor. The file is the only copy of the output: a pipe process has no replay
buffer, so `replay` and `subscribe` return an empty replay (with correct
offsets) and live events only. Output never needs to cross the socket.
- A write error stops the file and sets `pipe.output_error`; the process keeps
running and its output is still counted in the offsets.
- `write`, `resize`, `control`, `input`, `snapshot`, `read_rows` and `rename`
fail for pipe processes. `replay`, `subscribe` and `terminate`
work.
- Exit is published once both the exit status and the end of output are
known. A descendant that keeps the pipe open (`cmd &`) delays that by at
most one second after the child exits; output after that is not read.
- `Exited` (the lifecycle and the subscription response) carries `signal`,
the signal's name such as `"SIGTERM"`, when a pipe process was killed by
one; `exit_code` is then null. The field is left out when there is no
signal, so PTY exits serialize as before.
fail for pipe processes; `wait`, `signal` and `set_metadata` fail for PTYs.
- Exit is published once both the exit status and the end of output are known.
A descendant that keeps the pipe open (`cmd &`, dev servers) delays that by
at most one second after the child exits; the reader then closes the pipe,
so leftover writers get `SIGPIPE`/`EPIPE`. This is deliberate: the process
is reported as finished, and nothing reads what comes later. The file is
closed before the exit is published.
- `Exited` and the lifecycle carry `signal`, the signal's name such as
`"SIGTERM"`, when the process was killed by one; `exit_code` is then null.
`signal` is left out when there is none.
- An exited pipe process stays listed, as a zombie, until `terminate`. The
zombie keeps its PID and process group ID reserved, so `terminate` can kill
any descendants left in the group without reaching an unrelated process.
`terminate` sends SIGKILL to the group and to the child, reaps it, and never
waits on a descendant that left the group and still holds the pipe.

`List` takes `mode` too. Without it, `list` returns PTYs only, so servers that
predate pipe processes never see them. Clients leave `mode` out of the request
when it is unset: older daemons reject a `list` with any extra field.
zombie keeps its PID and process group ID reserved, so killing the group can
never reach an unrelated process. `terminate` sends SIGKILL to the group and
to the child, reaps it and removes the process; it never waits on a
descendant that left the group and still holds the pipe. The daemon never
deletes output files.

### Line count

`pipe.output_lines` counts the `\n` bytes written to the file. The reader
counts them in each successfully written slice (including a partial write
before an error), and the actor adds them in the same step that advances
`output_tail`, under the same lock, so `get` and `list` always return a
matching pair. After a write error nothing more is counted.

The file can hold a little more than `output_tail`, since the reader writes
before the actor counts: read only up to `output_tail` when pairing bytes with
the count. After `Exited` the file is closed and its size equals
`final_offset`, unless `output_error` is set: output read after a write error
still advances `output_tail` and `final_offset` but is not in the file, so use
the file's real size.

### Wait, signal and metadata

`wait { id }` (pipe only) is held open until the process exits, then answered
with one `Exited` and closed. It never sends output. A process that already
exited is answered at once, so `list` followed by `wait` after a server
restart cannot miss an exit. An unknown id or a PTY is answered with an
`Error` at once. If the process is terminated first, the reply is
`Error { message: "terminated" }`; if the daemon stops, the connection closes
without a reply. Several waiters may wait on one process.

`Exited` carries `exit_code`, `signal`, `final_offset`, `output_lines` (pipe
only; left out for PTYs), `output_error` (left out when there is none) and
`exited_at`. PTY subscriptions send the same response.

`signal { id, signal }` (pipe only; `"SIGTERM"`, `"SIGINT"` or `"SIGKILL"`)
signals the process group and the child, and returns `Ok`. Unlike
`terminate`, it keeps the process: `wait` then gets a normal `Exited` with
`signal`. Signalling an exited process is allowed and reaches whatever is left
of its group (an empty group is not an error); after `terminate` the process
is gone and `signal` fails.

`metadata` on `create_pipe` is an opaque JSON object the daemon stores and
returns as `pipe.metadata` without interpreting it. `set_metadata { id,
metadata }` (pipe only) replaces it and returns `Ok`. Both reject metadata
over 1 MiB of serialized JSON.

## Failure Boundary

Expand All @@ -162,19 +233,25 @@ connected owner; the superseded connection can no longer prepare handoffs or
stop the daemon, and its disconnect does not affect the new owner. The playground holds ownership until it exits; other CLI commands
only observe or operate an existing daemon and never start one.

Protocol v7 uses four-byte big-endian framing with bounded UTF-8 JSON control
frames and tagged raw binary output frames. It supports ping, create, list,
write, resize, atomic interaction promotion, snapshot, read_rows, replay, replay-to-live
subscriptions, title updates, rename, controller takeover, terminate, and destructive service
shutdown, ownership acquisition, and restart handoff preparation.

`Pong` and the registration carry `features`, the daemon's additive
capabilities (currently `["rename", "pipe"]` on Unix and `["rename"]` on Windows). Additive changes, such as a new request
or field older clients can ignore, extend `features` and keep the protocol
version; clients check `features` before sending a new request, since a daemon
that cannot parse one drops the connection. Only breaking changes bump
`PROTOCOL_VERSION`, which clients reject on mismatch. A missing `features`
means none.
Protocol v8 uses four-byte big-endian framing with bounded UTF-8 JSON control
frames and tagged raw binary output frames. Requests (`op`): `ping`, `own`,
`prepare_handoff`, `create_pty`, `create_pipe`, `list`, `get`, `wait`,
`signal`, `set_metadata`, `write`, `resize`, `control` (atomic interaction
promotion), `input`, `snapshot`, `read_rows`, `rename`, `replay`, `subscribe`
(replay-to-live, with title, resize, controller and exit events),
`terminate` and `shutdown` (destructive).

A request the daemon cannot parse is answered with
`Error { message: "unsupported request: <op>" }` for an unknown `op` (or
`"invalid <op> request: ..."` for bad fields) instead of dropping the
connection, once the token has been checked. Clients can therefore probe for
a request.

`Pong` and the registration carry `features` (required), the daemon's additive
capabilities. Protocol 8 needs none, so the list is empty. Later additive
changes, such as a new request or field older clients can ignore, extend
`features` and keep the protocol version. Only breaking changes bump
`PROTOCOL_VERSION`, which clients reject on mismatch.

Registration is written atomically with private permissions and contains an
instance ID, PID, protocol version, features, socket path, and random credential. A
Expand Down Expand Up @@ -206,6 +283,7 @@ registration, leaving the rest to a later sweep. The sweep checks liveness
through the registered process object.

OpenCode chooses a fresh UUID runtime directory for each server, independent of
the database. It starts the daemon only when the first terminal is created.
the database. It starts the daemon only when the first terminal or pipe
process is created.
Only an explicit restart handoff descriptor lets a replacement server reuse
the previous daemon's runtime directory and claim its ownership.
Loading
Loading