Wire changelog

Wire-protocol changelog

TL;DR. Wire-format change log for the phux protocol; the top entry’s version must match PROTOCOL_VERSION in phux-protocol. CI gate spec-version-sync enforces this.

Newest version is at the top. The top entry’s <major>.<minor>.<patch> must equal PROTOCOL_VERSION in crates/phux-protocol/src/lib.rs; just docs-check enforces it.

VersionDateNotes
0.2.0-draft.112026-05-30phux-h9s (ADR-0021 §3): KILL_COLLECTION { collection: CollectionId, name: str } command appended to the §5.1 catalog at tag 0x0a (after CREATE_SESSION’s 0x09). The teardown counterpart to CREATE_SESSION: destroys the named session under collection, tearing down every Terminal it owns in one round-trip — the same effect as a KILL_TERMINAL per pane, but resolved server-side rather than over N client round-trips. Reply rides the existing COMMAND_RESULT { OK } envelope (no new CommandValue; the async TERMINAL_CLOSED frames confirm teardown), issued as soon as the teardown begins. An unknown collection is refused with ERROR { INVALID_COMMAND }, an unknown name with ERROR { SESSION_NOT_FOUND }; v0.1 servers host only the default CollectionId(1). Backs phux kill SESSION, collapsing its prior N KILL_TERMINAL round-trips into one (window / pane / @id targets keep the per-KILL_TERMINAL path). No existing bytes changed; additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.102026-05-29phux-fdh (ADR-0021 §3): CREATE_SESSION { collection, name, command: optional<list<str>>, cwd: optional<str> } command appended to the §5.1 catalog at tag 0x09 (after ROUTE_INPUT’s 0x08). Creates a named session under a collection and seeds its primary pane without attaching, subscribing, or resizing — the create-only counterpart to the always-attaching ATTACH { CreateIfMissing } path. The server allocates the session + seed pane atomically, so two concurrent CREATE_SESSION for the same name cannot both succeed (closing the GET_STATE→ATTACH TOCTOU window the v0.1 client-side always-new logic carried). Reply rides the existing COMMAND_RESULT { OK_WITH(TERMINAL_ID(..)) } envelope carrying the seed pane’s TerminalId, asynchronously correlated by request_id (the same shape SPAWN uses, session-level); no new CommandValue variant — TerminalId tag 0x00 is reused. A name already in use or an unknown collection is refused with ERROR { INVALID_COMMAND } (create-only, never create-or-attach; v0.1 servers host only the default CollectionId(1)). Backs phux new --json (create + print id, no attach). No existing bytes changed; additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.92026-05-29phux-8yl (ADR-0022 §2): GET_SCREEN gains a trailing additive cells: bool field (one byte, appended after request_scrollback; an absent byte on a pre-phux-8yl body decodes as false, so no existing bytes change). When true, the COMMAND_RESULT { OK_WITH(JSON(..)) } reply’s ScreenState carries a new additive cells? array: per-cell OSC-133 semantic marks + styles for the viewport, sparse (only cells with a non-default style or a semantic mark, row-major, wide-cell tails skipped). Each CellInfo is { col, row, semantic?, style }; semantic is present only for shell-integration input / prompt cells (libghostty’s default output collapses to absent); style carries the bool attribute set (bold/faint/italic/underline/blink/inverse/invisible/strikethrough/overline) plus tagged fg/bg ({ kind: "default" | "palette" | "rgb", … }). ScreenState.schema_version bumps 2 → 3; cells is serde-default + skip_serializing_if (a cells = false snapshot serializes to exactly the pre-phux-8yl shape, no key), so a v2 consumer ignores it. Backs the new phux snapshot --cells flag. Additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.82026-05-29phux-o1v (ADR-0022): GET_SCREEN gains a trailing additive request_scrollback: optional<u32> field (presence-byte + u32, appended after terminal_id; no existing bytes change). None reads the viewport only (the prior shape), Some(0) reads all retained history, Some(n) reads the most-recent n history rows. Requested history rides the existing COMMAND_RESULT { OK_WITH(JSON(..)) } reply in a new additive ScreenState.scrollback[] field (oldest first, right-trimmed); the server reads history cells in place (Point::History grid refs), so the read stays side-effect-free. ScreenState.schema_version bumps 1 → 2; scrollback[] is serde-default so a v1 consumer ignores it. Backs the new phux snapshot --scrollback[=N] flag (bare flag = all). Additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.72026-05-29phux-3j3 (ADR-0022): ROUTE_INPUT { terminal_id, event: InputEvent } command appended to the §5.1 catalog at tag 0x08 (after GET_SCREEN’s 0x07). InputEvent tagged union allocated (Key = 0x00, Mouse = 0x01, Focus = 0x02, Paste = 0x03), reusing the INPUT_KEY/INPUT_MOUSE/INPUT_FOCUS/INPUT_PASTE atom encodings. Delivers an already-built input event to a Terminal without an ATTACH, subscription, or resize — the write counterpart to the side-effect-free GET_SCREEN read; unlike the attach-then-INPUT_KEY path it never resizes the live pane to the caller’s viewport. Reply rides the existing COMMAND_RESULT { OK } (or ERROR { TERMINAL_NOT_FOUND } for an unknown id). Allowed for primaries; input fire-and-forget per §9 (a full mailbox drops the event but still acks OK). No existing bytes changed; additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.62026-05-29phux-oki (ADR-0022 §5): GET_SCREEN { terminal_id } command appended to the §5.1 catalog at tag 0x07 (after RUN_HOOK’s reserved 0x06). Reply rides the existing COMMAND_RESULT { OK_WITH(JSON(str)) } envelope carrying a serialized ScreenState ({ schema_version, pane, cols, rows, cursor?, lines[] }) — the stable agent-surface read contract; no new CommandValue variant. Side-effect-free: the server walks its own emulator grid, so unlike ATTACH_TERMINAL it neither subscribes the caller nor resizes the Terminal (safe to poll). Allowed for viewers. No existing bytes changed; additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.52026-05-28phux-k61 (ADR-0021): the generic COMMAND / COMMAND_RESULT envelope (§5) is wire-allocated. proto discriminants COMMAND = 0x31 (C→S), COMMAND_RESULT = 0xC2 (S→C), from the control-plane reserved ranges (Appendix B). Command tagged union follows the §5.1 catalog order (SPAWN = 0x00 … RUN_HOOK = 0x06); v0.1 implements KILL_TERMINAL = 0x03 and GET_STATE = 0x05 only — other tags decode as UnknownEnumValue. CommandResult allocated (Ok = 0x00, OkWith(CommandValue) = 0x01, Error(ErrorCode, str) = 0x02); CommandValue allocated (TerminalId = 0x00, CollectionId = 0x01, State(SessionSnapshot) = 0x02, Json(str) = 0x03, Bytes = 0x04); StateScope allocated (Server = 0x00). CommandValue::State reuses the existing SessionSnapshot wire shape. Control verbs route through this envelope; phux new reuses ATTACH { CreateIfMissing } rather than a command. No existing bytes changed; additive draft bump (PROTOCOL_VERSION stays 0.2.0).
0.2.0-draft.42026-05-27phux-4rj: ClientCapabilities HELLO payload appends images: bitset<ImageProtocol>, kbd_protocols: bitset<KeyboardProtocol>, and hyperlinks: bool after the existing color and layers bytes. Server downsampling now gates sixel/kitty/iTerm2 image escapes, kitty keyboard APC replies, and OSC 8 hyperlink framing directly from the negotiated ClientCapabilities. The phux-i58 TLV migration remains out of scope.
0.2.0-draft.32026-05-27phux-dmb: RolePolicy added to ATTACH and ATTACH_TERMINAL as an additive field. Terminal subscriptions now have PRIMARY / VIEWER roles; only the primary may send input or terminal-mutating commands. TakeoverPolicy::DELIBERATE is required to displace an existing primary; silent takeover is forbidden.
0.2.0-draft.22026-05-27phux-4li.10: L1 Terminal lifecycle frames wire-allocated (§7.2.1). C→S discriminants SPAWN_TERMINAL = 0x22, TERMINAL_RESIZE = 0x23; S→C TERMINAL_CLOSED = 0xA1 (honours the spec-only reservation from §7.2), TERMINAL_SPAWNED = 0xA2. SpawnResult and SpawnError tagged unions allocated (Ok = 0x00/Err = 0x01 for SpawnResult — the convention extends to future Result<T, E> reply frames; CollectionNotFound = 0x00/SpawnFailed(str) = 0x01 for SpawnError, both #[non_exhaustive]). TERMINAL_CLOSED.exit_status: optional<i32> is a deliberately compact subset of §10.1’s ExitStatus tagged union — Some(n) for _exit(n), None for signal kills and unknown causes; the wider tagged union grows in a follow-up if needed. TERMINAL_RESIZE is per-Terminal PTY resize, sent in addition to VIEWPORT_RESIZE. Appendix B reserved-range guidance updated for 0x24..=0x2F and 0xA3..=0xAF. Server / client wire-up lands in follow-up tickets; the codec is wire-complete on this commit.
0.2.0-draft.12026-05-27phux-4li.2: L3 metadata frames wire-allocated. C→S discriminants GET_METADATA = 0x50, SET_METADATA = 0x51, DELETE_METADATA = 0x52, LIST_METADATA = 0x53, SUBSCRIBE_METADATA = 0x54; S→C METADATA_CHANGED = 0xD0. Scope tagged union allocated (Terminal tag 0x00, Collection tag 0x01, Global tag 0x02). METADATA_CHANGED carries the new value inline (optional<bytes>) — supersedes the earlier “consumers re-GET after notification” sketch. ClientCapabilities.layers now wire-encoded as a trailing u8 after color_support (additive trailing field per SPEC §6, no version bump beyond the L3 allocation). CollectionId(u32) allocated; L2 (which defines its full tagged-union shape) is still TBD. Reply path for GET/LIST defers to the COMMAND_RESULT envelope (§11).
0.2.0-draft2026-05-27phux-vp0.4: TerminalId becomes a tagged union (LOCAL { id: u32 } tag=0, SATELLITE { host: str, id: u32 } tag=1) per ADR-0016. Every TerminalId field on the wire gains a 1-byte tag prefix; the reference snapshot fixtures (§16) re-baseline accordingly. ErrorCode::UnsupportedSatelliteRoute = 106 is added (was already SPEC-reserved). v0.1 servers only construct LOCAL; v0.1 decoders MUST accept SATELLITE and, if not a federation hub, reply ERROR { UnsupportedSatelliteRoute }. PROTOCOL_VERSION bumped 0.1.0 → 0.2.0 (pre-1.0 wire break).
0.1.0-draft.72026-05-26L1 vocabulary cascade Wave C (phux-vp0.2). §7 catalog reorganized by tier (proto / L1 / L2 / L3); §7.L1 messages renamed PANE_* → TERMINAL_* and pane_id → terminal_id per ADR-0016 (wire bytes unchanged). §7.3/§7.4 declare L2 (Collections) and L3 (Metadata) as reserved tiers with TBD discriminants. §6.1 HELLO gains layers: bitset<Layer> inside ClientCapabilities / ServerCapabilities (Appendix A field-tag extensibility keeps the wire compatible). §10 collapses Sessions/Windows/Panes/Layout/Focus into §10.1 Terminal lifecycle and §10.2 Viewport resize; the demoted TUI vocabulary lands non-normative in new §17. §6.2 reclaims the CC_FRONTEND capability slot per ADR-0017. §14 renames PANE_NOT_FOUND → TERMINAL_NOT_FOUND (numeric discriminant 104 preserved). §16 conformance restructured per-tier (16.0 common, 16.1 L1, 16.2 L1+L3, 16.3 L1+L2+L3). No wire bytes changed; no version bump.
0.1.0-draft.62026-05-26Editorial: §7.1 / §7.2 message catalogs grow a Tier column mapping each message to its ADR-0015 layer (proto / L1 / L2 / tui→L3 / cmd); legend and tier-notes added. Previews the layered restructure that will rename PANE_* → TERMINAL_* (ADR-0016) and demote WINDOW_* / LAYOUT_CHANGED / FOCUS_CHANGED out of the wire (ADR-0017). No bytes changed.
0.1.0-draft.52026-05-26Editorial: §7.1 / §7.2 message catalogs grow a Status column tracking reference-implementation coverage (informative, non-normative). No wire change.
0.1.0-draft.42026-05-26Post-ADR-0013 cleanup: §2 Frame term re-anchored on per-pane seq; §6.2 inline comment on deprecated RenderingMode; §11.1 ADR cross-reference points at ADR-0013; §12 flow control rewritten for PANE_OUTPUT / per-pane seq (was PANE_DIFF / frame_id); Appendix B reserved-range guidance drops DiffOp.
0.1.0-draft.32026-05-25§8 rewritten for bytes-on-wire pane state sync; PANE_DIFF superseded by PANE_OUTPUT; PANE_SNAPSHOT carries vt_replay_bytes; §6.2 capability downsampling described as a server-side VT byte stream rewrite; §13 replay sequence and §16 conformance updated. ADR-0013.
0.1.0-draft.22026-05-24§7.7, §9, §10.5 revised to mirror libghostty input/OSC APIs. ADR-0006.
0.1.0-draft2026-05-24Initial draft. Subject to change.