waos-dev-protocol

What cargo waos and a running WaOS say to each other: the messages of one run, how they are framed on a stream, and the Unix socket on this machine that carries them. The connection is the run (the design's decision 29): cargo waos run connects, sends the program's id and its component, and reads what it writes until it ends; closing the connection, by Ctrl-C or the terminal closing, stops the program, and a later run of the same id replaces it. A run is the program its id names (decision 11 of docs/proposals/2026-10-23-permissions.md), which WaOS runs with that program's settings and folders, installed or not. There is no stop message. waos open <file> --program <id> connects the same way and sends one Open, files to open with the program the id names, which WaOS answers Opened or Refused (decision 3 of docs/proposals/2026-10-29-opening.md, until programs register what opens them). cargo waos screenshot connects the same way and sends one Screenshot of the program an id names, which WaOS answers Screenshots, a WindowPicture for each of its windows, numbered from 1 in the order they opened, with the title the program gave it, its size in physical pixels, whether it is in sight, and its last picture as a PNG, none before it showed one; cargo waos tap, type, key and scroll send one Input to a window of the program, by its number, a Tap or a Scroll at a point in the window's physical pixels from its top-left, Text to commit into what it edits, or a Key or a chord by name (cmd+s), which WaOS answers InputDone once the window shows its next picture, saying whether a new one came. Both are answered Unreached and why while no run of cargo waos run runs the program, for a program the library opened among them, which no tool reads or drives (the design's decision 60), and for a window the program does not have, a point outside the window, text with nothing in the window edited, and a chord naming no key. The socket is in the user's own folder, so the system's file permissions decide who may connect (decision 30); the network transport for phones carries the same messages.

• Takes: a program's id, its waos-package ProgramId, and its component, from cargo waos; a program's id and files to open with it, from waos open; a program's id with a screenshot or an input to one of its windows, from cargo waos; what the program writes and how it ends, its windows' pictures and what came of an input, from the WaOS app; a tokio runtime, on both sides.
• Provides: ToWaOS and FromWaOS, the messages, with Input, WindowPicture and Unreached; Connection, which agrees on the protocol's number with the other side first (PROTOCOL, agree_on_protocol), then sends and receives them as frames over a stream, split into a half that sends and one that receives when one task writes a program's output while another watches for the close; socket_path, where a WaOS listens on this machine; Listener, the WaOS side's end, which makes the socket's folder, replaces a socket file a WaOS that died left, refuses to start while another WaOS answers, and removes its file when dropped.
• Used by: waos-cli, for cargo waos run, screenshot, tap, type, key and scroll, and the WaOS app, which serves them and is waos open.

The socket's path: ~/Library/Application Support/WaOS/dev.sock on Apple's systems; $XDG_RUNTIME_DIR/waos/dev.sock elsewhere, or ~/.local/share/waos/dev.sock without one. The folder is made for the user alone (0700), and the socket file too (0600). macOS allows a socket path 103 bytes long, so a user's name may be 50 bytes.

A frame: a four-byte little-endian count of the message's bytes, then the message as postcard encodes it, a component, a program's output and a window's PNG as strings of bytes (serde_bytes), which postcard writes as it writes a Vec<u8>, so the encoding is the one of a sequence of bytes, read in one copy. Either side refuses a frame over 256 MiB, the receiver on the count alone, before it allocates anything: a component is megabytes, a debug build tens of them, and a count beyond that is a stream that is not ours. After a frame cut short or refused, the connection is done. A variant's place and a field's place is its encoding, so a change to a message adds at the end, and anything else raises the protocol's number; the screenshot and the input, added at the end, raised it to 3 all the same, so a WaOS of an earlier build refuses a cargo waos that may send them by number rather than at a message it cannot read. A message's Debug leaves out the text typed into a program, which may be a password, and writes a component's and a PNG's sizes rather than their bytes.

The first frame each way is that number, PROTOCOL, outside the messages' encoding: a count of four, then the number little-endian, the one shape every build reads. Each side sends its own and reads the other's before anything else; when they differ, each ends the connection with an error naming both numbers, which cargo waos prints, so a cargo waos and a WaOS of different builds find out rather than misread each other.

On Windows the crate carries the messages and Connection, but no transport: its named pipe is step 11.