Interactive sessions

The PTY session host, wire protocol library, and generic attach client behind donmai's live, attachable terminal sessions.

Most donmai sessions are headless: a session clones a repo, spawns a provider over pipes, consumes normalized activity events, and tears down. Interactive sessions are a byte-accurate sibling to that path - a session runs under a real pseudo-terminal (PTY), and another device can attach to it live: watch the actual terminal screen, drive keystrokes, resize the viewport, and reconnect without losing history.

Three OSS packages provide this, and they compose into one contract:

ptyhost - spawns a command under a PTY, owns the master file descriptor, and is the snapshot authority: it feeds every byte through a headless terminal emulator so a late-joining viewer gets the current screen instead of a replay from byte zero.
attachwire - the framing and codec library for interactive-attach-v1, the wire protocol every leg (host, relay, viewer) speaks: binary frames, two independent sequence namespaces, a terminal-escape sanitization allowlist, and a degraded HTTP fallback lane.
attachclient - a generic outbound client that dials a relay URL with a bearer token and runs one session's host leg. It is brand-neutral: the composing binary supplies the URL and the token, and the client never opens an inbound listener.

The boundary: what's OSS and what needs a relay

The OSS stack includes a complete local standalone path: spawn a ptyhost.Session and use AttachLocal with attachwire - no network, relay, token, or attachclient - for the same live screen, input path, and reconnect-safe resume. attachclient is instead the complete outbound host leg for remote or second-device attach; its required AttachURL, TokenSource, and Session connect to a compatible relay endpoint.

Attaching from a second device therefore needs a relay: something reachable by both the host (which only ever dials out) and the viewer (which dials in). That relay - and the multi-writer arbitration policy, session lifecycle, and control-plane token minting that sit in front of it - is not part of this repository. The wire protocol these packages currently speak is public but proposed and not yet ratified: attach to a compatible relay URL with a bearer JWT (aud claim "relay"), and negotiate the current interactive-attach-v1 draft.

fig 1.0rendered in-browser

fig 1.0 - the OSS host stack, the standalone loopback path, and the one thing it dials out to.

Proposed protocol: frozen vs draft

The canonical specification still has Status: Proposed and both ratification sign-offs are pending. It tags normative rules as either v1-frozen or v1-draft to mark the intended stability boundary. Until ratification, v1-frozen text may still change in place during final sign-off; after both sign-offs, changing a frozen rule requires a new protocol version. Draft rules remain amendable within v1 through the specification's review process.

The binary frame envelope, event-type registry, sequence namespaces, sanitization scope, and auth claim set are currently marked v1-frozen. snapFormat details, backpressure thresholds, and degraded-lane batch sizing remain v1-draft. Implementers should pin the specification revision they test against rather than treating the present proposal as an immutable compatibility commitment.

Sections

PTY session host

ptyhost: spawn-under-PTY, the ring buffer, the headless-VT snapshot authority, and the standalone local attach.

Wire protocol

attachwire: frame format, sequence namespaces, control messages, the sanitization allowlist, and backpressure.

Attach client

attachclient: RunHost, the Session interface, carrier fallback, and reconnect discipline.

If you're building a Swift viewer, CLI, or other tooling against this protocol, donmai's kit system (a buildpack-style, declarative toolchain provisioner) ships a general-purpose Swift foundation kit (default/swift in the donmai-kits repository): it detects Package.swift, provisions a pinned Swift 6 toolchain, and provides build/test/format commands plus a Swift-conventions prompt fragment and testing skill. It is a general Swift Package Manager kit, not specific to this protocol - there is no attach-specific Swift package in this repository today.