Daemon protocol
Frontends drive the daemon with rho's protocol: JSON-RPC 2.0 over the daemon's Unix socket, or its named pipe on Windows. This page is the reference for client authors. Rust clients can use the rho-protocol crate, whose Client handles framing, the handshake, and notifications. Clients in other languages can generate their types from the protocol's JSON Schema, crates/rho-protocol/schema/protocol.json, which lists every method's params and result, every notification, and every error code, keyed by its code.
Connection
Connect to the daemon's daemon.sock, or on Windows its pipe \\.\pipe\rho-daemon-<home id> (see Socket and permissions). Every message is one JSON-RPC 2.0 object on one line, UTF-8, ending with \n. A line may be at most 16 MiB; a longer one ends the connection with an InvalidRequest error. Request ids are integers or strings, and clients send no notifications.
The first request must be rho/hello. Any other request before it gets HandshakeRequired. The daemon accepts the handshake when the client's protocol version is compatible with its own, and otherwise answers VersionMismatch, whose data names both versions and which side has to change: fix is restart_daemon when the daemon is the older side, and update_client when the client is. With restart_daemon, restart says what restarting the daemon would cost at that moment: in_progress counts what it would interrupt (jobs queued, running, or waiting for input, logins under way, and sessions with work of their own), and clients counts the other connections whose handshake the daemon accepted, which it would disconnect. A client can offer the restart with those counts, and can replace a daemon that reports 0 for both without asking, as rho's own frontends do (Versions). A refused connection stays open for another rho/hello.
A hello also declares what the connection is for and what it does (#1780), which hold for the connection's life:
roleisfrontend, a person's client such as a terminal UI or an editor's agent host, oragent, session control that starts, prompts, and watches sessions for a model, asrho mcp serveand thesessionstool do.capabilitieslists what the connection does. The only one isanswer: answering a session's approvals and questions withrho/session/answer, holding their timeouts withrho/session/hold, and acting on a surface withrho/session/surface_action. Any of these methods from a connection that did not declare it getsCapabilityRequired, and nothing is done.
A role bounds the capabilities a hello may declare: an agent may not declare answer, and a hello that does gets InvalidParams and is not accepted. So a turn that asks waits for a person, whichever agent drives the session. A role is declared, not proven. The socket is private to its user and any of that user's processes may declare any role, so this keeps a client to its part; it does not confine a process that can open the socket itself.
rho/session/answer, rho/session/hold, and rho/session/surface_action are the only methods that need a capability (answer, which only a person's frontend connection may declare). Every other method is open to both roles, and that is intended: an agent connection may change the daemon's settings with rho/config/set and the other settings methods, and reconfigure a session with rho/session/configure. Agents legitimately tune the sessions they run, and since a role is declared, not authenticated, refusing these methods would stop no process that wanted to call them. Custom per-method permissions for connections may come later, after the beta (#1810).
A hello may also name the client's build: which wire it speaks, as an opaque string. While the protocol version stays at 0.1 until the beta, two builds of one version can speak different wires, and this tells them apart. The rho-protocol crate sends the hash of the schema it was built with, so two builds with the same schema have the same id; compare ids only for equality, since they have no order. When the hello names a build other than the daemon's, the daemon still accepts it, and its answer carries skew: requests may fail, and skew.restart says what restarting the daemon would cost at that moment, counted as for VersionMismatch, without the connecting client. A hello with no build gets no skew.
A client and a daemon of different versions still have to read this much of each other, so it is held steady at every version, also while the protocol is unstable: the daemon reads protocol from a hello before anything else in it, and protocol and the data of VersionMismatch only ever gain optional fields.
After the handshake the daemon runs a connection's requests concurrently and answers each one when it finishes, so responses can arrive out of order; pair them with their requests by id. Send a request that depends on another only after that one's response arrives.
When the client stops sending, the daemon answers every request it has already read, then closes the connection. When the daemon stops or restarts, it first sends rho/session/detached for every session the client follows, then answers the requests it has read and closes. A restarting daemon keeps its socket, so a client that connects again waits until the restarted daemon answers its rho/hello. A client that has stopped reading while the daemon closes its connection is dropped once a message has waited 1 second.
Methods
| Method | Params | Result |
|---|---|---|
rho/hello | protocol ({major, minor}), client ({name, version}), role (frontend or agent), capabilities (optional; answer), build (optional) | The daemon's protocol and daemon ({version, pid, build}), and skew ({restart}) when the hello named another build. |
rho/daemon/status | pid, version, protocol, started_at, uptime_secs, jobs (jobs queued, running, or waiting for input), in_progress (how many things a stop or restart would interrupt: those jobs, logins under way, and sessions with work of their own), socket, credential_store: the credential store the daemon keeps provider credentials in, and upgrade, present once the daemon's executable was replaced: the replacement's version and waiting_for, how many things the upgrade waits for: jobs in progress, logins under way, and sessions with work of their own. | |
rho/daemon/stop | {}; the daemon then shuts down as described. | |
rho/daemon/restart | {}; the daemon then re-executes in place, interrupting the turns under way. | |
rho/session/new | cwd, environment, agent?, setup?, parent?, grant?, worktree? | Opens a new session whose workspace is cwd, an absolute path to an existing directory, and returns its session id and options (below). environment is the client's environment variables, an object of strings, which the session's commands run with (below). The session runs as agent, the id of one of the workspace's agents, as rho --agent takes it, or the default agent; one the workspace does not define gets SessionOpenFailed. setup holds the client's other choices for it (below). parent names the session whose turn starts this one, as an agent's sessions tool does: the new session's job records the job writing that session as its parent, and its turns wait for a slot in the shared budget as subagents do (sessions other sessions start). A session no job of the daemon writes records no parent, though the new session still shares the budget. grant is what the session may do through session control (below). worktree: true opens the session in a git worktree the daemon adds for it, on a new branch from the HEAD of cwd's repository, at cwd's place in it, and the response's worktree names its branch, its path, and its origin, the cwd asked for; a cwd in no git repository gets SessionOpenFailed. The daemon never removes the worktree (sessions in worktrees). |
rho/session/prompt | session, content, optional timeout_ms, environment, optional grant, optional idempotency_key, optional author | Starts a turn of content, a non-empty list of content blocks, whose commands and those of later turns run with environment, and returns the turn's id, turn, once the turn began: it saved its prompt, or, for /compact, its compaction started, or, for a session another session started, it has to wait for a slot in the shared budget. A session runs one turn at a time; a prompt while a turn is under way gets SessionBusy. A prompt that arrives while settings changes wait to apply starts its turn once they have, so the turn runs with them. With timeout_ms, the daemon cancels a turn still running that many milliseconds after it took the prompt, and the turn ends timed_out. A prompt that names an idempotency_key can be sent again (below). grant is what the turn may do through session control (below). author is person when absent; client marks a /workflow: start a client sends on the person's behalf, such as a workflow hub's, which the daemon runs without saving or showing a user message, and any other prompt sent as client ends before it began. |
rho/session/cancel | session | Cancels the turn under way, if any. The turn ends cancelled, or interrupted when the daemon is stopping; one already past its timeout_ms ends timed_out. |
rho/session/steer | session, text | Adds text to the running turn's next model request and returns its id once the turn accepted it. The steer applies at that request as a user_message whose steer is id; a turn that ends first drops it, so a client that never saw it apply can send it again. Gets NotSteerable when no model request is taking input, or the turn ended before it accepted the input. |
rho/session/unsteer | session, id | Withdraws steer id before it applies and returns its outcome: withdrawn when it was removed before it reached the conversation, delivered when the provider already took it (it still applies), applied when it is already in the conversation, or not_found when the running turn never accepted that id, as for another turn's steer or one a turn dropped when it ended. Gets NotSteerable when no model request is taking input. |
rho/session/attach | session, after?, environment, setup? | Follows the session's events (below), reopening an unloaded session with its commands in environment and with setup (below). Returns its stream, its workspace, the replay that follows (tail or reset) and how many events it holds (replay_events), its job state and the turn that state is of, how long that turn had run when the attachment began (turn_elapsed_ms, absent while no turn is under way), the input requests open now (inputs), its background work (below), its title, once it has one, and the session's options (below). |
rho/session/observe | session, after? | Follows the session's events as rho/session/attach does, for a client that only reads it, and returns the same response. It never loads a session: one the daemon has loaded is followed as an attach follows it, and a saved one it has not loaded stays unloaded. The daemon replays that one as its file keeps it, with how its last turn ended, without starting its MCP servers, OpenAPI sources, or hooks, then detaches the client with not_loaded; with no MCP server connected, that replay titles MCP tool calls by their names alone. It carries no environment or setup, since it opens nothing that would use them. A session that a subagent run under way is writing is followed through the run's stream: until the run has opened the session the observe is refused with SessionBusy, the stream's one turn is the run, and its turn_ended reports how the run ended (stop is always end_turn for an answer). Once the run ends, the client is detached with not_loaded, and a later observe replays the session the run saved. |
rho/session/detach | session | Stops following the session; no event of it arrives after the response. |
rho/session/answer | session, request, answer | Answers one of the turn's open input requests (below) and returns {} once the daemon has handed the answer to the turn. Needs the answer capability. |
rho/session/surface_action | session, surface, action, data_model? | Hands the session what the user did on an A2UI surface its ui tool showed (below) and returns {}. Needs the answer capability. |
rho/session/configure | session, change | Changes one of a loaded session's settings for its later turns and returns its options (below). |
rho/session/mcp | session | Reads a loaded session's MCP server inventory without waiting for its active turn (below). |
rho/session/mcp/catalog | session | Lists the prompts and resources a loaded session's MCP servers offer, without waiting for its active turn (below). |
rho/session/mcp/resource | session, server, uri, max_text_bytes? | Reads one resource from one of a loaded session's MCP servers and returns its contents (below). |
rho/session/mcp/complete | session, server, prompt, argument, value | Asks one of a loaded session's MCP servers for values of a prompt argument (below). |
rho/session/processes | session, output? | Reads a loaded session's background processes, and one's retained output, without waiting for its active turn (below). |
rho/session/background/list | sessions: each loaded session with background work, by session id: its session and its work (below). | |
rho/session/background/stop | session, work | Stops one item of a loaded session's background work and returns {} (below). |
rho/session/inspect | session, report | Reads a report about a loaded session between its turns: context (what fills the context window, by source), hooks (its hooks, read again from their files, and their recent activity), compaction (its compaction settings as token counts, what its compactions removed, and what the latest one did and cost), or provider_context (the provider-native context in its conversation that its model cannot be sent, the model that produced it, whether the session may switch to that model, and whether compacting could summarize the conversation first). The report it answers with is presentation data whose shape follows the rho version. A session in a turn is SessionBusy; an unloaded one SessionNotLoaded. |
rho/session/hold | session, request | Stops an open input request's timeout, so it waits for an answer (below), and returns {}. Needs the answer capability. |
rho/session/list | cwd?, cursor?, limit? | One page of the saved sessions, newest first: sessions and, when more follow, next_cursor (below). |
rho/session/rename | session, title | Saves the session's title and returns {}; clients attached to it receive title_changed. |
rho/session/delete | session | Deletes the saved session and the sessions it started, unloading it first, and returns {} (below). |
rho/job/list | jobs: every job the daemon knows, including those earlier daemons ran but not those of sessions it discarded unsaved, oldest first. Each has its id, kind (session, subagent, or workflow), state, workspace, and timestamps; the session it writes, absent for a workflow and for a subagent on another runtime; the parent job that started it, for a subagent, a workflow, or a session another session started; the grant of a session's turn under way or its last one, absent when it has no limit; the grant_limit that grant is held to, for a session that opened under a limit; the run id of a subagent's run, which names its artifact directory; the workflow_run it drives, for a workflow, and result_pending while that run's result has yet to reach its session; the error when it failed; the worktree a session works in, for one opened with worktree, whose path holds its workspace, and worktree_stale once that worktree went stale: still on disk, unused, and the job unchanged for 14 days; and, usually while it is queued, its queue place: the budget it waits on, that budget's limit, and its position, 1 for the next to start. A session job whose session the daemon has loaded, and a subagent job whose run is under way and has opened its session, also has live, what the daemon follows of it now: its title, once it has one; the model it runs on; turn_elapsed_ms while a turn is under way; its usage as the last usage event said, with no cost_usd_micros for a subagent, whose spend its parent session's counts, nor for a session the daemon reopened, until its next turn reports usage; and its open inputs, each answered with rho/session/answer. A client shows and answers what every job waits on from this list alone, without attaching; what a session's background work still runs after its turn ended is in rho/session/background/list. | |
rho/worktree/prune | dry_run? | Removes each session worktree that is safe to remove, its branch kept, or with dry_run only says which, and returns worktrees: one report for each session worktree still on disk, with its job, its worktree, whether it is stale, and its verdict by kind: merged (clean and merged into base; removed, or would be), in_use, dirty, unmerged (with base), or failed (with git's error). A verdict this client does not know reads as unknown. |
rho/auth/key | auth, key, environment | Checks the API key with the provider of auth profile auth, such as openai-api-key, and saves it (below). Returns {}, or, when the provider could not be asked, unchecked with its reason and a message. |
rho/auth/logout | auth, environment | Deletes auth profile auth's saved credentials (below) and returns {}. |
rho/auth/list | environment | auths: every auth profile a client can sign in to, the TUI's /login picker's and ACP's auth methods, each with its auth id, provider, a label for a picker, its kind (api_key or login), and its status (signed_in or signed_out). |
rho/auth/login | auth, flow?, environment | Starts auth profile auth's interactive login in the daemon and returns its login id; its prompt and its end follow as notifications (below). flow is browser, the default, or device_code. |
rho/auth/login_cancel | login | Asks the login to stop, which then ends cancelled, and returns {}; a login the provider already approved still saves and ends succeeded. |
rho/auth/choose_store | store, environment | Checks that credential store store (os or file) takes a temporary secret, saves it as the daemon's behavior.credential_store, and returns the new credential_store (below). |
rho/config/schema | Every agent setting: categories, settings (each a setting spec), and the file_only tables only a hand edit changes. | |
rho/config/register | client, settings | Declares the client's own settings, which the daemon then stores for it (below), and returns {}. |
rho/config/get | namespace | The namespace's revision, values, and errors; the connection then gets rho/config/changed for it (below). |
rho/config/set | namespace, layer, revision, changes, optional writer | Writes every change, or none, and returns the new revision (below). |
A prompt whose turn ends before it began returns an error instead of a result:
TurnEnded, whosedatais the turn's outcome:cancelledwhen a cancel arrived before the turn began,timed_outwhen itstimeout_mspassed first, orfailedwith the reason, such as unreadable provider credentials or a slash command the daemon does not run. Nothing is saved and the model is not called, except that a cancel or timeout that arrives while/agent:<name>rebinds the session waits for the rebind: the session stays rebound to the agent, and only the prompt is not saved. A turn that stopped unexpectedly fails withthe turn stopped unexpectedly; see the daemon log.DaemonStoppingwhen the daemon starts stopping while the prompt waits for its turn to begin.
A prompt that starts with a slash command resolves as it does in rho run: prompt templates, MCP prompts, /init, /create-agent (daemon sessions only), /agent:<name>, and $skill mentions work, and so do /compact and /workflow:<name>, which run no model turn:
/compact [instructions]compacts the session's context. Clients get the command as auser_message, acompactionevent that starts with the triggercommand, then one that completes, followed byusagewith the compacted context's fill, then what the compaction did as anagent_message_chunk, and the turn endsansweredwith the sametext. A compaction that fails or is cancelled endsfailedorcancelledinstead, with no agent message. Neither message is saved: a later reload replays the compaction's own saved row in their place./workflow:<name> [inputs JSON]starts the workspace workflow in the background;/workflow:plan/<plan id>starts a run of a saved plan, and/workflow:run/<run id>takes a stopped run up again, withrecoverafter it to run again the attempts whose outcome is unknown, once nothing of theirs still runs. Clients get the prompt as auser_messageand the start notice, with the run id, as anagent_message_chunk, both saved, and the turn endsansweredwith the notice astext./agent:<name> [--model <reference> --] <task>rebinds a session that has no conversation yet to that agent, then runstaskas its turn; clients get the agent's options asoptions_changedbefore the turn's output.
The TUI's own commands, such as /model, do not run in the daemon, and the turn fails as a configuration error.
What a session runs, and what its job states mean, is described in Sessions and jobs.
Session MCP inventory
rho/session/mcp returns a point-in-time SessionMcpInventory for the named loaded session, including servers supplied in its setup. It neither loads the session nor changes its settings. An unloaded session gets SessionNotLoaded; an unknown id gets SessionNotFound.
config_path: the configuration file the daemon opened the session with.mode:native,unsupported_agent, ortools_disabled.servers: configured servers, including disabled and failed entries. Each has its qualifiedidentity,enabled, startupstatus(connected,connecting,disabled,invalid_config,failed,timed_out, ornot_loaded), exportedtool_count, and human-readabledetail.tool_sources_loading:truewhile the session still loads the tool sources it opened with, its MCP servers and OpenAPI sources. Its prompts wait until it has. An OpenAPI source is not a server, so with only OpenAPI sources this is the one sign that the session loads. Omitted whenfalse.
Details include transport, startup errors, exported tools, tools added or withdrawn since startup, the last failed keepalive ping, current MCP prompt commands, and resource counts. Treat detail as presentation text, not a machine-readable contract. status describes startup; subsequent reachability is reported in the details. Reissue the request for a fresh snapshot; no inventory subscription is created. It reads shared maintenance handles rather than locking the runtime, so a running model turn or a queued configure does not delay it.
Session MCP prompts and resources
Three reads give a client's composer what the session's MCP servers offer a person: resources to pull into a message, and values for the arguments of a prompt command. Each answers for the named loaded session without waiting for its active turn. None loads the session or changes what its model sees. An unloaded session gets SessionNotLoaded; an unknown id gets SessionNotFound.
rho/session/mcp/catalog returns a point-in-time SessionMcpCatalog. Reissue it to see what a server added or removed since; no subscription is created.
prompts: each has theserverthat offers it, itsname, an optionaltitleanddescription, theargumentsit declares (each aname, an optionaldescription, andrequired), andcompletes_arguments, which istruewhen its server suggests values for them. The session runs a prompt as the commandmcp:<server>:<name>, which itsoptionslist.resources: each has itsserver,uri,name, and an optionaltitle,description, andmime_type. Withtemplated, theuriis an RFC 6570 URI template whose placeholders must be filled in before a read.
rho/session/mcp/resource reads the resource at a concrete uri from server and returns its contents in the server's order. Each is text (a uri, an optional mime_type, and the text) or blob (the same, with the bytes base64-encoded in blob); a kind the protocol does not carry is unknown. A server the session has not connected gets InvalidParams. A read the server refuses or fails gets InternalError with the server's reason as its message. A client that uses only the start of a text body names how many bytes in max_text_bytes: a longer text may then come back cut short at a character boundary, still longer than that, so the client can tell there was more. A blob always comes back whole. A read whose response still would not fit a protocol line (16 MiB less 1 KiB for the envelope) gets InternalError, and its message gives the size and the limit.
rho/session/mcp/complete asks server for values of argument of prompt, given the value typed so far, and returns values, best first. Suggestions are help: a server that has none, does not complete arguments, or fails the request answers with no values and no error.
Session processes
rho/session/processes returns the background processes the named loaded session's process tool started, as they are now. It neither loads the session nor changes anything the session's model sees: a read does not mark a result seen or move the cursor the model polls with. An unloaded session gets SessionNotLoaded; an unknown id gets SessionNotFound. Reissue the request to refresh; no subscription is created, and a running turn does not delay it.
processes: the processes still running and those that ended whose result the model has not been given yet, oldest first. Each has itsid,command,state(starting,running,exited,terminated,timed_out, orfailed_to_start),elapsed_seconds,quiet_secondssince its last output while it runs, and itsexit_codeonce it ended with one.output: present when the request'soutputnamed aprocessthe session still knows. It holds theprocessas it is now, also after it leftprocesses, and the retainedchunksfrom the request'sfromcursor on, each with itscursor,stream(stdoutorstderr), andtext.
To follow a process's output, send from: 0 first, then each answer's next_cursor. The session retains a bounded amount of output: first_cursor is the oldest chunk it still holds, so above 0 earlier output was evicted, and a client drops the chunks it holds below it.
Session background work
A loaded session's background work is what runs on its behalf outside its turns: the processes its process tool started, the workflow runs it started, and the subagents it delegated to. The attach response's background lists it as it is then, and the background event carries the whole list again each time it changes. Each item has its item, tagged by kind: process with its id, workflow with its run, or subagent with its run and, for a subagent that writes a Rho session, that session. It also has a title to show (the command, workflow name, or task), its status (running, completed, failed, or cancelled), and a process's exit_code once it ended with one. Work that ended can stay listed, with how it ended, until the session's model has been given its result, so a client sees how it ended before it leaves the list. The list is sent before a turn begins or ends, so a client hears how the work a turn takes up ended, and what a turn left running, before it hears of the turn.
rho/session/background/list reads every loaded session's list at once, without attaching to any: each session with work listed, as its session and its work. A session absent from it has none or is not loaded. A subagent's session lists none while its run is under way; that run is listed as a subagent item of its parent's. A daemon from before this method answers MethodNotFound, which a client reads as not knowing, not as no work. Work runs on after the turn that started it ends, so a job that rho/job/list reports completed, or in any other state but in progress, may still have work whose status is running: a client that shows sessions from the job list reads this too to tell a session that is done from one whose work still runs. Reissue it to refresh; no subscription is created. A later major of the protocol lists this work with each job in rho/job/list instead, and removes this method.
rho/session/background/stop stops one item, named by its item as the list gives it: a process is terminated, a workflow run is cancelled, and a subagent's run is cancelled. Its result then reaches the session as any result does, so the list reports it ended. The answer means the stop was requested, not that the work has ended. An item the session is not running gets InvalidParams.
Content blocks
A prompt's content, and a user_message event's, is a list of blocks, each with a type:
| Block | Fields | What the model sees |
|---|---|---|
text | text | The text. |
image | mime_type, data (standard base64) | The image: a PNG, JPEG, GIF, or WebP. Each image may be at most 32 MiB, the limit pasted images have, but over the socket the whole request must fit in one 16 MiB line, which leaves about 12 MiB of image after base64; a longer line is an InvalidRequest. |
resource | uri, text | A text resource embedded whole, such as an attached file: text in a code fence labelled with uri. |
resource_link | uri, name, optional description | A resource named but not included: description, else name, in a code fence labelled with uri. |
context | text | Text the client adds that the person did not write, such as a host's instructions: the text, ahead of the prompt's other blocks. A prompt that runs no model turn, such as /compact or a /workflow: start, leaves it for the session's next model turn, while the daemon keeps the session loaded. Only a prompt carries it; the saved user_message leaves it out. |
A prompt with no blocks besides context gets InvalidParams, as does one with an image whose data is not base64, is over the limit, is not one of those formats, or is not the mime_type it declares; the error names the block by its position, from 0. A block of a type the daemon does not know reaches the model as a fenced placeholder. A user_message holds the message as saved, so a resource the prompt carried appears as its fenced text block, live and on replay.
A session's setup
rho/session/new and rho/session/attach take an optional setup: the choices rho acp takes per session and rho takes as flags. The daemon applies it when the request opens the session: a new session, or an attach that reopens a saved one. A session the daemon has loaded keeps what it opened with, as it keeps its environment. Every field is optional:
| Field | What the session gets |
|---|---|
additional_directories | Directories outside the workspace its tools may use, as --add-dir adds them: absolute paths to existing directories. Any other entry gets InvalidParams, naming it, and the session does not open. |
mcp_servers | MCP servers the client provides, connected next to those in config; one replaces a config server of the same name. Each has a transport: stdio, with name, command, and optional args (a list of strings) and env, or http, with name, url, and optional headers; env and headers are objects of strings, by name. The daemon connects plain HTTP only to this machine and never lets these servers sample the model. An entry it cannot connect is left out, and still replaces the config server of its name; when a name repeats, the last entry wins. |
without | Parts of the session left out: tools, system_prompt, or subagents, as --no-tools, --no-system-prompt, and --no-subagents leave them out, or questions, for a client that cannot show questions: the session then has no questionnaire tool and declines an MCP server's question; or saving, as --no-save: the session has no file (below). A part this daemon does not know gets InvalidParams. |
child_threads | Who runs the children its agent tool starts: daemon, the default, as subagents of the session, or host, as the client's host's own threads, which rho acp --t3code asks for. With host, the session's agent and agents tools delegate through the delegate_task, task_status, and task_cancel tools of an MCP server named t3-code in mcp_servers; while one of them is missing, every agent call fails rather than run the child in the daemon. |
idle_wake | What the daemon does when a subagent, workflow run, or background task of the session finishes while none of its turns runs: never, the default, or turn. A background process started as a service never wakes the session nor holds a turn open; its result waits for the next turn. With never, a prompt's turn stays open until the work it started and every subagent of the session finish, and a result of older work waits for the session's next prompt. With turn, a prompt's turn ends while that work runs on, and the daemon starts a turn of its own that gives the model the result, as the terminal UI does. That turn has no prompt: its events reach every attached client. A subagent's request that its parent act starts such a turn too. Its informational messages do not: they go to the model with the session's next provider request. A session with host child threads is woken through its host instead. |
surfaces | Whether the client draws A2UI surfaces: unsupported, the default, so the session has no ui tool, or drawn. The daemon also reads it from an attach to a session it has loaded (below). |
sign_in | When the session needs usable credentials for its model's auth profile: required, the default, to open, so a session without them does not open and the request fails with SignInRequired; or later, from its first turn, so a session without them opens signed out, as the terminal UI starts, and its turns fail on the missing credentials until a sign-in. |
The session keeps its directories and the parts it leaves out, other than questions, in its file, so they outlast the daemon unloading it. A prompt or attach that reopens a saved session opens it with the directories it saved that still exist and the parts it saved as left out, plus those its own setup names: a later client can narrow a session further, never widen it. MCP servers, questions, surfaces, child_threads, idle_wake, and sign_in belong to the client, since a server's env and headers may hold secrets and host child threads go through the client's MCP server: the daemon never saves them, so a reopened session has only those of the attach that reopens it, and none when a prompt reopens it, since a prompt carries no setup. A saved directory that no longer exists is dropped, and the daemon logs a warning naming it. A session rho run or rho acp saved keeps what their --no-* flags left out the same way.
That guarantee holds across the daemon's reopens, so it covers the sessions of the TUI and rho acp, which run in the daemon.
A new session opened without saving lives in the daemon's memory alone, and so do its job's record and those of the jobs it starts: rho/session/list never lists it, the daemon keeps it while a client follows it or it has work under way and discards it once it sits idle, and a daemon restart loses it. saving is read when a session opens: a request that reopens a saved session without it gets InvalidParams.
Following a session
After rho/session/attach, the daemon sends the session's events as rho/session/event notifications, each with the session, a seq, and the event. The attach response comes first. Each event's type is one of:
| Event | What it carries |
|---|---|
state | The job's new state, and the turn it is of: the one under way, or the one that ended. Only a session that has run no turn has none. An ended turn's turn_ended comes first. |
user_message | A user message, whole: its message id and content. A steer that just applied, crossing into the conversation for the turn's next model request, carries the steer id rho/session/steer returned. |
steering_delivered | The provider already took steer id mid-request: it can no longer be withdrawn, and still applies, as a user_message carrying id, at the turn's next model request. |
agent_message_chunk, thought_chunk | More text of the agent's reply or reasoning, under a message id. |
tool_call | Opens a tool call, or updates the call with the same id: its title, kind, status, input (raw_input), content, and locations. A call opens as pending while the model is still writing its input, with a display that follows the input so far, and becomes in_progress under the same id when it starts; a call of a response the provider discarded closes as failed. Once it finishes, its content starts with the text the model got from it, if any. A tool the provider ran itself, such as its web search, opens completed under an id of its own, with what the provider said it did as its content. Absent fields are unchanged. Its display, when present, replaces the card Rho's TUI draws for the call (below). |
plan | The agent's plan, replacing any earlier one. |
usage | How full the model's context is: used_tokens, and window_tokens when the model's window is known. Once a request in the session had a price, cost_usd_micros holds what the session has cost so far, across daemon restarts, in millionths of a US dollar. While a response streams, each count of its usage the provider sends reports the step's fill again with the cost so far, the unfinished response included. A finished compaction reports one too. |
title_changed | The session's new title: the generated one, a few seconds after the first answered turn, rho run --detach runs included, or one rho/session/rename saved. |
compaction | A context compaction began or ended, under its id. Its status has a type: started, then exactly one of completed, cancelled, or failed with an error. A started status carries trigger: command when a /compact prompt started it, so the turn runs the compaction and no model request, or automatic when the session started it within a model turn. A completed status carries counts, the context before and after the compaction: previous_messages, current_messages, previous_tokens, and current_tokens (locally estimated), and cost_usd_micros when the session prices the compaction. A compaction that removed nothing reports the same counts on both sides. |
provider_request | The turn sent the provider a model request and waits for its response. It says what the turn is doing until its next event. |
response_discarded | The provider's response broke off and is retried. What it streamed cannot be taken back: keep it, or mark it superseded; the retried response starts new messages. |
provider_retry | The turn asks the provider again, and the reason: rate_limit, provider_error (another failure that may pass), invalid_response, context_overflow, or request_failed (one request failed and is sent again; no response was discarded). retry_after_ms is how long the provider said to wait, when it said. It says what the turn is doing until its next event; a discarded response's response_discarded comes first. |
card | A titled card shown outside the conversation, such as a background result: its body as markdown, as plain text for hosts that show text as is, and its tone: neutral, accent, success, warning, or error. A card that is a notification also carries it as display, the notification Rho's TUI draws, with what expanding it shows. |
notice | Something to tell the user that is not part of the conversation. |
input_requested | The turn waits for a person: the request, with its id, what it asks (below), the tool_call that asks, if one does, its timeout, if it has one (below), and its asker, subagent for a subagent's question and absent for the turn's own request. |
input_resolved | The request id closed, with its resolution: answered, withdrawn, or timed_out. |
input_held | The request id's timeout stopped; it waits for an answer. |
turn_ended | Turn turn ended, with its outcome (below). |
background | The session's background work changed: work, all of it, replacing the last. |
activity | Whether the session is settled: state is settled once no turn is under way and neither the daemon nor the session's host will start one for work the session waits on, and active otherwise. It is a level: a session with idle_wake: turn stays active after its turn ends while a subagent or task runs whose result the daemon will deliver in a turn of its own, and settles after that turn. active comes before the state that starts a turn, and settled only after the state that ends one. A delivery turn that ends without taking its result, with nothing left running, settles the session rather than being started again. |
options_changed | The session's options changed (below), all of them, replacing the last. |
cache_warm | The daemon's keep-warm of the session's provider prompt cache changed. warming holds pings, those sent since the session's last model request, and max_pings, the most the daemon sends before it lets the cache expire, while a process started with keep_warm holds the cache and no turn runs; it is absent otherwise. cost_usd_micros is what the session's pings have cost since the daemon loaded it or its conversation last moved, absent while no ping had a price. usage counts the pings too, so a client that shows them apart takes this out of the latest usage cost; after a ping, a usage with the cost so far comes first unless a turn runs, whose own usage then carries it. Why warming stopped early is a notice. Sent only for a session opened with idle_wake: turn while behavior.keep_cache_warm is on, whose process tool then offers keep_warm. |
Each loaded session has one stream of events, numbered by seq from 1. A client keeps the stream and the highest seq it has handled since its attach response as its cursor, and passes them as after when it attaches again, for example after the TUI is closed and reopened. A session the daemon unloaded and reopened since has a new stream. The response's replay says what follows:
tail: the daemon still buffers every event after the cursor, and sends those, then the live ones. The client continues where it was.reset: the cursor is from another stream, too old, at 0, or absent. The client drops what it shows and its cursor. The daemon sends the session's saved conversation, then ausageevent with the session's context fill and spend as of that save, once it knows them (a reopened session's has no spend until a turn reports it), then the events since the last turn saved: the last turn'sturn_endedandstate, and the turn under way. The saved conversation's events and thatusagecarryseq0, except the last, which carries theseqthe turn under way began after, so a client that detaches before it has the whole conversation holds no cursor and resets again.
Saved conversations hold no usage, compaction, provider_request, response_discarded, provider_retry, steering_delivered, cache_warm, or title_changed events, nor the calls of tools the provider ran itself, and their user messages carry no steer; those are live only, so a reset replays them only for turns since the last one that saved, apart from the usage above. The attach response's title is the session's current title.
The first replay_events events after the response are the replay; the rest are live. The replay ends in the response's state, of the response's turn. A client that attached after that turn ended finds how it ended in the replay, as the turn_ended carrying that id, and one that attached while it runs waits for that turn_ended. rho attach follows a session this way.
A loaded session's replay, tail or reset, ends with an activity event carrying the session's current level, counted in replay_events; a session observed unloaded is settled. A subagent run's stream sends no activity: follow its state instead.
The daemon buffers up to 16 MiB of a session's recent events for clients that resume. A turn larger than that still resets correctly once it is saved; a client that resets while it is under way gets a notice that its start is missing.
The daemon detaches a client with rho/session/detached, after which no event of that session arrives:
lagged: the client fell 4096 events behind, the daemon unloaded the session, as a delete that fails after it unloaded the session does, or the session's conversation moved to another node of its tree (select_node,rewind_workspace). A turn never waits for a client; attach again with the cursor to catch up.daemon_stopping: the daemon is stopping.restarting: the daemon is re-executing in place, for an upgrade orrho/daemon/restart, and closes the connection next. Connect again and attach with the cursor; the restarted daemon answers with aresetreplay. When the restart cut short a turn with notimeout_msof a session opened withidle_wake: turn, and the attach reopens the session withidle_wake: turntoo, the daemon first starts a turn of its own that continues it, which the replay ends in. That turn begins with anotice, not auser_message; its model input is saved as the turn's user message, which a laterresetreplay of the saved conversation includes. A session reopened otherwise, or first by a prompt, keeps the turninterrupted, as does a turn with atimeout_msor of a session opened withidle_wake: never.deleted:rho/session/deletedeleted the session.not_loaded:rho/session/observefound the session unloaded, so its replay was the saved conversation and nothing follows. Observe again to read it again.
Attaching or observing a session the connection already follows replaces the earlier attachment.
NEXT_MAJOR(rho-protocol): report a session's activity as SessionAttachResponse::activity and stop replaying a trailing synthetic SessionEvent::Activity. Until then, read the level from the replay's last event. When the stream's last event is not an activity event, or the replay does not hold it, the daemon adds the trailing one under the stream's last seq, so it may repeat the seq of an event already sent, the one at your cursor included. Do not drop an event because its seq is not above your cursor.
Tool cards
A tool_call's display is the card Rho's TUI draws for the call, so every frontend can draw the same one. Its types are the display module of rho-protocol; in the schema, Presentation and the types it uses. A display is one of:
card: a card with a status (running,ok,error, orinterrupted), a header, facts under it, and a body of lines, code, search hits, or diff rows.summary_card: a card drawn collapsed to its facts until expanded.message: a notification, such as an agent's report.
A call's start and each progress update carry a card that replaces the last one, and its result carries its final display. A call that closes failed without a display was cut off: draw its last card as interrupted. A reset replays the cards a client watching live got, except for a call the model was still writing when its response was aborted, which a reset does not replay. Images a call returned stay in its content.
Turns, and sending a prompt again
Each turn has an id (#1777). rho/session/prompt answers with it, every state of the turn and its turn_ended carry it, and an attach names the turn its replay ends in. So a client tells the turn it started from one another client started by the id, whatever order events and answers arrive in, and whether an event is replayed or live. The daemon keeps a session's last turn's id with its job, so the id still names the turn after a restart.
A prompt's answer can be lost: the connection closes first, or the daemon begins restarting and answers DaemonStopping, which it may do after the turn already saved the prompt. A prompt that names an idempotency_key, any non-empty string the client uses for no other prompt of the session, can be sent again safely. While the key is that of the session's latest turn, the prompt starts no turn: it answers as the first one did, with that turn's id once the turn began, even after the turn ended or the daemon restarted. The daemon compares only the key, not the content, and keeps the latest turn's key alone, so a prompt is safe to send again until another turn starts on the session. A turn that ended before it began (TurnEnded) ran nothing, so its key starts a turn when sent again. An empty key is InvalidParams.
How a turn ends
A turn that ends sends one turn_ended event; the state that records the job's end follows, unless the daemon could not record it. A turn the daemon's stop or restart cuts short sends none: the stop first detaches every client with daemon_stopping, or restarting, and rho/job/list shows the job interrupted, as it does for a turn whose daemon died. The outcome has a type:
| Outcome | Job state | What it carries |
|---|---|---|
answered | completed | The model's answer whole as text, and why it stopped: end_turn, max_tokens (the provider cut it off), or refusal. Show text rather than the chunks you gathered when they differ, as after a provider retry restarted the reply. |
max_steps | completed | The turn used its model-step limit before the model answered; text is its last step's reply, possibly empty. |
cancelled | cancelled | A client cancelled the turn. |
timed_out | timed_out | The daemon cancelled the turn at its prompt's timeout_ms, which it repeats. |
failed | failed | The error: its kind (authentication, provider, tool_host, configuration, or other) and a message. An authentication failure's message names only the provider, the auth, and how to log in, never the provider's own text, which may echo credentials. Any other failure whose provider sent a diagnostic shows it first, as a notice. An authentication failure's diagnostic goes to the daemon's log only. |
A client that resets finds, after the saved conversation, the turn_ended of each turn since the last one that saved to it. Outcomes are not saved with the conversation.
Answering a turn's requests
A turn that needs a person, for an approval, a plan approval, or questions, opens an input request and sends input_requested to every attached client. The job is waiting_for_input while any request is open. A request waits for as long as it takes: it is never denied because no client is attached, and only a timeout the user configured answers it for them. A client that attaches later finds every open request in the attach response's inputs, even when the replay no longer holds the event that opened it; the replay may repeat some, so key requests by id. The session's input_requested hooks run too, so a user away from every client can be told.
Any connected client whose hello declared the answer capability may answer with rho/session/answer, whether or not it follows the session. The first answer wins and every attached client receives input_resolved with answered; a later answer, or one to a request the turn withdrew, gets InputNotOpen. A turn withdraws its open requests, with withdrawn, when it is cancelled or ends, and a plan approval when the tool that asked stops waiting; a turn that stops waiting just as an answer wins, or just as a timeout fires, ignores it. Request ids are unique within the session for as long as the daemon has it loaded.
A question one of the session's subagents asks is the session's request, not a turn's. It opens whether or not a turn runs, since a subagent outlives the turn that started it, and it stays open when a turn ends or is cancelled: only an answer, a timeout, or the subagent giving up closes it. The job is not waiting_for_input for it. Answering it starts no turn; the subagent goes on with the answer. Its request's asker is subagent, so a client can tell it from the turn's: dismissing it need not cancel the turn, as Rho's TUI does not.
Each request's ask has a kind, which decides the answers it takes; any other answer gets InvalidParams and leaves the request open:
kind | What it carries | Answers (answer.kind) |
|---|---|---|
approval | The tool or part of rho that asks (source), the operation it would perform (read or write a path, discover instructions, run a process, reach the network, load a skill, or control_session: act on another session, naming the action (new, prompt, steer, or cancel), the session unless it starts one, its workspace, and the text it sends, unless it cancels), and the policy's reason. | allow_once, allow_for_session, or deny with an optional reason for the tool. |
plan_approval | The plan, as markdown, and the permission modes it may be carried out in. | approve_plan with one of those modes, or keep_planning. Either may carry feedback, text the model reads with the answer. |
question | A title and its questions, each with an id, prompt, choices (value, label), its selection (one or many), whether it takes the user's own text (allow_other), whether it is required, and the answer the agent suggests, if any (default: the values it would send and whether to pre-select it, style selected, or only focus it, focused). | answers, mapping question ids to the chosen choices' values or the user's text; decline; or dismiss. |
Timeouts
When the user sets [questionnaire] timeout_seconds, a question whose agent offered fallback answers comes with a timeout: the deadline_ms (Unix time in milliseconds) when the daemon answers it, the answer it will give (answers), and the agent's reason for it. Show the user both, with a countdown. Nobody needs to be attached: at the deadline the daemon answers the request itself, and every attached client receives input_resolved with timed_out. The tool learns the answers came from the fallback, not the user.
Never answer a timeout yourself: an answer sent with rho/session/answer counts as the user's own, so the tool would take the fallback as the user's choice. The daemon answers it.
Once the user starts on the request, on their first key, paste, or click in it, call rho/session/hold. The request is then held for good, with no timeout: every attached client receives input_held, the request waits for an answer like any other, and a client that attaches later finds it in inputs without a timeout. Holding a request that has no timeout, or one already held, changes nothing. The setting applies to sessions opened after it changes.
Surfaces
A session's ui tool shows the user an A2UI v1.0 surface (Surfaces). A session has the tool only when the request that opened it asked for it, with surfaces: drawn in its setup, so a client that draws surfaces sends that in the setup of every rho/session/new and rho/session/attach. Asking for surfaces needs the answer capability, which rho/session/surface_action needs too: a connection that did not declare it and sends surfaces: drawn is refused with CapabilityRequired, since nobody could act on a surface through it. Every other session has no ui tool: one a client that never heard of surfaces opens, and one a prompt reopens, since a prompt carries no setup. A daemon from a build before surfaces ignores the field, and its sessions have no ui tool either, so a client needs no check of the daemon's build before it asks.
An attach to a session the daemon has loaded does not change the session's tools, so a client that draws nothing can follow a session that has the ui tool, and a client that draws surfaces can follow one that lacks it. The daemon counts the attached clients whose attach said surfaces: drawn. While there is none, a ui call that waits for the user is refused, with an error that tells the model to ask in text, and shows nothing: nobody could answer it. A call that does not wait still shows its surface, which a client that draws surfaces gets in its replay when it attaches. A call already waiting when the last such client leaves keeps waiting, as a held request does, for that client to come back or the turn to be cancelled.
A client that draws them keeps one A2UI processor for each session, with the basic catalog, since surface ids are unique within a session only. The rho-a2ui crate has one, MessageProcessor. The ui call's tool_call carries the surface in its content, as one item of type surface:
| Field | Meaning |
|---|---|
surface | The id of the surface every message is about. |
messages | A2UI v1.0 agent-to-renderer messages, already checked: createSurface, updateComponents, updateDataModel, or deleteSurface. |
A call has at most one, and every update of the call repeats it unchanged, since an update replaces the call's content. Apply its messages once for each call id, when the item first arrives, and draw the surface under the call's card. A call that waits for the user sends the item while it is still in_progress; a call whose wait was cancelled closes failed, with an error that begins stopped waiting on surface, and keeps it, and its surface stays. A call the daemon refused has no item. A reset replays each call with the same item, in order, so a client that drops its processors on a reset rebuilds every surface from the replay. The daemon saves no messages: it compiles a saved call's block again, which gives the same messages while the daemon's rho-a2ui is the one that showed them, and a block a later version refuses replays as its card alone. It compiles only the calls whose saved result says they showed a surface: one that succeeded, and one that stopped waiting. A call that failed any other way, or was interrupted before it ran, replays as its card alone, as it was live.
When the user acts on a component whose action is an event, send rho/session/surface_action with the session, the surface, and action, the A2UI action message whole, as MessageProcessor::dispatch_action writes it (RendererMessage::to_json). For a surface created with sendDataModel, add its data model as data_model. The daemon answers {} once the session has the action: a ui call waiting on that surface returns it, also when the call shows an update to the surface and the user acts at that moment, and otherwise the model reads it at its turn's next boundary, in a turn the daemon starts when the session is idle and was opened with idle_wake: turn, or with the next prompt. A surface the session does not have, an action that is not the message for that surface, and a component with no event action of that name get InvalidParams, as does a session the daemon has not loaded. Actions that run a function on the client, such as openUrl, are the client's to run and are not sent.
Changing a session's settings
A session's options are what a frontend shows as its settings and command menu: ACP's config options and available commands, and the TUI's model picker, reasoning, fast mode, and permission controls. rho/session/new and rho/session/attach return them, and every attached client receives options_changed when they change: after rho/session/configure, at a turn's end, which may leave new skills, prompt templates, or MCP prompts behind, after a plan approval switches the permission mode, and after rho/auth/key, rho/auth/logout, or a finished rho/auth/login changes the models a session may switch to. A session in a turn when a credential write lands refreshes at the turn's end.
| Field | What it carries |
|---|---|
model | The current model, as {provider, model}, the auth profile it runs on, and the models the session may switch to (available), each with a short label; the user's favorites first. |
reasoning | The current reasoning level and the levels the model takes (available): off, minimal, low, medium, high, xhigh, max. Absent when the model's reasoning cannot be configured. |
fast_mode | Whether fast mode is enabled: faster responses at a higher credit rate. Absent when the model has no fast mode. |
permission_mode | The current permission mode and every mode (available): bypass, auto, allow_edits, plan, supervised. |
commands | The commands a prompt may run, in menu order: each name, kind, description, and input_hint, what to type after the name, absent when it takes nothing. A slash command starts the prompt as /<name>; a skill is mentioned anywhere as $<name>. /workflow:<name> commands are listed when the session has the workflow tool, and /agent:<name> ones for every workspace agent that runs on Rho. |
added_dirs | The directories the session's tools reach besides its workspace; absent when it has none. |
rho/session/configure applies one change, tagged by kind, and answers with the session's options as they are now:
kind | Fields | Change |
|---|---|---|
model | model ({provider, model}), optionally auth and setup | Switches to one of model.available, keeping the reasoning level; a model that cannot keep it is refused. auth names the auth profile to run the model on, as --auth does; one the model's provider does not take is InvalidParams. Without it, the session keeps its auth when the provider takes it, else uses one that has credentials. A change that moves the session to another model tells clients which prompt file it now runs on, as a notice, unless setup is true: a launch flag or a host's setup sends that, as it sets the session up rather than switching it. |
model_after_compaction | model, optionally auth | Switches as model does, only if the session's current or last prompted turn is a /compact that reduced the conversation. It waits behind that turn like any change and is dropped, with options as they were, when the turn did not compact. A client sends it once a /compact it asked for started, to return to the model the session compacted from even if the client stops following the session; a change sent after it still applies last. |
reasoning | level | Spends one of reasoning.available on later turns. |
fast_mode | enabled | Turns fast mode on, for a model that has it, or off. |
permission_mode | mode | Gates later turns' tool calls with mode. |
agent_catalog | Reads the workspace's agent definitions again and tells the model, from its next turn on, which agents it can now delegate to; clients get a notice when the model had to be told. | |
add_directory | path | Lets the session's tools reach the directory at the absolute path, and tells the model so from its next turn on, with a saved row; clients get a notice. A path that is not a directory, or one the session already reaches, is InvalidParams. |
select_node | node | Continues the conversation from node, the id of a node in the session's saved tree, which a client reads from the session's file (no method lists them yet): later turns branch from it, and the nodes after it stay in the tree. The daemon detaches every attached client as lagged; attaching again replays the conversation up to node. A node the tree does not hold, or a session with nothing saved, is InvalidParams. |
rewind_workspace | checkpoint | Puts back the files the turn of workspace checkpoint checkpoint (the id of the node its turn ended on, which a client reads from the session's checkpoint journal; no method lists them yet) changed, where they still hold what that turn left, and, when every one was put back, continues the conversation from before that turn as select_node does. Clients get what became of each file as a notice, which also says so when the files were put back but the conversation could not be moved. A checkpoint the session does not have, a session in plan mode, or one with nothing saved is InvalidParams. |
model_catalog | Reads the model lists again, after a client refreshed the lists the daemon shares on disk; every loaded session's options follow. | |
context | text, display | Adds text to what the model reads from its next turn on, with no turn of its own, and saves it as a user row reading display. Attached clients get no event for it; a later reset replays the row. Empty text is InvalidParams. |
A change the session cannot take, such as a model no saved credential serves or fast mode on a model without it, gets InvalidParams naming why, and the session keeps its setting. A change that fails as it applies, such as a model switch whose provider could not be built, gets InternalError; the session's options then report what it runs with, which options_changed carries if that changed. A change sent while the session's turn is under way, waiting for input included, waits for the turn to end, then applies and answers, so a frontend can send settings whenever its user picks them. Changes and turns take the session one at a time, in the order the daemon took their requests: a change applies after the turn of every prompt taken before it, and a prompt's turn runs after every change taken before it, so a change sent once the job reports running waits for that turn's end. A change the daemon took applies even if its client disconnects before the answer; while the daemon is stopping, one still waiting gets DaemonStopping and does not apply. Only a session the daemon has loaded takes a change; any other gets SessionNotLoaded, so attach first.
Settings persist with the session: from its first change on, the session keeps its model, reasoning level, fast mode, and permission mode with its file, as they stand at each save, a plan approval's mode switch included. A session the daemon unloads and reopens, or one a later daemon reopens, runs with them, and its options say so. A setting it can no longer take, such as a model whose credentials are gone, falls back to the config's.
Listing, renaming, and deleting sessions
These methods let a frontend show and manage saved sessions without reading session files (#1670, #1667). They work on any saved session, loaded or not, and reach the same session store as rho sessions, /resume, and ACP's session/list.
rho/session/list lists the sessions a person can resume: those with a saved message whose workspace still exists, leaving out rho run's, subagents', and workflow nodes' sessions, as /resume does. With cwd, an absolute path, it lists only that workspace's sessions, resolving symlinks as rho/session/new does, and none when the path does not resolve to a directory; without it, every workspace's. Each entry has:
| Field | Meaning |
|---|---|
session | The session id, which rho/session/attach reopens. |
cwd | The session's workspace. |
added_dirs | The extra directories the session can reach that still exist; empty when none. |
title? | The session's title, once it has one. |
first_user_message?, last_user_message? | The first and last user messages on one line, cut to 80 characters, as /resume previews them. |
updated_at | When the session was last saved, in Unix seconds. |
Sessions come newest first. A page holds limit sessions, 100 by default and at most 1000, and a larger limit gets InvalidParams naming the limit. When more sessions follow, next_cursor is an opaque string to send back as cursor for the next page. The walk never repeats a session, nor skips one when others are deleted between pages; a session saved during the walk moves ahead of the cursor and is missed, so list again from the first page for a fresh view. A cursor that is not one a list returned, such as a malformed one, gets InvalidParams.
rho/session/rename saves title, trimmed, as the session's title, as rho sessions rename does. A title that is empty, holds a control character such as a newline or an escape, or runs over 500 characters gets InvalidParams naming why. A title it saves is never replaced by a generated one. An id nothing is saved under gets SessionNotFound. Ids are chosen by clients, so one id can be saved in two workspaces; a rename or delete of such an id gets InvalidParams.
rho/session/delete deletes the session's files, with those of the subagent and workflow sessions it started, as rho sessions rm does. The daemon unloads a loaded session first, and detaches its clients with deleted; a session it loaded that has saved nothing yet has no files, so it is unloaded, its clients detached with deleted, and the delete returns {}. It refuses with SessionBusy while the session's turn is under way, waiting for input included, while a settings change waits to apply or applies, while a subagent, workflow run, or background process it started is still running or holding a result, while a run it started has not finished, or while another job writes it. Another process, such as a foreground rho run, holding the session or a session it started gets SessionInUse. A loaded session is checked against all of these before the daemon unloads it, so a refused delete leaves it loaded; should the delete still fail after the unload, as on a disk error, its clients are detached with lagged and attaching again reopens it. While the delete runs, a request for the session may get SessionBusy, or, once the session is unloaded, SessionNotFound or SessionNotLoaded. An id the daemon has not loaded and nothing is saved under gets SessionNotFound. The session's job record stays.
Signing in and out
rho/auth/key and rho/auth/logout change the credential store the asking client's sessions read, as /login and /logout do in the TUI. rho/auth/key, rho/auth/logout, rho/auth/login, rho/auth/list, and rho/auth/choose_store each take environment, the client's environment variables as on rho/session/new (#1779). The store is the one RHO_CREDENTIAL_STORE in that environment names, else the daemon's own: the daemon moves to the store its config selects when the request arrives. A request the daemon refuses writes nothing. Moving stores alone changes no running session's credentials. A change applies to every session that reads the store, whichever client opened it: a running session uses a new key, or drops a deleted one, from its next prompt, and new sessions use it at once. After a logout, a session's next prompt fails with TurnEnded, whose outcome is a failed turn of kind authentication, until a key is saved again.
rho/auth/key first asks the provider's models endpoint about the key and refuses one the provider rejects, with HTTP 400 or 401, with KeyRefused, keeping the key saved before; the error's message names the status. A key the provider cannot be asked about is saved anyway, and the result's unchecked says why: its reason is no_model_listing when rho lists no models for the provider, forbidden when the endpoint answered 403, as it does for a key that may run models but not list them, or unreachable when its endpoint could not be reached or failed with another status, and its message says so in words, such as HTTP 404. A client reads a reason it does not know as another reason the key went unchecked. Surrounding whitespace is ignored, and auth must take an API key; OAuth and other sign-ins use rho/auth/login (below). rho/auth/logout also forgets an Ollama login.
A credential set in the asking client's environment, such as OPENAI_API_KEY, wins over a saved one in that client's sessions, so these methods, and rho/auth/login, refuse its auth profile with EnvironmentOverride before writing anything; its data.variable names the variable to unset in the client's environment. The daemon's own environment plays no part: a credential variable there signs in no session.
The key travels only over the daemon's socket, which only its user can open, and the daemon never logs it, nor the params of any request.
rho/auth/list reports what the asking client's sessions can use now: the store they read, logins the TUI or ACP saved in their own processes included, and the credential variables in its environment.
Logging in
rho/auth/login runs an auth profile's interactive login, such as openai-codex's or github-copilot's, in the daemon, which relays it to the client that started it; rho login is such a client. The response, {login}, comes before anything else of the login, which then arrives on the same connection:
| Notification | Params | When |
|---|---|---|
rho/auth/login_prompt | login, prompt | The provider's login is ready. prompt holds the url to open, and for a device-code login the user_code to enter there and, when the provider has one, the url_with_code that fills it in, with an instruction for the user. The daemon opens no browser: the client opens the URL, or shows it. |
rho/auth/login_finished | login, outcome | The login ended. The outcome's type is succeeded, once the credential is saved; failed, with a message; or cancelled. A provider that sends no confirmation (Ollama Cloud's device key) succeeds as soon as the daemon saved the login, since its prompt's instruction already told the user what to approve. A client reads a type it does not know as a login that did not succeed. |
A browser login waits on a callback port on the daemon's machine, so a client on another machine should ask for device_code; a provider with no device flow, such as OpenRouter, runs its browser login either way. The credential is saved as rho/auth/key saves a key, and every session the daemon runs uses it from its next prompt.
One login per auth profile runs at a time, whichever client started it: another gets LoginBusy until it ends. A login ends when the provider approves or refuses it, when rho/auth/login_cancel cancels it, or when the connection that started it closes; the last sends no rho/auth/login_finished, since nobody is left to read it. Once the provider approved, the daemon saves the credential even if the client leaves. rho/auth/login_cancel for a login that already ended gets LoginNotFound. An auth that takes an API key, or none, gets InvalidParams. When the daemon cannot reach the store the login would be saved in, rho/auth/login refuses with CredentialStoreUnavailable before the provider is asked, so no prompt follows.
Credential store
credential_store in rho/daemon/status names the daemon's own store, the one its environment and config select, which sessions and sign-ins use unless their client's RHO_CREDENTIAL_STORE names another: os (the Secret Service on Linux, the Keychain on macOS) or file. selected_by says what chose it: default when nothing did, config for behavior.credential_store, or environment for RHO_CREDENTIAL_STORE in the daemon's environment. unreachable, present only when the daemon cannot reach the store, says why, such as a daemon with no session D-Bus for the Secret Service. The daemon checks by looking up an account that does not exist, writing nothing and prompting for nothing, so a locked keyring counts as reachable until a write is refused. A client reads a store or selected_by it does not know as another value.
The daemon never moves credentials to another store on its own. While selected_by is default, a client signing in should ask its user which store to use, offering the file store when the OS store is unreachable, as rho login does, and send the answer with rho/auth/choose_store. The daemon first writes and deletes a temporary secret there, refusing a store that does not take it with CredentialStoreUnavailable, then saves the choice in its config and keeps credentials there from then on; credentials already saved stay where they are, and the models each session may switch to follow the new store. A store RHO_CREDENTIAL_STORE chose, in the daemon's environment or the asking client's, cannot be replaced this way, so the daemon refuses with EnvironmentOverride naming the variable.
Settings
The daemon reads and writes the user's settings for its clients (#1720), so a frontend renders a settings screen from data. A namespace is {"kind": "agent"}, the agent's settings in config.toml, or {"kind": "client", "name": "<name>"}, a client's own (below).
rho/config/schema describes each agent setting with its key, which is also where config.toml keeps it (behavior.permission_mode is the permission_mode key of [behavior]); its kind; its default, absent for an optional setting that is unset by default; the category page and optional section it sits under; a label and help; whether a project may later override it (overridable_per_project); and applies, when a change takes effect:
applies | Takes effect |
|---|---|
immediately | As soon as it is saved, such as behavior.agent_concurrency, which resizes the subagent budget. |
next_turn | At the next turn of every loaded session: the advisor and automatic compaction settings, and the codemode mode. |
next_session | In sessions the daemon opens later. |
restart | When the daemon next starts, such as behavior.credential_store. |
A kind is bool; choice, whose choices each have a value, a label, and optional help; integer, from min to an optional max, with an optional unit (bytes, lines, percent, or seconds); text; or model, on the runtimes it lists (rho, claude-cli). A value is true/false, a whole number, a string (a choice's value), or for a model {"runtime": "rho", "provider", "model"} or {"runtime": "claude-cli", "model"?}. A model on another provider takes that provider's default auth profile.
rho/config/get returns every setting of the namespace in values, each with its value, absent when unset, and its source: global when the file sets it, default otherwise. It also returns errors, each a message and the key it concerns when it has one, for what keeps the file from loading. While the file does not load, values are the last ones that did, and those stay in force for loaded sessions and for saved sessions the daemon reopens, while rho/session/new fails with SessionOpenFailed, naming the file and its errors. The connection then gets rho/config/changed with the namespace, its new revision, the values that changed, and the whole errors list whenever either changes, including through the client's own rho/config/set and edits by hand. Reading the namespace again replaces that subscription. The daemon notices a hand edit the next time something touches the settings: a config request, a session opening, or a turn starting.
rho/config/set takes the revision the client last read and a list of changes, each {"op": "set", "key", "value"}, which writes the value even when it is the default, or {"op": "reset", "key"}, which removes the key from the file so its default applies. The daemon applies them in order, so a setting another belongs to comes first: an internal agent's model before its reasoning. layer is global, the user's file. The daemon edits only those keys, keeping the file's comments and layout, then loads the result; nothing is written unless every change is valid and the file still loads, and a change to the value the file already holds writes nothing. A stale revision, or another writer holding the file, such as rho login recording a login, gets ConfigConflict: read the settings again and resend. A client that may send a write before rho/config/changed for its last one arrives names itself in writer, a string unique to it such as a random UUID: a revision stays good for that writer while only its own changes followed it, so its quick changes do not conflict with each other. Another client's change, or a hand edit, ends that. A writer still sends each write only once the last one's response came back: the daemon handles requests concurrently, so writes in flight together may land in either order. An unknown key, a value the setting does not take, or a result that does not load, such as a compaction target at or above its threshold, gets InvalidParams naming each key, its limit, and the value sent. behavior.credential_store gets InvalidParams too: change it with rho/auth/choose_store, which checks the store can be reached. A hand edit that no longer loads is repaired by changes to the keys it fails on; a file that is not valid TOML, or does not load for keys the changes leave alone, gets ConfigInvalid: fix it by hand.
Client settings
A client keeps its own settings in the daemon by declaring them with rho/config/register: a client name of lowercase letters, digits, and -, and settings in the schema's shape, each a bool, choice, integer, or text setting. The daemon stores their values in ~/.rho/clients/<name>.toml, one file per client, and serves them as {"kind": "client", "name": "<name>"}. Registering again replaces the client's schema, which the daemon keeps until it stops; a client registers each time it connects to a new daemon. Keys the file holds that the schema does not list stay in the file and are not served. A file that stops reading keeps its last good values served, with its error, as config.toml does; a value its setting refuses reads as the default. rho/config/get or rho/config/set on a client that has not registered gets InvalidParams.
A session's grant
A session's agent can start, prompt, and watch other sessions through session control: the sessions tool and rho mcp serve. What a turn may do there is its grant, which the daemon holds on the session's job (#1780):
depthis how many sessions started one another to reach this one: 0 for a session a person drives.accessisread(list, read, and wait for sessions) orwrite(also start, prompt, steer, and cancel them).workspacesis"any", or{"only": [...]}with the directories it reaches, as canonical paths.
rho/session/new and rho/session/prompt name it as grant. Without one, the daemon reads it from the request's environment (RHO_SESSION_DEPTH, RHO_SESSION_SCOPE), which is no limit when the environment carries none; a value there that does not parse gets InvalidParams. The daemon records the grant on the session's job, where rho/job/list shows it, and writes those two variables into the session's environment from the record, in place of any the client sent. A prompt's grant replaces the record's when its turn starts, so a session that opened without a limit has none again once a person prompts it; a session reopened by an attach takes the grant of the attaching client's environment.
A session that opens under a limit is held to it (#1796). Every session an agent starts through session control opens under one, at least a depth of 1; a session a person starts opens with none. The job keeps the grant the session opened with as grant_limit, which rho/job/list shows beside grant, and the daemon holds every later grant to it, whoever asks: a prompt or a reopening attach gets the deeper of the two depths, the lesser access, and the workspaces both reach. So a person's prompt into such a session runs under the session's limit, not the person's own access, and a prompt that asks for less still gets less. The request is not refused; a client reads the limits its turn runs under from the job. A session that opened without a limit has no grant_limit.
A session opened naming a parent opens with no more than a session its parent's turn starts may have, whatever the request asks for: at least one level deeper than the grant on the parent's job, with no access or workspaces the parent lacks. The daemon checks that only when one of its jobs writes the parent session; for a parent it does not run, such as a foreground rho run's, and for a session started with no parent, as one rho mcp serve starts is, the session opens with what the request asked for.
Session control still decides the grant it names, one level deeper than its caller and with no more than the caller's scope, and checks it against its own limits.
The grant bounds session control, which enforces it against a caller; it does not confine the session, whose commands can reach the daemon's socket themselves.
The client's environment
A session's commands run with its client's environment, not the daemon's (#1659). rho/session/new, rho/session/prompt, and rho/session/attach each carry environment, the client's environment variables as an object of strings; a client leaves out a variable whose name or value is not UTF-8. A new session's commands start with the opening client's, each prompt replaces it with the prompting client's, and an attach uses its own only when it reopens a session the daemon had unloaded. Processes already running keep the environment they started with. MCP servers, hooks, OpenAPI sources, CLI subagents, a Claude Code advisor, and the workflow runs a session starts read it too, as Daemon describes. The RHO_TRUST_PROJECT_* variables in the environment that opens or reopens a session are its project trust until the daemon unloads it, and that of the workflow runs it starts; the daemon's own environment grants none (#1779). A rho/session/prompt whose environment grants other trust than the session has, less or more, is refused as ProjectTrustMismatch before anything of the session changes: no turn starts, no event is sent, and no client is detached. rho/session/attach to a loaded session, rho/session/observe, and rho/session/steer are not checked. The credential variables and RHO_CREDENTIAL_STORE of the environment that opens or reopens a session are the session's credentials for as long, as Daemon describes: its models sign in with them, a later prompt's do not replace them, and the daemon's own environment supplies none. The daemon leaves provider credentials out of commands' environments, though CLI subagents and the advisor get them, never logs the environment, and never saves it, so a session reopened after a restart takes the reopening client's.
Errors
Errors use the JSON-RPC code and message. The first five codes are JSON-RPC's own.
| Code | Name | Meaning |
|---|---|---|
| -32700 | ParseError | The line was not JSON. Sent with a null id. |
| -32600 | InvalidRequest | Not a valid JSON-RPC request, a second rho/hello, or a line over 16 MiB. |
| -32601 | MethodNotFound | The daemon does not implement the method. |
| -32602 | InvalidParams | The params do not match the method's, or one is invalid, such as a cwd that is not a directory. |
| -32603 | InternalError | The daemon failed while handling a valid request. |
| -32000 | HandshakeRequired | A request other than rho/hello came before the handshake. |
| -32001 | VersionMismatch | The protocol versions are incompatible; data says which side to change and, when that is the daemon, what restarting it would cost. |
| -32003 | SessionNotFound | No session is saved under the id. |
| -32004 | SessionBusy | The session already has a turn under way (for a prompt or a delete), a settings change waiting or applying (for a delete), a delete under way, or, for a delete, background work running or a run it started unfinished; or another job, such as a subagent run, writes the saved session a prompt, an attach, or a delete would touch. |
| -32005 | NotSteerable | No model request is taking input. |
| -32006 | SteerRefused | The running turn refused the steering input, or a request to withdraw a steer. |
| -32007 | DaemonStopping | The daemon is stopping, or restarting in place, and starts nothing new. |
| -32008 | SessionOpenFailed | The daemon could not open the session: for example, the config is invalid, the workspace does not define the agent a new session asks for, the agent a saved session was saved as, or the one /agent:<name> rebound it from, changed or is gone, or the session is a subagent's or workflow node's, which only its parent continues. |
| -32009 | TurnEnded | The turn ended before it began; data is its outcome. |
| -32011 | InputNotOpen | The input request is not open: another client answered it first, it timed out, or the turn withdrew it. |
| -32012 | SessionInUse | Another process, such as a TUI or a foreground rho run, has the session open, or, for a delete, a session it started, so the daemon cannot reopen or delete it. |
| -32013 | EnvironmentOverride | A variable in the asking client's environment holds the auth profile's credential, or RHO_CREDENTIAL_STORE, in that environment or the daemon's own, chooses the credential store, so saving or deleting one, or choosing another store, would change nothing; data.variable names it. |
| -32014 | KeyRefused | The provider rejected the API key, and nothing was saved; the message says what failed. |
| -32015 | CredentialStoreUnavailable | The credential store could not be opened, read, or written, as when the OS keyring is locked or the daemon has no session D-Bus to reach it. rho/daemon/status says why; rho/auth/choose_store chooses another store. |
| -32016 | SessionNotLoaded | The daemon has not loaded the session, which a settings change needs; attach to it first. |
| -32017 | LoginBusy | The daemon is already signing in to the auth profile; wait for that login to finish. |
| -32018 | LoginNotFound | No login under way has the id: it ended, or never started. |
| -32019 | SignInRequired | The daemon could not open the session because its model's auth profile has no usable credentials: none are saved or set, they could not be read, or the provider refused them. Sign in, then try again. A session whose setup's sign_in is later opens signed out instead. |
| -32020 | ProjectTrustMismatch | The prompting client's project trust (the RHO_TRUST_PROJECT_* variables in its environment) is not the session's, so no turn started and the session is as it was. data names the variables only the session's trust has (session_only) and those only the client's has (client_only). Open another session, or prompt with the session's trust. |
| -32021 | ConfigConflict | The settings changed since the revision a rho/config/set sent, so nothing was written. Read them again, then resend. |
| -32022 | ConfigInvalid | The settings file is not valid TOML, so the daemon cannot merge a change into it and wrote nothing. Fix it by hand; rho/config/get lists where it fails. |
| -32023 | CapabilityRequired | The method needs a capability this connection's rho/hello did not declare, such as rho/session/answer from a connection of role agent. Nothing was done; a connection keeps what it declared. |
Versions and compatibility
The protocol has its own version, major.minor, independent of rho's; rho/hello and rho/daemon/status report it.
Major 0 is the unstable protocol, which is the current one: it may change anything, and a client and daemon work together only when their versions are equal. Until the beta, the version is 0.1 and a change to the wire does not raise it, so two builds that report the same version may still differ; the beta sets the version once. It stays at 0.x until a frontend outside rho's repository has run against it (#1776). The rest of this section describes majors from 1 on, where a client and daemon work together when their majors match.
A protocol minor only adds: methods, notifications, error codes, optional fields, and values of open enums. In the schema, one variant of an open enum is marked x-rho-other and matches every value the enum does not list, so a client generated from it accepts values a later minor adds; read them as unknown. For an event or content block the catch-all matches any object with a string type, so schema validation alone does not reject a malformed known variant: pick the variant by its type, then decode it. A client should also ignore fields it does not know, and treat an error code it does not know by its message. Anything else, such as removing, retyping, or constraining a field, making a field required or nullable, or adding a value to a closed enum, comes only with a new major.
The daemon omits an optional field that has no value rather than sending null.
CI holds the protocol to this. A test fails when protocol.json no longer matches the wire types, and a check compares it with the schema of the last rho release: a change a minor does not allow fails unless the major rises, and any other change to the wire, which excludes descriptions and names, needs the minor to rise. While the major is 0, a second check compares each change with the commit before it: the minor may not rise, and the handshake may only gain optional fields.