Agent-First Terminal v0.1.0

An agent that can run a command and read its output still cannot hand you the terminal. The moment a program wants a password, redraws an alternate screen, or takes fifteen minutes and needs someone to glance at it, “capture stdout” stops being the right shape.

Agent-First Terminal is the runtime underneath that: real PTYs, several at once, structured enough for a program to drive and live enough for a person to sit in.

Two actors, one terminal, and the person wins

The interesting problem is not opening a PTY. It is that an agent and a person are both typing into one, and neither should have to guess whose turn it is.

Input goes through leases, shared or exclusive, with a TTL — and a human preempts immediately. Not by asking, not on the next lease boundary: the moment a person types, the automated actor holding the lease loses it. That ordering is the whole design, because the alternative is a person fighting an agent for a prompt, and losing on latency.

Writes are actor-aware and atomic, so two actors cannot interleave halfway through a line.

Secret input publishes nothing

A password prompt inside a shared terminal is the sharpest version of the problem. If the session is being streamed, echoed, snapshotted and multiplexed, “just don’t echo it” is not enough — the bytes are still in a screen snapshot and an event stream that other actors are reading.

Secret mode suspends every non-human actor for the duration and publishes nothing derived from those bytes. No snapshot, no event, no scrollback entry. The person ends the window; only then does normal publishing resume.

Snapshots, not a scraped screen

The runtime exposes structured VT screen snapshots and a multiplexed event stream rather than a raw byte river with a parser bolted on each consumer. A subscription to scrollback is bounded, so a long-running build cannot make a viewer’s memory the runtime’s problem.

Resize, foreground process-group signals and typed lifecycle operations are part of the contract, because a terminal you cannot resize or Ctrl-C is not a terminal you can actually use.

The core library carries no async runtime and no HTTP dependency. Depending on this crate needs no feature at all; the api feature exists only for the standalone server. cargo install agent-first-terminal without it installs nothing and says so, naming the flag, rather than leaving a working-looking install with no executable behind it.

Three ways to reach the person

The CLI can open the same live runtime as a trusted local DOM-rendered window, and the two other deliveries exist because a window is not always possible:

• --mode window opens here, on this machine’s display.
• --mode link returns a LAN URL that needs no command on the receiving device. It is a bearer capability with control of every session in the runtime, so it travels through a trusted channel and never faces the Internet. The page is AFUI’s, under AFUI’s idle-plus-grace attention policy.
• --mode session publishes the runtime and opens nothing. That is the shape for a display-less machine, and for a person who is somewhere else — a session bounded by a window nobody is watching ends the moment someone closes it, so here the command is the bound.

One detail worth knowing, because it is the difference between a tidy session tree and a pile of orphaned windows: every PTY the runtime opens inherits the process environment, including AFUI_DELIVERY=session when afterminal itself was reached through link or session. A sub-command with a UI of its own, run inside that shell, publishes into the existing registry instead of opening a window on a machine nobody is looking at. --mode window leaves the variable untouched, so a value you exported yourself is never overwritten.

For programs

The same multi-session runtime is available over a loopback-only, bearer-protected HTTP API with a committed OpenAPI 3.2 contract, drift-tested against the code. An external controller can open sessions, attach midway to sessions an already-running server owns, write input, resize, signal, and read the event stream.

The runtime stays independent of any UI host and of any application-specific task model. AFUI hosts the CLI’s window; it does not own the runtime.

Getting it

Homebrew and Scoop packages are not published for this spore yet.

$ cargo install agent-first-terminal --locked --features api