Scripting and embedding

Four ways to drive the agent from something other than a person at a terminal.

Line mode: one turn per line

With piped standard input, revolve runs one turn per input line and prints to standard output.

printf '/help\nWhat is 2+2?\n' | revolve

Nobody can answer a permission prompt here, so an uncovered command is denied with a note and the model is told it was refused. --allow-all runs it anyway, and never overrides a deny rule.

JSON mode: one turn, one object

--print <message> --json runs exactly one turn and writes a single JSON object to standard output. Nothing else goes there, so | jq .answer needs no filtering: startup notes, tool calls, token counts, errors and any permission prompt all go to standard error, where a script reads or discards them.

$ revolve -p "What is 2+2? Answer with the number only." --json math 2>/dev/null | jq .
{
  "protocol": 25,
  "name": "math",
  "cwd": "/home/x/project",
  "model": "anthropic:claude-haiku-4-5",
  "outcome": "done",
  "message": "",
  "answer": "4",
  "tool_calls": [],
  "input_tokens": 19109,
  "output_tokens": 5
}

outcome is the field to branch on. limit means a turn budget stopped the turn where it stood: the answer may be missing, half-written, or wrong about its own completeness, and reading it as a finished result is the mistake this field exists to prevent. error means the turn never produced a result — a missing config, a provider that refused, a session that died — and the process exits non-zero as well, so $? and the object agree.

A session name works here as everywhere else, which is what lets a script run several turns in one conversation.

RPC mode: a conversation over a pipe

--rpc speaks one JSON object per line in and one per line out. It is what an editor or a wrapper program talks to. The first line out is {"event":"ready","protocol":25}, and protocol is bumped whenever an event name or field set changes.

Requests, on standard input

Events, on standard output

printf '{"type":"user_message","text":"What is 2+2? Answer with the number only."}\n' | revolve --rpc
{"event":"ready","protocol":25}
{"event":"info","text":"context: 33 kB per turn"}
{"event":"text_delta","text":"4"}
{"event":"context_usage","text":"context 17k/60k (28%)"}
{"event":"info","text":"17229 in, 5 out"}
{"event":"turn_outcome","outcome":"done","message":"","input_tokens":17229,"output_tokens":5}
{"event":"turn_ended"}

The round trip to get right is ask_user: read the id out of the event and send a permission request carrying that same id. A client that never answers deadlocks on the first tool call that asks. Ids count up from 1 for the life of the process and are never reused. Answering an id that is not open is an error line rather than a fatal one, and so is any other malformed request — a bad line never kills the session.

Closing standard input is not the same as shutdown: the mode stops reading requests but keeps emitting until the running turn has ended, so a plain pipe works for a script. An unanswered prompt is denied at that point rather than hanging forever.

Because prompts reach the client, RPC mode counts as interactive in the sense the permission engine means, the way the terminal does and the line mode does not.

Detached sessions

A session normally lives and dies with its front end. revolve detach starts one that does not: the agent runs as its own process, listening on a unix socket, and a front end attaches whenever there is someone to watch.

revolve detach review          # start it in the background and return to the shell
revolve agents                 # what exists, and what is running behind it
revolve attach review          # bring the terminal to it
revolve attach review --rpc    # watch the same session raw, as JSON lines
revolve stop review            # stop that one; stop --all stops every running session

The socket lives in $XDG_RUNTIME_DIR/task-agent/, or next to the session files when that variable is unset, and is removed when the session stops. revolve agents lists the named sessions of this directory — name, model, when the session file was last written, whether a process answers its socket — followed by every running session of any other directory. Liveness is decided by connecting, so a socket file with nobody behind it reads as stopped and is deleted on the spot.

A session that dies is started again by whoever started it. The process that spawned a detached session — an agent that called StartAgent, or the window that opened it — waits on that process, and an abnormal exit (a panic, or a kill by the OOM killer) is answered by starting it again on its own session after 250 ms, then a second, then five seconds. After the third try it is left down. A session that exits normally, including one ended by revolve stop, is never started again, and neither is one whose socket another process has taken over in the meantime — the socket is the lease, since bind refuses an address that still answers. Every restart writes a line into that session's own log beside its socket, so a session that came back says so. revolve detach returns to the shell and leaves no supervisor behind, and the cron line revolve schedule writes is what brings a session back that nobody was watching.

A detached session speaks the same vocabulary as RPC mode, one connection per client, so anything that can drive --rpc can drive a detached session by connecting to its socket. Several clients may attach at once and every event goes to all of them; closing standard input turns a watcher read-only instead of ending it, so a script can tail a session it is not driving.

The snapshot

What a socket adds over a pipe is what a client gets when it arrives in the middle of things. Right after ready, the session sends one snapshot line, because a client arriving mid-conversation cannot infer a state from a stream of edges.

Everything after that is the live stream. A client that disconnects changes nothing: a turn in flight runs to its end and its events stay in the tail for whoever attaches next.

The pending prompts are the point of it. A permission prompt has to reach a human, and no rule and no --allow-all may answer in his place — so with nobody attached the prompt is queued and the turn blocks there for as long as it takes. It reaches every client attached when it is raised and waits in pending for every client that arrives later. Nothing expires and nothing is denied on a timer. A session stopped while a turn was running says so with an error line before it quits.

Embedding it in a program

The agent is a library crate of its own, so a program can hold it instead of shelling out to it. The workspace has three members: task-agent in core/ is the agent with its tools, providers, sessions and every terminal-free front end; revolve in tui/ is the terminal binary; revolve-gui in gui/ is the window. A host depends on task-agent alone and therefore links no terminal library at all — ratatui, crossterm and idet are named nowhere in core/, which is a rule the dependency direction enforces rather than a habit.

task_agent::agent::Agent takes user input over an mpsc channel and answers with AgentEvents — the same seam every front end sits behind — and task_agent::files::Files is the sandbox the tools reach the disk through. The window is the proof that the seam holds: revolve-gui owns no agent at all, it starts a detached session and attaches to it, so everything it knows arrives as an AgentEvent and everything it says leaves as a String.

A host that already owns the text — an editor with unsaved buffers — hands in a FileHost rather than letting Files read and write the disk behind its back:

pub trait FileHost: Send + Sync {
    fn read(&self, path: &Path) -> Option<String>;
    fn write(&self, path: &Path, content: &str) -> Option<Result<(), FileError>>;
    fn editor_info(&self) -> Option<String> { None }
}

None means "not mine" and the disk answers, which is what makes partial ownership work: a host holds the documents the user has open and stays out of the way for everything else. Reads, writes, the content hash guarding Edit against unread files, and the Grep walk all go through it, so the model sees what the user sees rather than the last saved version. Files::set_host installs one and Files::set_root moves the sandbox at runtime, for a host whose project changes while the process keeps running. A host that answers editor_info also gains the EditorInfo tool, offered to the model only when a host actually answers it.

A host that takes a write has to put the text on the disk as well, not only into its own buffer, because the agent verifies its own work by running the build and the compiler reads files.