Versioning and introspection
Versioning and introspection: part of the Control Protocol of TUIOS.
This page is one part of docs/protocol.md of the tuios repository. The Control Protocol page lists every part.
Versioning and introspection
The protocol carries a version integer. Bump it only on an incompatible change to the envelope or to an existing verb; adding a new verb is backward compatible and does not bump it.
Support window
A client and a daemon one minor release apart work together, in both
directions. A live upgrade works from the previous minor release too. Code
that serves only an older peer is removed. The CI job mixed-versions pairs
this build with the previous minor release (scripts/e2e-mixed-versions.sh).
The hello handshake
hello is the first call a client should make. It reports the protocol range the
daemon serves and identifies the daemon, so a version mismatch is reported as a
protocol_mismatch error rather than surfacing later as a decode failure or a
dropped connection.
Request:
{"id": 1, "verb": "hello", "params": {"client": "tuios", "version": "1.4.0", "protocol": 1}}Result:
{"id": 1, "result": {
"type": "hello",
"protocol": 1,
"min_protocol": 1,
"daemon_version": "1.4.0",
"pid": 4242,
"instance": "5b0e9c1f2a7d4e83",
"sessions": 2,
"link_policy": true,
"pane_grants": true,
"load": {"cores": 8, "load1": 0.84, "mem_pct": 41.5, "agents_working": 3},
"os": "linux"
}}link_policy says the daemon holds calls from other machines to a link
policy (see What a linked machine may do here).
tuios stdio-proxy reads it before it would reach the daemon on its own socket
for a link, and refuses when it is set. It is absent from an older daemon.
pane_grants says the daemon holds calls from panes to their grants (see
pane-grants) and takes a pane's token with pane-grants. On a
platform where the daemon cannot read the peer's pid, the tuios CLI reads it
and then presents $TUIOS_PANE_ID and $TUIOS_PANE_TOKEN on every
connection it opens from a pane. It is absent from an older daemon.
load is the machine's load: cores, load1 (the one-minute load
average), mem_pct (memory in use, Linux only), agents_working and
load_ok. load_ok is false when the daemon could not read the load, as on
Windows and FreeBSD: load1 is then 0 and means nothing. It is absent from a
daemon from before the field, whose load1 was read. The daemon reads the
system at most every 5 seconds. A linked daemon reads it off
the hello its heartbeat sends, so list-hosts can report each host's load
with no call of its own. It is absent from an older daemon.
instance is an id for the running daemon image. It changes when a live upgrade execs another binary, while pid stays the same.
upgrade is present only on an image that took its panes over in a live upgrade (see daemon-upgrade), and says what the handoff measured: from (the build the panes came from), panes, manifest_bytes, preflight_ms, quiesce_ms, capture_ms, pending_max, pending_total (bytes the programs wrote while their panes were stopped), stopped_at (Unix nanoseconds), apply_ms, apply_heap_start, apply_peak_heap_inuse, apply_heap_end, paused_ms, fallback, set when the new binary could not take the panes over and the binary that was running took them back, and recovered, set with fallback when the new image died before it was up and the handoff's keeper started the binary that was running in its place, under the keeper's pid.
os is the operating system the daemon runs on, as Go names it: linux,
darwin, windows. A client attached from another machine reads it to start
a command entry with sh -c or cmd /C. It is absent from an older daemon.
A client may also send term and color_term, its TERM and COLORTERM. A session the connection later creates, with new-session, switch-session's create or start-agent, gives its panes that terminal, as a session made by attaching or by tuios new gets the client's. A caller with no terminal of its own (a script, CI, an agent) sends them empty or leaves them out, and its sessions get the daemon's fallback, xterm-256color and truecolor. The tuios CLI sends both.
The handshake is optional, not a gate: a daemon serves every other verb whether
or not hello was called. A daemon that answers hello with unknown_verb,
or closes the connection with no response line, is older than the support
window. The tuios CLI reports it as a version mismatch, with the
tuios kill-server command that resolves it.
Changes to existing verbs
Changes that alter what an existing verb does, for a caller that relied on the old behaviour. None of them bumps the protocol integer: every field keeps its name and type, and a caller that sends nothing new keeps working. What changes is an answer, and each entry says which.
A pane's OSC 1 name labels an unnamed workspace. The name a pane's program gives with OSC 1 is the label of its workspace while the workspace has no name of its own and the pane is its active one. OSC 0 sets the icon name too, but it does not count: shells and agents send it with every prompt. What changes for a caller:
- A
list-windowsentry, andget-windowwith no client attached, carryicon_namewhen the pane gave one. The synced session state carriesicon_names, a map from window ID to the name, filled from the daemon's emulators into every snapshot and never stored, so a value a client sends back is ignored. - The daemon pushes the session's state when a pane's OSC 1 name changes, so a client labels a workspace whose panes it does not stream. Pushes for OSC 1 and OSC 7 changes start at least 100 ms apart.
- In the attached session's own views an unnamed workspace reads as the
name instead of its number: the dock, the rail's workspace tags, the go-to
picker, the tab menu and
{workspace}inappearance.host_title. A name set withset-workspace-namestill wins.list-workspaces, the session navigator's rows for other sessions, herdr's tab label and the tmux shim are unchanged. - The pane snapshot carries
explicit_icon_name, and each title stack entryexplicit_icon. An older peer leaves them out and reads as no name.
A usage limit is a state of its own. An agent that stopped on its
harness's usage or rate limit reads limit_reached. What changes for a caller:
- The agent state can be
limit_reachedinget-agent-state,list-agents, the synced window state,agent-stateevents andwait-for agent-state.needs_youis false for it andreadytrue. An older client draws it as a state it does not know. set-agent-state erroredwithkindusage_limitnow lands aslimit_reached, where it stayederrored. A reader that looked forerroredwithblocked_byusage_limitreadslimit_reachedinstead.- Claude Code's
StopFailurehook witherrorrate_limitorbilling_errorreportslimit_reached. Any other error reportserroredwith the error named (stopped on overloaded), where it saidstopped on an error. - Every
list-agentsentry gainslimit_resets(the reset the harness named, in its words, empty otherwise) andcontext(tokens,window,percent,near, or null). See Context size. - The metadata keys
context_tokensandcontext_windoware written by the status line feed, the transcript (tokens only, under the sourcetranscript) and protocol panes.
Task cards carry attachments. get-task gains attachments, a card's row
gains attachment_count, a card's history and task-changed gain the actions
attached and detached, and attach-task, detach-task and
get-task-attachment are new (Task verbs). A daemon from
before this answers the new verbs with unknown_verb.
agent-transcript over a link needs transcripts, which the default
grants. The person's own client attached through a host reads the
conversation of an agent on that host. Before, the call over a link needed
respond, which the default does not grant. respond still includes
transcripts, so a table that allows respond reads as before. A table that
sets allow without either now refuses with forbidden naming
transcripts. The call still needs the nonce of a person's attach: a
process in a pane, a link stream the hub did not vouch for and a caller with
no nonce still get not_human.
herdr's pane.focus and agent.focus show the pane's session. A
focused pane in a session that no client shows now moves the attached client
to that session, as workspace.focus does, so the pane is on screen. Before,
the pane was focused in its session and the client stayed where it was.
The herdr stream also sends workspace_focused, tab_focused and
pane_focused when a client moves to another session, once each and in that
order, as herdr does when its active workspace changes. A window focused in a
session no client shows sends no pane_focused.
set-session-name raises the new event session-labelled. Before, a
display name changed with no event, so a subscriber, and herdr's
workspace.renamed through it, never heard of it. A subscriber that names no
types gets it.
The herdr socket sends workspace_renamed for a rename. rename-session
sent workspace_created for the new name, for a workspace the herdr client
already had, and workspace.rename sent nothing. Each now sends one
workspace_renamed with the label session.snapshot then shows, as herdr's
workspace.rename does. See
AGENT_STATE.md.
The new event agent-seen says a finished pane was looked at, or marked
unread again. A subscriber that names no types gets it.
The herdr socket reports a seen done pane as idle. herdr's done is an
idle agent nobody has looked at yet, and tuios's mapping did not read the
seen bit. See AGENT_STATE.md. What
changes for a herdr client:
agent_statusisdoneonly while the pane has a finished turn nobody has looked at, andidleafter.erroredstaysdone.pane.agent_status_changedfires when a pane is looked at or marked unread.pane.focusandagent.focusmark the pane seen, with or without a client.agent.wait,events.waitandagent.promptwithwaitmatch that status.
The new verb report-program-status applies an
OSC 7501 report to a pane. tuios status sends it when it has no terminal.
The herdr socket sends tab_renamed when a workspace is named. A herdr
tab is a tuios workspace, and naming one with set-workspace-name or herdr's
tab.rename sent nothing to a tab.renamed subscriber. See
AGENT_STATE.md. What changes for a herdr
client:
tab_renamedcarries the tab'stab_id, itsworkspace_idand the newlabel, the labeltab.getreads next.- Clearing a name sends the label the tab falls back to, its workspace number.
- An empty workspace in the background sends nothing when named: its name
comes with the
tab_createdof its first pane.
The new verb list-routes lists this machine's addresses.
queue-prompt takes client_id. A second call from the same sender with the
same client_id for the same pane queues nothing and answers duplicate: true. A call without it
works as before.
A hooked agent that stops reporting shows as silent. A pane whose claim
is a report, and whose state is working, may go without a report for
[agents] silent_after (default 10m). After that, what changes for a
caller:
get-agent-stateand everylist-agentsentry reportstateasunknownand gainreason:silent.reasonis empty for every other pane.activityisunknown.source,agent_state_atandevidence_age_msstill describe the last report.readystays false.- The
agent-stateevent reportsstateunknownwithreasonsilentwhen the pane goes silent, and the reported state with no reason when the next report comes. - A selector's
state:term matches the shown state,unknown. - The synced window state keeps
agent_stateworkingand gainsagent_reason. A session's window summary reportsagent_stateunknownand gainsagent_reason. Both are omitted when empty. ask-agent,fan, the queue and agent mail still read the pane asworking, so nothing is typed into it.
The next report from the pane's agent clears it, a report that its
if_state refuses included. The herdr socket API still reports the pane as
working.
An agent can be settled. mark-attention takes the actions settle and
unsettle, which name a pane with session and window (see
mark-attention). What changes for an existing caller:
get-agent-stateand everylist-agentsentry gainsettled. The synced window state and the session listing's window rows gainagent_settled, omitted when false and taken from the daemon's own state on every client push. A row of another machine's agents (list-hostswith agents) carries that host'ssettled, display only.- The daemon clears the settle in the change that makes the agent need the
person: it goes to
needs_input,erroredornone, it finishes a turn (completion_seqgoes up), or it sends the person mail. - A
settlecloses the pane's openfinisheditem with the reasondismissed, asdismiss-attentiondoes, and marks the turn seen. - The hook event
after-settleexists (see HOOKS.md).
Asks of one agent take turns. An ask-agent that comes while another
ask of the same target runs no longer types over it, and no longer fails with
not_ready once ready_timeout passes. It waits for its turn, first come
first served, for up to timeout, and then goes on as before. A turn that
does not come in time is not_ready, and nothing is typed. An ask whose
caller closes its connection while it waits leaves the line and types
nothing. The reply gains
queued_behind and waited_turn_ms. A queued prompt (queue-prompt) is not
typed while an ask holds the target's turn.
list-tasks takes all_sessions. It lists every session's cards, and the
answer has all_sessions: true in place of session. The agents view's
board reads it. A daemon from before this ignores the parameter and answers
for one session, without all_sessions; a daemon with no task verbs answers
unknown_verb. In both cases the board says the daemon is too old. A selector
takes stage:.
Cards move on their own, and fan and start-agent take task. The daemon
moves a task card when it records a fact about the card's work, and sends the
task-changed staged event with reason naming the fact (see
Task verbs). fan takes task and task_session and stamps
the card with the fan it makes. start-agent takes task and claims the card
for the pane it opens. Both answer with the card's row in task, and take
human_nonce for the stamp or the claim. A daemon from before this refuses
task by name with invalid_params, so a client can start the agent without
it and claim after. claim-task with next skips a card a fan of another
session works on.
list-host-sessions rows carry agents. A remote session row gains
agents, one entry per agent pane: id, title, state, state_at,
harness, message, kind, meta and subagents, at most 32 a session.
The agents view draws them as rows.
list-hosts names the ssh failure of a host it cannot reach. A row with
status unreachable gains failure, fix and, for some, fix_command,
when ssh's own words name the failure. failure is one of host_key_new,
host_key_changed, auth, dns, refused and timeout. fix is one
plain sentence. fix_command is the command that fixes it, as a person types
it: ssh ADDR true for host_key_new and ssh-copy-id ADDR for auth. The
reason of such a row is the sentence of its class, in place of "The host
did not answer." The status value is unchanged. A row whose words match no
class has none of the three fields.
list-hosts reports each host's load. A host row gains cores, load1,
mem_pct, agents_working, load_ok, load_at and rtt_ms, from the last hello on the
link: the handshake, then the heartbeat. A link that carries traffic is not
pinged, so its heartbeat now pings once the load is older than a minute. The
fields are absent until a hello from the host carried a load.
send-agent-message takes a message in parts. text is no longer
required when parts is given. parts is the form queue-prompt takes. A
message that fits 8 KiB and holds no image has its blocks put in place. Any
other has each paste and image written to the paste folder, attached, and
named in the body. A daemon from before this answers text is required for a
message sent in parts alone.
queue-prompt takes host. A message for a pane on a linked machine is passed there over the link. See The delivery queue.
queue-prompt takes images. A part may be {"kind":"image","data":…}. A
daemon from before this answers invalid_params for the kind. See
The delivery queue.
queue-prompt takes a message in parts. text is no longer required when
parts is given, and the result gains parts, the count read. A message
with a long paste can now put a file in the paste folder when it is typed. The
queues are also bounded in bytes, 32 MiB a pane and 128 MiB in all, and
queue_full covers both bounds. See The delivery queue.
A caller that sends only text sees no change.
A link checks that its host still answers. A link that carried no frame
for 15 seconds sends hello, with no params, on a stream of its own. A reply
of any kind, an error included, counts as an answer. Two pings in a row with
no answer in 5 seconds end the link, and it is dialed again. After this
machine wakes from sleep, or after retry-host, one ping with no answer is
enough. retry-host on a host that is up now sends that ping at once, and on
a host that is not up it starts the backoff again from 1 second. The next
dial after a ping ends a link, after a wake from sleep, or after a dial that
timed out runs ssh with -o ControlPath=none, so a master connection that did
not survive the sleep is not used. The drop reason is
"The host stopped answering." An older far daemon answers the ping as it
answers any hello.
list-worktrees reports a merged branch. With changes, each row gains
merged, and merged_into when merged is true. See
list-worktrees. A worktree record gains start_commit, the
commit its branch was at when new-worktree made it. An older peer ignores
all three.
The default window_size is latest. A daemon with no [daemon] window_size now uses latest, so session-info reports window_size: "latest" where it reported smallest. Under latest the session's agreed
chrome reserve counts only the clients of the session's size along each axis,
and every client whose hello does not offer ViewChrome. On the client
protocol, a hello can carry Machine (the client's short host name, kept only
when it is a valid machine name), ClientKind (ssh or web) and
ViewChrome. MsgAttached can carry ClientID, ClientCount, SizedBy,
SizedByClient and SizedByKind, and MsgSessionResize the three SizedBy
fields. They name the client that set the size for the hint a larger client
shows, and tell a client whether it is that client. An older peer ignores all
of them.
A client that is not tuios can stream a pane and answer the Inbox. Three
additions serve a native phone app on ssh host tuios stdio-proxy:
- The new verb stream-pane streams one pane as bytes, with a sequence number on every frame, so a client resumes after a dropped network instead of taking a new screen.
- The new verb attach-presence gives a connection the
person's
human_noncewithout an attach. - A pane can now be smaller than its clients asked for, while a stream holds a size lease on it. A client that compares the pane's size with its own layout sees the difference. The pane goes back when the lease ends.
respond, reply-approval, answer-ask, dismiss-attention and every other
verb that takes human_nonce now also accept the nonce of a presence. A
presence made for one session acts only in that session. See
Nonce scope.
A phone can get the Inbox by Web Push. The new verbs
register-push, list-push and remove-push keep the person's
phones. When an Inbox item of a kind a phone asked for opens or closes, the
daemon sends an encrypted push to the phone's push service. The verbs take
the person's human_nonce, from an attach or a presence with no session, and
over a link the respond capability. Each registration opens an Inbox item.
A pane records the pane that started it. When a process in a pane calls
new-window, split-window, start-agent, fan or new-worktree, the pane
it makes records the caller's pane. What changes for a caller:
list-windows,get-windowand everylist-agentsentry gainstarted_by,{"session", "window"}. It is omitted when no pane started the window: the call came from outside every pane, or over a link.- The synced window state gains
started_by, taken from the daemon's own state on every client push, and saved with the session. An older peer drops it. The gui-bridgestatewindow rows gain it too. - The new verbs
search-panes,command-historyandlist-portsread pane text, the shell commands a pane ran, and the TCP ports a pane's processes listen on (see search-panes).
A pane's OSC 7501 reports are part of its state. A program in a pane can report what it does with the Program Status Protocol (see PROGRAM_STATUS.md). What changes for a caller:
get-agent-stateand everylist-agentsentry gainprogram_status, the pane's records, the root first:id(absent for the root),state,kind,progress(always present, -1 for none),app(the record's own or its nearest parent's),title,msgandat. It is an empty list for none.sourcecan beprogram.set-agent-statedoes not accept it.blocked_byand thekindparam ofset-agent-statecan beauth.- The synced window state and a session's window summary gain
program_status, omitted when empty and taken from the daemon's own state on every client push. An older peer drops it.
The daemon keeps paste buffers. The new verbs list-buffers,
show-buffer, set-buffer, delete-buffer and paste-buffer read and
change one list of buffers that every client and session shares (see
list-buffers).
A client now calls set-buffer for each yank. The tmux shim's buffer
commands use these verbs when the daemon has them, so a buffer the shim set
before is no longer read from its file. The error code no_buffer is in the
catalog.
A host that waits for a Tailscale sign-in can be dialed again on request.
The new verb retry-host takes host and makes that link dial again now
instead of after its backoff. While the host is in tailscale_check, the link
then dials again every 5 seconds at most, for two minutes. A dial in progress
is not stopped, and a call within 2 seconds of the start of the last dial wakes
nothing. The result has host, status and, when the link has one,
approval_url. A restricted connection and a linked machine may not call it.
approval_url is only an https address on login.tailscale.com,
controlplane.tailscale.com or the host's tailscale_login, matched exactly.
For any other address the banner named, the row has no approval_url and has
approval_refused: true. A caller over a link gets neither field, and the
reason of such a host without the address.
host-changed, and the push to attached clients, now also fire when a link in
tailscale_check gets a new approval_url, so a client sees the new sign-in
page at once. The reason of such a host is reworded to "Tailscale SSH needs
you to sign in before tuios can reach this machine." and goes on to name the
page. The status value is unchanged.
remove-worktree removes the worktree's checkpoints. The daemon saves a
pane's work tree under refs/tuios/checkpoints/ when its agent finishes a turn
(see list-checkpoints). Those refs belong to the whole
repository, so remove-worktree, and keep-fan through it, now delete the
ones taken in the removed worktree. The checkpoints of panes in other
checkouts stay. The result is unchanged. The error code no_checkpoint is in
the catalog.
keep-fan can merge the kept attempt, and confirm_required has a second
use. keep-fan takes merge, merge_mode and into. With merge, the
kept attempt's branch is first merged into its base, as ship-merge does, and
the result carries it as merge. A merge that is refused stops the call
before any sibling is removed. Without merge the verb is unchanged.
ship-push and ship-pr answer confirm_required with what they would send
and a token, as a write by select does. A worktree record, in
list-worktrees, list-sessions and the session state, may carry pr. The
new error codes nothing_to_commit, merge_conflict, checkout_dirty,
no_remote and gh_unavailable are in the catalog. See
ship-commit.
A pane lists its subagents. The daemon keeps each subagent a pane's agent runs, not only the count (see Each subagent). What changes for a caller:
get-agent-stateand everylist-agentsentry gainsubagent_list: id, type, description, state (running,done,failed,stopped), started_at, ended_at, now, last, tools and result.subagentskeeps its meaning, the running ones. The synced window state and a session's window summary gainagent_subagent_list, taken from the daemon's own state on every client push and omitted when empty, which an older peer drops.report-agent-activitytakes the eventsubagent_update, and its activity takescall_id,spawn,outcomeandtools. Asubagent_stopno longer forgets the subagent at once: it stays on the list as ended for a minute.set-agent-state's activity takesspawn,agent_typeandcall_idon atoolevent. An older daemon ignores them.agent-activityentries of kindsubagent_startandsubagent_stopname the subagent intextby its description and type, "Research tmux (general-purpose)", or its type alone, and asubagent_stopcarriesoutcome,duration_msandtools.- The Claude Code hook sends the subagents' own tool calls, which it dropped
before, as
subagent_update, and readsbackground_tasksfromStopandSubagentStop. The integration's version is unchanged: the events it hooks are the same.
A pane counts the subagents its agent is running. An agent that hands work
to subagents and ends its turn reports done while they work, so the daemon
keeps, per pane, the subagents its hooks reported starting and not yet
stopping (see Agent metadata). The reports
come with the new verb report-agent-activity, and
set-agent-state is unchanged: state is still required, and its activity
still takes the five events it did. What changes for a caller of the older
verbs:
subagentsis a reserved metadata key, written by tuios:1 subagent,3 subagents, absent at none.set-agent-metarefuses it likenowandprompt, and itsclearleaves it.get-agent-stateand everylist-agentsentry gainsubagents, the count as a number, 0 while none run. The synced window state gainsagent_subagents, omitted when zero and taken from the daemon's own state on every client push, and so does a session's window summary.agent-activityentries have three more kinds:subagent_startandsubagent_stop, with the subagent's type astext, andsession_start, with how the conversation started.- The Claude Code integration is version 3: it adds
SubagentStartandSubagentStopentries, sointegration statusreads a version 2 install as out of date until it is installed again. ItsSessionStartsends the sameset-agent-stateas before and then areport-agent-activitysession_start.
A session's size follows its window_size policy. The daemon reads
[daemon] window_size and a session's own daemon.window_size (see
SESSIONS.md). With the
default of that release, smallest, nothing changes. What changes for a caller:
session-infogainswindow_size,session_widthandsession_height.set-optionofdaemon.window_sizeis applied by the daemon, not by a client, andget-optionof it can answer withsource: "config".- On the client protocol, a hello and a welcome can carry
WindowSize. A client that offers it reports input with the new binary messageMsgClientActivity, and draws a session larger than itself as a view. A daemon uses a policy other thansmallestonly while every attached client offered it.MsgSessionResizegainsPolicy. Each side sends nothing new to a peer that did not offerWindowSize. The daemon refuses aMsgClientActivityframe over 16 bytes unread, as it does any frame over its type's limit. - An attach can carry
ViewOnly, for a client that sends no input. Underlargestandlatestsuch a client does not count toward the size.tuios-web --read-onlysets it. An older daemon ignores it.
A call from another machine is held to a link policy. Every verb and
every binary message that arrives over a link is checked against what the
[hosts] table on the receiving machine lets the calling machine do, before
it runs (see What a linked machine may do here).
A refused call does nothing and fails with forbidden, and a hint naming the
capability and the table that grants it. The default lets a link do what it
could before, with these exceptions:
respond,reply-approval,dismiss-attentionand the newrelease-agent-messageneed therespondcapability, which the default does not grant. Over a link they used to be refused only for want of a verified nonce (not_human); with the default policy they are nowforbiddenfirst.tuios respond -w HOST:SESSION:WINDOWneedsallow = [..., "respond"]on that host for this machine.open-host-connectionover a link, which relays on to the far machine's own hosts, needs every capability, so the default refuses it.- A binary message a policy refuses is answered with
MsgErrorcode 10 (ErrCodeForbidden), and the connection stays open. - Calls on the daemon's own socket are unchanged.
Mail from another machine can be held for the person. With
hold_mail = true for the sending machine, send-agent-message over a link
to anyone but human stores the message addressed to human, with held,
held_for and held_for_label naming the window it was for. The reply
carries held: true and held_for, and to is human. The agent does not
see it until the person passes it on with release-agent-message. The Inbox
mail item carries held_id and held_for. Without hold_mail nothing
changes.
A pane on another machine can outlive a dropped link. open-pane takes
resumable, and the far daemon then keeps the process for its
hosted_grace for the asking machine after the connection drops, returning
resume_token and grace (seconds). open-pane with resume reattaches it.
The asking daemon now always sends resumable; a far daemon that does not
know it refuses it with invalid_params, and the asking daemon sends the
request again without it, as it does for window. What changes:
- A window on another machine no longer closes when the link drops, for up to
the far grace.
list-windows,session-infoand the state pushed to clients carryhost_link: "reconnecting"andhost_link_until(unix seconds) while it is being reattached. A caller that waited forwindow-exiton a link drop now waits for the grace, or for the process to exit. - Keystrokes to such a window while it is reconnecting are refused, not queued.
- Closing such a window sends
close-paneto the far daemon, which ends the process at once. - On the far machine, a pane opened with
resumableis still read while no connection is attached, so its process no longer blocks on a full pty while the link is down. A pane opened without it behaves as before.
Mail for a machine whose link is down can wait for it. send-agent-message
takes host, a machine in the [hosts] table: the daemon delivers the message
to session there over its link and returns that machine's answer with host
and queued: false. When the link is down it keeps the message instead, on
disk, and answers {"type": "agent_message_queued", "queued": true, "queue_id": 3, "waiting": 1, ...}; the messages go in order when the link is
back. At most 64 wait per machine and 256 in all; past that the send is
rate_limited. A send is also queued when the call fails without an answer
from the far machine while the link stays up (a timeout, no room for another
stream), and when earlier mail for that machine still waits or is being
delivered, so it cannot arrive ahead of it. With the link up the queue is
tried again at once, then after 1 second, doubling to 30 seconds. An error
the far machine answers is returned as before and is not queued. What changes
for existing callers:
list-attentionhas a seventh kind,outbox, one item per machine with mail waiting or refused. A consumer that switched on the six kinds sees a kind it does not know.dismiss-attentionon anoutboxitem discards the mail still waiting for that machine, and answersfor_hostanddiscarded.list-hostsrows carryqueued.tuios send-agent-message -s HOST:SESSIONfalls back to this when the host is unreachable, instead of failing withhost_unreachable.- A message queued from
humanarrives on the far machine asclaimed_human: no nonce the far daemon would honour survives the wait.hostis refused over a link and dropped from a hosted pane's report channel.
A result from another machine is marked untrusted. The CLI reaches a
session on another machine with a host-qualified target (-s HOST:SESSION,
-w HOST:SESSION:WINDOW) through open-host-connection, and speaks that
machine's own verbs. The daemon relays the bytes and decodes none of them, so
the rules below are the CLI's. The verbs on the wire do not change.
- Every
--jsonresult from another machine carrieshostand"untrusted": true. It used to carryhostonly. This coverslist-windows,capture-pane,wait-for,list-agents,send-agent-message,ask-agent,stash getand every other verb that prints its result with--json. A--jsonerror another machine answered carries them too. - In
tuios ls --all-hosts --jsonandtuios list-agents --all-hosts --json, each other machine's entry inhostscarries"untrusted": true. Thelocalentry does not. tuios capture-panetakes--json. Its plain output from another machine is fenced as untrusted content, as mail is, with│before every line. Control characters, bidi controls and zero-width characters are removed. With--ansior--resolved, SGR sequences (CSI ... m) are kept and every other escape (OSC, DCS, cursor moves, modes) is removed. A local capture prints as before.tuios send-agent-message --attach PATHto another machine first asks that machine for its session's stash root withstash-list. A path under that root passes through as written. Every other path must be a regular file on this machine: it is put in the far stash withstash-put, the stored path is attached, and one line on stderr says so ("Sent notes.txt to build's stash."). A file over 8 MB is refused before it is sent. The far daemon checks its link policy (mail) onstash-listand eachstash-put, so a link without it refuses the message before it is sent. A message queued for a host whose link is down keeps its paths as written.
An agent on needs_input or unknown is not ready to be asked. The
states that count as ready are now idle, done, errored and none. They
used to include needs_input and unknown as well. fan types its first
prompt only on idle or done, and used to accept unknown too.
An agent on needs_input is most often sitting on a permission menu, and text
typed there is read as the answer: the question approved or denied whatever
the agent had asked for. unknown is what the silence timer writes when a pane
went quiet and nothing on its screen said the agent is at its prompt, and an
agent in the middle of a long tool call looks the same.
list-agentsreturnsready: falsefor a pane onneeds_inputorunknown. It used to returntrue.readystill means what it always meant, thatask-agentwould type at the pane without waiting, and it is that answer that changed. A script that pollsreadybefore asking now waits for the prompt to be answered, or for the agent to reach its prompt.ask-agentwaits on a pane onunknownlike one that isworking, and fails withnot_readywhenready_timeoutruns out, with a message that says the state was unknown.forcesends anyway.fandoes not type into an agent onunknownwhen its harness can show that it is at its prompt, which is a harness whose manifest has an idle rule on the screen or the title (see below for the list); such an agent reachesidlefrom its prompt box or title. For another agentunknowncounts as ready, since nothing could ever show more.ask-agentagainst a pane onneeds_inputfails with the new codeagent_blockedand writes nothing. It used to type the question. It also stops waiting withagent_blockedwhen a pane it is waiting on reachesneeds_input, instead of running outready_timeout.forceonask-agentstill skips the wait for a working agent. It no longer types at a pane onneeds_input; the new paramallow_blockeddoes, for a caller that has read the prompt and knows it takes free text.forceandallow_blockedtogether are whatforcealone used to be.list-agentsandget-agent-stategainblocked_by:approvalorquestionfor a pane onneeds_input, empty when the source did not say and for every other state. A screen, title or notify rule supplies it from itskind, a report supplies it with thekindparam ofset-agent-state, and a report without one is guessed from its message the way a rule without a kind is.get-agent-statealso gainsready, with the same meaning as inlist-agents.
agent_session_id can change without a state report. The new
set-agent-session verb writes the window's agent_session_id, which
get-agent-state and list-agents return, without touching the state, its
source or harness_id. Before it, the field changed only with a
set-agent-state report. A consumer that read a new id as a sign of a new
state report should read the state fields instead. The ten session-only
integrations (see Agent state) send it,
so a pane running one of them now carries an id while its state comes from
screen rules. Separately, the daemon forgets the harness pid a window's id was
reported with when the detector sees the agent leave the pane. set-agent-state
reads that pid only while a report holds the pane mid-turn, which the agent
leaving has already ended, so its answers are unchanged.
A restore keeps each pane's agent_session_id, and the Inbox has a
resume kind. A daemon restart used to bring every window back with its
agent_session_id empty, although the state file held it: the restore's state
push took daemon-owned fields from the empty session it had just made. The id
now comes back on every restored window that ran on this machine (a window that
ran on another machine drops it, since the conversation is over there), so
get-agent-state and list-agents return it after a restart. With it, the
restore offers to resume each conversation whose harness has a [resume]
command and whose pane had an agent running when the state was saved (a saved
agent_state other than none, or an agent_harness; a pane whose agent had
exited keeps its id and gets no offer), as daemon.resume_agents says. A
restored window also comes back with no agent state: agent_state,
agent_message, agent_kind, agent_state_at, agent_harness, agent_meta
and foreground_cmd are cleared, since its shell is new. They used to come
back as saved, so a restored pane at a fresh prompt reported the old agent as
working until it closed. Clearing them is also what keeps an offer from
coming back on every later restart. In the default ask mode,
list-attention gains one item of the new kind resume per such pane, with
the command as its summary, and subscribers see an attention event opening
it. AttentionKindNames, the order list-attention groups by and the
counts object gain resume, between errored and finished. A client that
groups by kind and does not know resume should treat it like any unknown
kind. Windows also carry a new field, agent_session_harness, the harness
the id belongs to; set-agent-state with agent_session_id and
set-agent-session write it with the id, and a set-agent-session report that
names the stored id under a different harness is now applied (it updates the
harness) rather than answered as unchanged.
A prompt is pasted and submitted with a carriage return. ask-agent and
fan used to write the text followed by a line feed. Claude Code and Codex
submit on a carriage return, which is what the Enter key sends, and several
agent TUIs bind a line feed to "insert a newline", so a prompt could sit in the
input box unsent, and a prompt of several lines was a sequence of Enters. Both
verbs now write the text with its trailing line breaks dropped, wrapped in
ESC[200~ and ESC[201~ when the pane has bracketed paste (DECSET 2004) on,
then wait about 300 ms, or less once the pane has drawn the paste and gone
quiet, then write one carriage return. Line endings inside the text become line
feeds, and the paste delimiters are removed from it so the text cannot end the
paste early. A pane without bracketed paste still reads each line feed in the
text as the application decides, which for a shell is one command per line.
The submit key and paste come from the harness's manifest. ask-agent and
fan read the [input] block of the target pane's harness (see
AGENT_STATE.md). Every bundled harness keeps
the carriage return and the bracketed paste described above, so for them
nothing changes on the wire, with one exception: for GitHub Copilot, a pane
with focus reporting (DECSET 1004) on is sent a focus-in report (ESC[I)
before the paste, because Copilot ignores a synthetic Enter after it lost focus.
A user manifest can set submit = "lf" or bracketed_paste = false for its
harness.
More harnesses read their screen and title for working and idle. The
bundled manifests now carry herdr's working rules for every harness that has
them, and idle rules for Cline, Devin, Grok, Kiro, Maki and Qwen Code on the
screen and Amp, Grok and Hermes in the title, beside the four that had them.
What a caller sees:
list-agentsandget-agent-statereportworkingandidlefromsource: screenorsource: oscfor these harnesses where they used to report nothing from those tiers.readyisfalse, andask-agentandfanwait, for a pane of Amp, Cline, Devin, Grok, Hermes, Kiro, Maki or Qwen Code onunknown. It used to betrue, because these harnesses had no rule that could show they were at their prompt.forceonask-agentstill types at once, and a user manifest without the idle rules gives the old answer back.- Codex reports
needs_inputfrom its screen for an approval form, the directory trust prompt and the update offer. It used to report it only from its title and notifications. - Claude Code reports
needs_inputfor a live form under the last rule, a dynamic workflow question and an MCP elicitation dialog, andworkingfor the/btwoverlay and for background agents and MCP tasks still running. Its screen rules now match substrings case-folded. - Gemini CLI's title rules key on the glyph Gemini CLI writes. A title whose
text starts with "Action required" after the working glyph
✦reads asworking, where it used to read asneeds_input. - Grok's footer-hint rules read the last two lines only, as herdr's do.
explain-agent-screen says more. The result gains manifest_source
(bundled or the path of the user file in force), replaces_bundled, and
progress, the pane's last OSC 9;4 report. Each entry of rules and
title_rules may carry groups, naming each nested group that refused, and
text, what a rule reading a region narrower than the tail read there. The
title rules are explained against the progress report too.
An OSC 9;4 report can be read by the harness's own rules. A report from a
pane whose manifest has a title rule with region = "osc_progress" that
matches the report is read by those rules instead of mapped by the sequence's
published meaning. No bundled manifest has such a rule, so nothing changes for
a bundled harness.
A submitted prompt has to be taken. After Enter, ask-agent and fan give
the pane five seconds to show that it took the prompt, the check herdr calls
agent_prompt_stalled. The pane shows it by turning working, by turning
needs_input when it was not on needs_input before, by turning done or
finishing a turn (completion_seq goes up), by its screen showing a turn
running with its input box empty, for a harness with rules for both (Claude
Code), or by printing something after Enter. The screen counts because a
harness that reports its state from hooks can take a prompt and have the
report come late or never, when the harness kills a slow hook. Output counts only for a pane whose harness has no screen or title rule
that reports working, which today leaves out Claude Code, Codex, Gemini CLI,
opencode and every other harness with such a rule: a TUI that read Enter as a
newline redraws its input box, so output from it proves nothing.
ask-agentfails with the new codeprompt_stalledwhen the pane showed none of that. It used to wait outsettleand return an empty reply withsettled_by: idle. The question was typed either way, and the ask is still recorded in the ring. The new paramstall_timeout(milliseconds, default 5000) sets the window.- The
settleclock ofask-agentstarts when the pane took the question, not when Enter was sent, so a pane that is quiet before it reacts is not counted as having answered. fanrecords the newprompt_statusvaluestalled, with aprompt_note, where it used to recordsent. A prompt stayspendingfor the few seconds the check takes. A client that does not knowstalledshould treat it likenot_sent, which is whattuios fan --waitfrom an older build prints.
A message from human says whether it is verified. Any caller can send
send-agent-message with from: "human", and such a message used to be stored
exactly like the person's reply from the mail overlay. Now:
- The attach reply (
AttachedPayload) carrieshuman_nonce, a fresh random secret per attach. It is an additive field, empty from an older daemon. send-agent-messagetakes a new paramhuman_nonce. The tuios client sends it with a reply from the mail overlay, and only when it has one, since an older daemon refuses the param.- A message from
humanis stored withverified_human: truewhenhuman_noncematches a client attached to the same session now, over the same kind of connection: a nonce issued to an attach on the link socket verifies only a send on the link socket, and a local one only a local send. Otherwise it is stored withclaimed_human: true. The send result andread-agent-messagesboth report the two fields, and the mail overlay andtuios read-agent-messagesshow a claimed one as unverified. - Over a link, the hub relays the stream without reading it, so no flag in the
request can stand for a check the hub made. A client attached through the
link got its nonce from this daemon, and its reply verifies against that
attach; every other
from: "human"over the link is claimed.
The nonce alone is not an identity, since an agent can attach too. The next entry closes that.
Nonce scope. Every verb that takes human_nonce applies one rule, in the
daemon's humanNonceFor (internal/session/human_sender.go). The verbs are
respond, reply-approval, answer-ask, dismiss-attention,
mark-attention, send-agent-message from human, release-agent-message,
queue-prompt, cancel-queued, review-note, paste-image,
register-push, list-push and remove-push.
- A session is a boundary. A presence made with
attach-presence and
{"session": X}proves the person only for an act in session X. Anywhere else the verb fails withnot_human, and nothing is done. - A presence made with no session proves the person for every act that its
connection can reach. A connection that calls
restrict-connectionloses its presence. - The nonce of an attach proves the person for an act in any session, because
the Inbox of one client answers for every session.
send-agent-messageandpaste-imagealso need the attach to be to the session of the act. - An act that is in no single session, such as an Inbox item of another
machine, takes the nonce of an attach or of a presence with no session. A
phone for Web Push gets the Inbox of every session, so
register-push,list-pushandremove-pushare such acts. - The sender rules apply to both kinds: the caller is outside every pane, comes over the same kind of connection, and is the process that holds the nonce when the kernel gives the process ids.
A process inside a pane cannot act as the person. The daemon reads the
pid of every caller from its socket (SO_PEERCRED on Linux, LOCAL_PEERPID
on macOS) and counts the caller as inside a pane when the daemon is one of its
ancestors, when its controlling terminal is one of the daemon's pane
terminals, or when its environment names one of the daemon's windows in
TUIOS_PANE_ID or TUIOS_WINDOW_ID, or the daemon's socket in
TUIOS_SOCKET. The last two also place the client's hook commands and dock
components, which are automation and not the person. A process whose
record cannot be read counts as inside a pane. docs/AGENT_STATE.md, "Who can
act as the person", has the threat model.
send-agent-messageandask-agentwithfrom: "human"from such a caller fail with the new codeforbiddenand store nothing.send-agent-messageused to store the message asclaimed_human, andask-agentused to record the ask as from human. A caller outside every pane is served as before.- The attach reply to such a caller carries no
human_nonce, so nothing it sends verifies. verified_humanalso needs the sender to be allowed to act as the person, and, where the kernel gave both pids, to be the process that holds the attach. The tuios client sends its reply from the process that attached, so its replies still verify. A nonce copied to another process does not.read-agent-messageswithto: "human"from such a caller is served as a peek: it marks nothing read, and the result carries the new fieldpeek_forced: true. It used to mark the person's mail read.- A state push from an attached client inside a pane no longer marks the
focused window's finished turn seen, so
finished_unreadstays true until the person looks. - Over a link, only a stream the hub vouched for can verify. The hub puts
{"human":true}in the stream's open frame when the process that calledopen-host-connectionmay act as the person on the hub; the open frame's payload used to be empty, and an empty payload still means not vouched. The proxy on the far machine dials the new link-human socket (<socket>.link-human) for a vouched stream and the plain link socket for any other. An attach through the plain link socket gets no nonce, and afrom: "human"send over it isclaimed_human. A far daemon from before this change has no link-human socket, so the proxy falls back to the plain one; a hub from before it vouches for nothing, so no attach through it verifies on a far daemon that has the change. - Windows and the BSDs do not give this build the peer's pid. There every caller is treated as before, and the nonce is the only proof.
A reply the person did not type is not signed as theirs. The tuios client
sends a reply from its mail overlay without the attach nonce when any key that
send-keys, run-command or a tape script routed to the client opened,
edited or sent the reply line, so the daemon stores it as claimed_human. The
reply line reads automated reply: while that is so. Such a reply used to be
signed like one typed at the keyboard.
The Inbox. The daemon keeps one attention queue over every session, read
with the new verbs list-attention and dismiss-attention and followed with
the new event type attention (see list-attention). What
changes for an existing caller:
subscribewith notypesfilter now also deliversattentionevents. A consumer that switches ontypeand ignores the ones it does not know is unaffected; one that treats every unknown type as an error should filter.- The replay ring holds
attentionevents like any other retained event, so a resume withafter_seqreplays them. EventTypeNames, and so the accepted set ofsubscribe'stypesparam inlist-verbs, gainsattention.- The error catalog gains
not_human, raised bydismiss-attention(and, since peek and respond, byrespond). Its nonce is checked the way a reply fromhumanis, so a caller inside a pane is refused even with a live nonce. - Dismissing a
finisheditem marks the pane's turns seen, so itsfinished_unreadinlist-agentsgoes false, the same as focusing the pane in a client. Dismissing amailitem marks the person's mail in that thread read, the same as reading it in the mail overlay, and the attached clients get the usual read receipt. - The daemon writes the queue to
attention/items.jsonunder the session state directory, mode 0600, and reads it back on start. Onlyfinishedanderroreditems are kept across a restart; see list-attention. - A pane that stays on
needs_inputorerroredand reports a new kind, message or name updates its Inbox item. Noagent-stateevent is sent for it and no hook fires, the same as before: the state did not change.
Peek and respond. Two new verbs, peek-prompt and respond, read the prompt an agent is blocked on and answer it without attaching. What changes for an existing caller:
- The error catalog gains
prompt_changed, raised only byrespond. not_humanis now raised byrespondas well asdismiss-attention.- The harness manifest schema gains an optional
[answers]block under aneeds_inputscreen or title rule (see the answers block).schema_versionstays 1: an older build ignores the block, and a manifest without one loads as before. A block this build rejects fails the manifest's load. - The config file gains
[daemon] respond_from_shell, false by default. It is not an optionset-optioncan change. - The bundled Claude Code and Codex manifests declare answers. Their rules match exactly what they matched before; only the block is new.
- Later, a
needs_inputscreen rule gains the optional keysshow,tool_field,what_fieldsandhint_fields(see a prompt drawn as a dialog). An older build ignores them. The bundled Crush manifest uses them and declares answers for its permission dialog.
Approvals answered from the Inbox. The new verbs request-approval and
reply-approval let a harness hook hold a permission prompt until the person
answers it in the Inbox (see request-approval). It is off
unless [agents.approvals] in the config names the harness. What changes for
an existing caller:
- An
approvalitem gainsrequest_idandexpireswhile a hook holds it, andoptionsis now filled then: the decisionsreply-approvaltakes for it, withalways_scope(the rules always adds) whenoptionsholdsalways. All four are absent when nothing holds the item, which is every item when approvals are off. - While a hook holds an
approvalitem, itssummaryis the held call's line, the onerequest-approvalwas given, and a new message the pane reports meanwhile does not replace it. When the hold ends the item shows the newest message reported during it. With nothing held, a new message updatessummaryas before. - The
attentionevent'sclosedgains the reasonanswered. The closing item then carriesanswer(once,alwaysordeny) andanswered_by(the id of the client that answered). - A decision from
reply-approvalmoves the pane fromneeds_inputtoworkingstraight away, with an ordinaryagent-stateevent, instead of waiting for the harness's next report. - When an attached client of the person moves the session's focus to a pane whose approval is held, the hold ends with no decision and the harness asks in its pane. Nothing else about focusing a pane changed.
- The error catalog's
not_humanis also raised byreply-approval. - The Claude Code integration is now version 2: its
PermissionRequesthook entry gets a 310 second timeout instead of 5, so a hold can run. With approvals off the hook still returns within 500 ms.tuios integration statusreports a version 1 install as out of date until it is installed again. The opencode and Kilo plugins are version 2 as well: apermission.askedevent runs the hook and waits for what it prints, and sends a reply to opencode only when the hook printed one. The plugin names the tool call a request is about, fromtool.execute.before, so the Inbox line isapprove bash: <command>rather than opencode's permission name. - Only a call the Inbox can show whole on one line is held; every other prompt is reported as before and answered in the pane. See request-approval.
- In the Inbox,
spaceon a held approval does not open the peek of respond: the hook keeps the prompt off the pane, so there is nothing to read. The TUI says to answer with1,2or3instead.
The Inbox and the host listings cover every machine. A daemon with a
[hosts] table now keeps one stream per linked host over the link: it lists
the host's Inbox, then subscribes to the host's attention, agent-state,
agent-message, session and window events from the position the listing was
current to, resuming with after_seq after a redial and listing again after a
gap (see Following linked hosts). What changes for
an existing caller:
list-attentionalso lists the items of every linked host, withhostset and an id of the formhost:id, andcountscounts them. It used to list this machine's items only. A caller that wants the old answer passes the new paramhost: "local".sessionwithouthoststill names a session on this machine, so a far session of the same name is not in it.- Items gain
staleandseen_at: while a host's link is down its items stay, withstale: trueand when the host was last heard from, and the item is updated (anattentionevent with actionupdate) each time the mark changes. - A host item never carries
request_id,expiresoralways_scope, andoptionsis display only: a held approval is answered on the machine that holds it, soreply-approvalnever sees a host item's id. dismiss-attentionaccepts a host item's id. It hides the item on this daemon only, until the host changes it, and marks nothing on the host; the result carrieshost. A dismiss is the person's fact, and a second hub or a client on the host still sees the item.attentionevents of a host item carryhost. A subscriber that names asession,windoworpanedoes not get them, because it reads those names as this machine's; one that names none does.subscribetakes the new paramhosts. With it, theagent-state,session-createdandsession-closedevents of linked hosts are delivered too, each withhostset and only its identifying fields, andsessionandwindowmatch events of other machines. Without it nothing relayed from a host is delivered, so an existing subscriber sees what it saw.- The new event type
host-changed(inEventTypeNamesand the accepted set oftypes) says a host's link changed state or what the host holds changed. It carrieshostandstatusand nothing else.subscribewith notypesfilter delivers it. list-hostsgainsevents_push: trueat the top and, per host,events(live,polling, or empty while the link is not up) andevents_note, which says why a host is polled: its tuios is too old to have an Inbox or to resume its stream, and the note names the update.list-host-agentslists every session on each host, where it used to list only the host's most recently active one. Each row gainssession, and the rows gainagent_state_at,cwd,blocked_by,completion_seqandfinished_unread. The entry'ssessionis set only when every row is in the same session. Hosts are asked at once rather than one after another. A host that predatesall_sessionsonlist-agentsis asked session by session.list-host-sessionsandlist-host-agentsanswer for a host that did not answer with the rows it last gave, withstale: trueandfetched_at(unix seconds), beside theerrorit always had. Both gainevents.list-agentstakes the new paramall_sessions, and every row gainssession.- The
MsgHostsChangedpush to attached clients gainsChanged, the hosts whose link, sessions or agents changed. The daemon now sends it on such a change too, not only when the[hosts]table changes. An older client reads it as it always did, as a reason to list the hosts once.
A pane on another machine reports to the daemon that holds its window.
open-pane takes the new param window, the asking daemon's id for the
window, and then returns calls_token; the asking daemon opens the new verb
pane-calls with it (see Reports from a pane on another
machine). What changes:
- A hosted pane's process gets
TUIOS_PANE_ID, the owner's window id. It used to get none. - On the machine running the process,
set-agent-state,set-agent-meta,set-agent-sessionandwait-for(conditionagent-message) withwindowset to a hosted pane's id or window id,read-agent-messageswithtoset to it, andsend-agent-messagewithfromset to it are no longer answered there. They are sent to the owner and its answer is returned. A caller that is not in that pane getsforbidden, and when the owner is too old to take the call,protocol_mismatch. Such a call used to fail there withwindow_not_foundorsession_not_found. A forwardedsend-agent-messagemay attach only paths in the owner session's stash, like a message from the link, and a forwardedwait-foris capped at one hour on the owner and ends if the report channel drops. - The asking daemon may send
open-panetwice on one connection. A far daemon from before this refuseswindowwithinvalid_params, and the asking daemon then asks again without it, so a window still opens on that machine, with no reports from the pane. - The
sessionparam ofopen-panewas documented as exported asTUIOS_SESSION. It is exported asTUIOS_SESSION_REMOTE, as it has been since hosted panes stopped exportingTUIOS_SESSION; the description now says so.
A connection can restrict itself. The new verb restrict-connection (see
restrict-connection) narrows what one connection may
do for as long as it is open, and tuios mcp restricts every connection it
opens. A connection that never calls it is served exactly as before. What
changes for everyone:
- Every pane is started with
TUIOS_PANE_TOKENbesideTUIOS_PANE_ID. It is new, and nothing reads it butrestrict-connection. fanrecords on each session it starts the session of the pane that ran it, when a pane of this daemon ran it, andlist-worktreesrows gainlaunched_fromfor such a session. Rows of any other session are unchanged. The field is additive on the saved session record, so an older daemon reads a newer record and drops it. The record also holds that session's ID, and reach is checked by the ID, so a later session that takes the name reaches nothing. When that session ends, the sessions it started stop naming it. A record written before the ID names its lead by name alone. That name reaches nothing, and a restore drops it, so such a lead reaches its attempts again only byfan --joinor as the person.- On a restricted connection, every verb outside the table in
internal/session/conn_scope.goanswersforbiddenwith a hint namingrestrict-connection, and under scopeowna verb that names no session gets the caller's own session, not the most recently active one.
A shell's commands are facts the daemon reports. The daemon's emulator always recorded a shell's OSC 133 marks for the scrollback browser; it now turns them into events and facts (see run). A pane whose shell sends no marks is unaffected by all of this. What changes for everyone else:
- A subscriber with no
typesfilter now also receives the new event typesprompt,command-startedandcommand-finished, from every pane whose shell marks its commands. They carry the new fieldscmdline,exit_code,duration_msandcommand_seq. A consumer that switches ontypeand ignores what it does not know is unaffected; one that treats every type it does not know as an error has three more to ignore. list-windowsentries gainat_prompt,command_seq,running_cmdline,last_cmdline,last_exit_codeandlast_duration_ms, only for a window whose shell has sent a mark. Other entries keep their shape exactly. Such an entry also carriesmarks_commands, true once the shell has sent the C mark that starts a command, andprompt_marks_only: trueonce a lineruntyped came back to a new prompt with no C: the shell marks its prompts only (bash before 4.4 with the bash recipe, which ignores PS0, or a prompt theme that sends only A).at_promptis then false, since the daemon cannot tell a prompt from a running command there, andrunrefuses the pane withno_shell_integration. A subscriber sees one morepromptevent in that case: the new prompt that shows it.capture-paneaccepts the new sourcelast-command-output, so its documentedacceptedset inlist-verbshas three values.wait-for'ssourcewas documented with the same list and never took the new value; it is now documented asvisibleandrecent, which is what it always used.wait-fortakes the new conditioncommand-finishedand the new paramcommand_seq.- The new hook event
after-command-finishedruns on the daemon withTUIOS_COMMAND,TUIOS_EXIT_CODEandTUIOS_DURATION_MS. Every hook now gets those three variables, empty for the other events. - The new error codes
no_shell_integrationandnot_at_promptcome only from the new verbrunand the new capture source.
The Inbox has a seventh kind, ask. The new verb ask-human puts a
question to the person as an Inbox item, and the new verb answer-ask is how
the person's client answers it (see ask-human). What changes for
existing callers:
list-attentioncan return items of kindask, and itscountsobject has anaskkey. The kinds sort approval, ask, question, mail, errored, resume, finished;askis new between the first two.kindsacceptsask.attentionevents carryaskitems, and the close reasonsupersededis new: the pane asked a newer question.- An
askitem from a pane closes when the pane closes (window_closed), like a blocking item. popuptakeswait,capture_stdoutandtimeout. Without them it answers exactly as before; withwaitit answerspopup_resultinstead ofpopup_opened, when the command exits.- In the TUI's Inbox, the digit keys 1 to 9 pick an answer on an
askitem. On everything else, 1, 2 and 3 do what they did, and 4 to 9 do nothing, as before.
Selectors address many panes. A new param select takes a selector (see
Selectors) on list-agents, list-host-agents,
list-attention, wait-for, send-agent-message and ask-agent. A call that
sends none of the new params is answered as before. What changes:
- Every
list-agentsrow gainsgroup, the fan-out group of the pane's session, empty outside one.list-host-agentsrows carry it from a host that sends it. list-agentswithselectand nosessionlists every session, asall_sessionsdoes, and answers withselectand, withoutall,confirm. Withsessionit narrows that session and carries noconfirm, since a write by the same selector reaches every session.send-agent-messageandask-agentwithselectanswer with a new result shape,agent_messages_sentwithresults, oragent_replieswithreplies. Withoutconfirm, or with aconfirmfor a different set of panes, they send nothing and fail with the new codeconfirm_required, whose hint carries the new fieldconfirm.ask-agentno longer markswindowas required inlist-verbs, sinceselectreplaces it; a call with neither is stillinvalid_params.wait-fortakesselectandeveryforagent-state. Witheverythe result carriespanesandtotalinstead of onewindow.- A pane on another machine that sends its calls through its owner is refused
with
forbiddenwhen a call namesselect.
fan starts any program, several at once, from the caller's PATH. fan
takes the new params agents, prompts and env, and the new verb
start-agent starts one agent beside the caller. What changes for a caller of
fan:
agentis an argv string, split the way a shell splits words.agent"claude"means what it meant. A name no manifest recognises used to be refused withinvalid_params; it is now started if it is on thePATH, and refused as not installed otherwise, with the harness ids inavailableinstead ofaccepted, since they are no longer the only values.countandagentare no longer marked required inlist-verbs, sincepromptsandagentsstand in for them. A call with neither is stillinvalid_params.prompt_statushas the new valueheld, which a caller that waits forpendingto end should treat the same way. Thetuios fan --waitof this build does. A CLI from before it stops waiting atheldand reports the prompt as not sent.- A held prompt opens a
questionitem in the Inbox for the pane, with the summary "waiting at a screen tuios does not recognise: look at the pane and answer it". It closes when the prompt is typed or given up on, or when the pane's state changes. - The harness the daemon started stands in for detection while the wait runs,
so
unknownis not ready for an agent of a harness that can show idle even before the detector has named the pane. It used to be ready until detection ran. list-worktreesrows gainagent, the agent as it was named, andprompt_ready_by. Sessions offan_startedgainagentandcommand, and the top-levelcommandis an absolute path when the caller sent aPATH.- The
tuios fanCLI sends itsPATHinenv. Against a daemon from beforeenvit retries without it, unless--envwas passed.tuios fan --hostsends noenv, since a call over a link may not carry any, and refuses an explicit--env.
A repository can be named by its origin URL. new-worktree, fan and
start-agent take the new params repo_url, repos_root and clone (see
new-worktree), so a caller on another machine can name a
repository without a path. What changes:
repois no longer required whenrepo_urlis passed. Passing both isinvalid_params, and so isrepos_rootorclonewithoutrepo_url. A call withrepoalone is answered as before.- A
repo_urlthat matches no checkout is the new coderepo_not_found. fan's result gainsrepo_root, and both results gaincloned: truewhen the call cloned the repository.- With
clone,fanchecks its agents before cloning, so a clone is not made for a call that fails on an agent. Withoutclonethe order is as it was: the repository first. start-agentalso takesrepoandargs, creates a named session that does not exist, and answers withsession_id,created_session,workspaceandcwd.
The new verb bundle-worktree changes no old one. A daemon from before it,
or from before start-agent, answers unknown_verb, and one from before
repo_url answers invalid_params naming it; the CLI turns both into "tuios
on HOST is too old".
start-agent can run an agent headless over a protocol. start-agent
takes the new param protocol, acp or codex (see
start-agent). Without it nothing changes. What changes for an
existing caller:
request-approvalholds a permission for a panestart-agent --protocolopened even when[agents.approvals]does not name the harness: choosing the protocol is the opt in. Every other rule of the verb applies to it unchanged, and every other pane is refused withdisabledas before.list-agentsrows gainprotocol:acporcodexfor such a pane, empty for every other.- A pane a protocol names is ready only on a state it reports.
unknownis never ready for it, whatever its harness, since its screen is a transcript no manifest rule reads. Withoutprotocolthe wait is as before. - A daemon from before
protocolrefuses it withinvalid_paramsnaming it, so an old daemon never starts the agent in its TUI instead. - The mark is the daemon's own, by window id, and nothing a caller sends sets
it. It is not saved: after a daemon restart a restored pane's approvals
follow
[agents.approvals]like any other pane's.
Calls from a pane are held to the pane's grants. Every pane holds grants
(read, write, fan, respond, admin; see pane-grants),
and the daemon checks every JSON verb and every client protocol message from
a connection placed in a pane against them before the handler runs. With no
[agents.permissions] in the config and no pane given grants of its own,
every pane holds admin, which is everything a pane could do before, and
every call is answered exactly as before. What changes:
- Every pane is started with
TUIOS_PANE_GRANTS, the grants it holds as it starts, comma separated, ornone. helloanswers withpane_grants: true.new-window,start-agentandfantake the new paramgrants. A call that sends none is answered as before, except from a pane that does not holdadmin: the new pane then holds the caller's own grants rather than the default. Agrantsthe calling pane does not hold isforbidden.respondmay now be answered for a pane that holdsrespond, without ahuman_nonce, on a pane in its reach. Its result then carries the new fieldby_pane. A pane withoutrespondgetsnot_humanas before, whose hint now says the grant exists.admindoes not includerespond, so no pane can answer a prompt unless the person gave it the grant.list-windowsentries gaingrantsfor a pane given grants of its own. The entries of every other pane keep their shape.- The session record's windows gain a daemon-owned
grantsfield. It is additive in JSON and gob, a client sync can neither set nor clear it, and an older daemon reads a newer record and drops it, so a pane restored by an older daemon holds that daemon's (unchecked) rights. - For a pane without
admin: a verb its grants do not cover answersforbiddenwith a hint namingpane-grants, the pane's grants and the config key; a verb that names no session gets the pane's own session, not the most recently active one; a subscription carries only the sessions the pane may read; and every client protocol message except the hello answers an error, so such a pane cannot attach or userun-command. The error for the command message namesrun-commandand points atget-window. - For a pane without
admin,send-text,send-keys,runandask-agenton another pane answerforbiddenwhen the target holds a grant the caller does not, or when the target is onneeds_inputand the caller does not holdrespond(see pane-grants). A call with no window is pinned to the pane focused when it is checked.send-keysfrom such a pane is written to the target's terminal even when a client is attached, so its keys never reach the window manager. Calls from outside every pane, and from a pane holdingadmin, are answered as before. tuios get-windowreads with the new verbget-windowinstead of the client protocol'sGetWindowcommand, so a pane holdingreadmay run it on its own session. The verb answers asGetWindowdid, from the attached client when there is one, so the--jsonoutput keeps its shape; with no client attached it gains the shell fieldslist-windowsgives a window. A window that matches nothing is now reported the waylist-windowsreports it, with the available windows. Against a daemon from before the verb the command falls back toGetWindow.restrict-connectionand pane grants share the code that fills in and checks a caller's session and window. A restricted connection is answered as it was; a refusal of a parameter that reaches every session now reads "and the connection is restricted to its own", the words it used before.
The new verbs pane-grants, set-pane-grants and get-window change no
old one.
send-keys with a window goes to that window. With a client attached,
send-keys used to hand every parsed key to the client, which read them as
the person's keys and ignored window: in window-management mode an arrow
moved the selection, in terminal mode it went to the focused window, and the
call answered ok either way. Now:
- With
window, the keys are written to that window's terminal whether or not a client is attached.PREFIXwithwindowand a client attached isinvalid_params, because the window manager acts on the focused window and not the one named. A caller that sent the leader chord with a window leaves the window out. - Without
window, keys go to the attached client as before, or to the focused window's terminal when none is attached.literalalways writes to a terminal: routed to the client it waited out the 10 second timeout and answeredcommand_failedon a send that had worked. - Every key is parsed before anything is sent, on both routes. Names are
case-insensitive and take the spellings of tmux, curses, vim and the DOM:
up,arrow-up,ArrowUp,KEY_UP,<Up>,PgDn,BSpace,C-c,M-x,^C. New names:BTab(shift+Tab) andshift+on named keys. A token written as an escape sequence (\e[A,\x1b[A,\033[A,^[[A) is sent as those bytes. A word that looks like a key name and is not one (Dwon,KEY_FOO,F13,a+b) used to be typed as its letters; it is nowinvalid_paramswithparam: keys, the key names inacceptedand the closest name indid_you_mean, and nothing is sent. A plain lower-case word such aslsis still typed. - Arrows,
HomeandEndwritten to a terminal follow the pane's application cursor keys mode (DECCKM):ESC O Awhen the program turned it on, aslessandvimdo,ESC [ Aotherwise. Modified named keys use xterm's form (ctrl+UpisESC [ 1 ; 5 A), wherealt+Upused to beESC ESC [ A. - The new param
repeat(1 to 1000, default 1) sends the sequence that many times. - The result gains
sent_to(windoworclient),keys(how many were sent), and forwindowthewindow_idandwindowname it went to.tuios send-keysprints that assent 3 keys to window docs (3a42ab8f)and takes--repeat(-N) and--json.
A window's name wins over another window's title. A window target that
is not an id, index or prefix used to match a name or a title alike, so a
program that set its title to another window's name made both ambiguous. A
name given with new-window or set-window --name is now matched first, and
titles only when no name matches. An ambiguous prefix or name still answers
window_not_found; the message now lists the index, short id and name of
each window it matched, and the hint says it matched more than one.
new-window can print the id alone. tuios new-window --print-id prints
the full window id and nothing else, for id=$(tuios new-window --print-id).
new-window waits for an attached client to place the window. With a
client attached, new-window now answers once the client has placed the
window and sized its terminal, up to one second, so unplaced is false in
the usual case. It used to answer at once with the nominal geometry, and a
program started in the pane straight after the call got a resize while it
drew: glow's pager then showed a blank screen and ignored keys. With no client
attached nothing changes. A client that does not place the window within the
second leaves the answer as it was, unplaced: true.
The agent review, triage, queue and approval verbs. Twelve verbs are
new: review-diff, review-note, send-review, compare-fan,
verify-fan, keep-fan, mark-attention, agent-activity,
queue-prompt, list-queued, cancel-queued and get-approval (see
Agent review, triage and queue verbs).
Every one is built; none answers internal with "not built yet" any more.
The older verbs change as follows, and a
caller that sends nothing new is answered as before:
request-approvaltakeskind(approvalorplan),plan,tool,target,cwdanddeny_message(see Risky approvals and plans). An unknownkindisinvalid_params.reply-approvaltakesrisk_ackandplan_sha, andrespondtakesrisk_ack. What changes for a caller that sends neither is under Risky approvals and plans.set-agent-statetakesactivity, one hook event for the pane's activity ring. Itseventmust be one ofprompt,tool,tool_done,tool_failedorturn_end, or the call isinvalid_paramsand nothing is applied. A valid one is not recorded yet, and the state part of the report applies exactly as without it.list-attentiontakesinclude_snoozed. Nothing can be snoozed yet, so it lists what the plain call lists.kindsaccepts the new kindplan, which sorts right afterapproval.- Attention items gain
snoozed_until,marked_unread,risk,deny_message,plan_linesandplan_sha, each omitted when unset, and a close may carry the new reasonsnoozed. An item mirrored from a linked host keeps that host'sriskandplan_lines, display only. get-agent-stateand everylist-agentsentry gainqueued, the length of the pane's delivery queue, 0 until the queue is built. The synced window state gainsagent_queued, omitted when zero and taken from the daemon's own state on every client push. A row of another machine's agents (list-hostswith agents) keeps that host'squeued, held to 0 through[agents.queue]'s ceiling of 64, display only.- A worktree's record gains
verify, the lastverify-fancheck in it, omitted when none has run. - The event type
agent-activityexists and is opt-in: a subscription receives it only when itstypesnames it, so a subscriber that names no types never sees it. Nothing publishes it yet. - The error codes
not_repo,no_notes,queue_fullandrisk_unacknowledgedare in the catalog. - An
approvalitem'sriskcan namecut short: the line nobody holds was clipped, so the rules could not read all of it. An allow acknowledges it inrisk_acklike any rule. A daemon started with no config file at all marks approvals with the shipped rules, where it used to mark nothing.
The activity ring is built. agent-activity answers (see
agent-activity) instead of internal, and these older
verbs change:
set-agent-staterecordsactivityin the pane's activity ring when the report passes the identity guard (the nested-session guard behindforeign_sessionandforeign_harness), whether the state part applies or not: aPostToolUserefused byif_statestill records its tool result. A report the guard refuses records nothing, even whenif_staterefused it first. The answer gainsactivity_recorded(bool), present only when the call sentactivity. The state part is handled exactly as before.set-agent-statewithactivityalso moves the pane's metadata: atoolsetsnowto<tool>: <target>, apromptsetspromptto its first line and clearsnow, and atool_failedorturn_endclearsnow.- The daemon clears
nowwhenever a pane's agent state moves to one other thanworkingorneeds_input, however it moved: a report with or withoutactivity, a screen rule, an OSC sequence, the foreground detector or the silence timer. A pane at rest never keeps a stalenow. Amodelin the activity setsmodel(sourcehook) when the pane does not already show that model from any source. These keys ride the window state'sagent_metalike any other, soget-agent-state,list-agentsand older clients see them as ordinary metadata. set-agent-metarefuses the keysnowandprompt, set or removed, withinvalid_params: they are written by tuios from hook activity.clearleaves them in place, whateversourceit names.set-agent-metano longer pushes state for a call that changes nothing. A key set to the value it holds, by the source that wrote it, keeps its expiry unless less than half of the TTL is left, and a call where every key is like that leaves the session version alone and sends clients nothing. A status line that writes the same values several times a second used to push state each time. The answer is the same either way.- The event type
agent-activityis published, one event per entry, carrying the entry asentry. It is not kept in the replay ring, likeoutput: a resume whosetypesnames it gets anot_retainedgap when one was published afterafter_seq. Read the ring withagent-activityinstead.
tuios now feeds set-agent-meta itself. No verb changes; what changes is
who calls two of them, and a client that draws metadata now has some to draw:
- A protocol pane (
tuios agent-proto, whatstart-agent --protocolruns) callsset-agent-metafor its own pane with the sourceprotocoland the keysmodel,context,costandplan, each only when its value changes, and all of them again at the start of each turn, so values a restarted daemon or a clear tononelost come back. It also callsset-agent-statewithactivityfor each prompt, tool call and finished turn.stateis the state the pane last reported (workingduring a turn, the turn's end state forturn_end) andif_stateisnone: the daemon records the activity and refuses the state part on every pane that has a state, so the call restamps noagent_state_at, rewrites no message and pushes no state. Only a pane whose state was lost mid-turn (none, after a restart or a clear) gets its state back from it. These calls and the metadata go on a connection of their own, off the pane's input loop. It sends activity only to a daemon whoselist-verbslistsactivityforset-agent-state, and nothing extra to an older one. - An ACP protocol pane whose agent names its model in
session/newmodelsnow says so in the transcript's first line:connected to opencode 1.2 (Claude Sonnet 4)where it saidconnected to opencode 1.2. A Codex pane said it before, and still does. tuios agent-statusline(Claude Code's status line, opt in, and the opencode and Kilo plugin) callsset-agent-metafor its own pane with the sourcestatuslineand the keysmodel,contextandcost, at most once every 15 seconds per pane while they change, and never with a TTL. What the interval held back is sent at the end of the turn: by Claude Code'sStophook (tuios agent-hook claude-code, which then callsset-agent-metafor its own pane as well asset-agent-state), and by the opencode plugin's--turn-end.- The opencode and Kilo plugin is version 3, so
integration statusreads a version 2 install as out of date until it is installed again.
The delivery queue is built. queue-prompt, list-queued and
cancel-queued now work (see
The delivery queue), and no longer answer "not built
yet". What changes for a caller that uses none of them: nothing, since a pane
has no queue until something is queued. For one that does:
queue-promptfor a pane that runs no agent tuios knows of isinvalid_params, and forhumanit isno_keyboard. Ahuman_noncethat does not verify isnot_human, not a quiet fall back to the caller's own name.list-queuedwith no window lists every pane of the session, not the focused one, and its entries gainsession,window,nameandfrom. Its result hastypequeued_promptsandsession.cancel-queuedwith anidand no window finds the entry in any pane of the session.idtogether withallisinvalid_params. An entry being typed, or one the caller may not drop, isforbidden; an id that is not queued isinvalid_params. Its result hastypequeue_cancelled.get-agent-stateandlist-agentsreportqueuedas the pane's queue length, and the synced window state carries a non-zeroagent_queuedwhile something waits. A client that does not know the field drops it.- An Inbox question may carry the summary "your queued message was typed but
NAME did not take it: look at the pane", on the pane's blocking key, for a
queued message the agent showed no sign of taking. It is an ordinary
questionitem and closes like one. It also closes, and the stalled message leaves the queue, when the pane shows within ten minutes that it took the message after all: it turnsworking, or its screen shows a turn running with its input box empty. A finished turn or aneeds_inputdoes not drop the message, since it may still be in the box. [agents.queue] maxis read at start and again when the config file changes.- One message per rest holds across an emptied queue: a message queued just
after the last one was typed waits for a rest the agent reaches after that
typing, and
deliveringis false until then. The typing time is the moment the Enter went out, so a turn that ends while the daemon is still watching for the agent to take the message counts as that rest. - For a pane whose harness cannot show working (the daemon counts its output as taking a message), a rest after a typed message is also output followed by 5 seconds of silence, since such a pane may never change state.
cancel-queuedof a stalled message closes its question, and the messages behind it are typed at the pane's next rest, not in the rest the stalled one was typed into: its text may still sit in the agent's input box.- A linked machine that gave no name drops, with
cancel-queued, only what it queued on the same connection.queue-promptandcancel-queuedfrom a pane on another machine, forwarded through its report channel, areforbidden.
The tuios client replies, and reads the recap. No verb changed; the client now calls three it did not:
queue-promptwithhuman_noncewhen the person sends a reply from the Inbox (ron a finished or errored item, or on a rail agent row). A reply that any key fromsend-keys,run-commandor a tape touched is not sent at all, so everyhumanentry the client queues was typed at its keyboard.list-queuedand thencancel-queuedwithhuman_nonceforxon a rail agent row with messages queued, dropping the newest entry not being typed. An undo is a newqueue-promptwith the same text. Neither is sent for a key fromsend-keys,run-commandor a tape, so everyhumandrop and undo the client sends was pressed at its keyboard too.agent-activitywithrecapandsince(when the person last had the pane in front of them) for the Inbox's Finished detail and for the dock line when the person comes back to a pane. Nothing polls it.
Against a daemon without queue-prompt, the first reply answers
unknown_verb and the client stops offering reply; against one without
agent-activity the recap falls back to what the client counted itself.
Fan compare, verify and keep are built. compare-fan, verify-fan and
keep-fan answer instead of internal (see compare-fan,
verify-fan and keep-fan). What changes for an
existing caller:
verify-fantakesenv, with the rules offan'senv: a call over a link that passes it is refused withforbidden.- A worktree's
verifyrecord gainsnote, omitted when empty, saying why a failed check has no exit status: it timed out, or the daemon restarted while it ran. A record saved asrunningby a daemon that has since restarted is reported bycompare-fanasfailedwith that note; the saved record itself is not rewritten. verify-fanopens a window namedverifyin each fan session it reaches. An attached client shows it like any other new window, without focusing it. It closes when the check passes and stays open when it fails, until someone presses enter in it.- The daemon's shell facts gain the time the last command finished, which
compare-fanreports aslast_command.at. No other verb reports it. tuios fan keepcallskeep-fan, and falls back to the loop overremove-worktreeit ran before when the daemon answersunknown_verb. Its output and--jsonshape are unchanged, except that a sibling left dirty is described by the daemon's refusal plus a sentence naming--stashand--force, and siblings are now matched by the repository's main checkout rather than its directory name, so two checkouts that share a name no longer count as one fan.
The Inbox's lifecycle is built (mark-attention). The person can snooze an item, wake it, mark a finished pane unread, and restore an item they dismissed or snoozed in the last 10 seconds. What changes for a caller of the older verbs and for a subscriber:
list-attentionwithinclude_snoozedlists the snoozed items after the open ones, each withsnoozed_until. They are not incounts, which say what is waiting. Without the parameter the listing is as before and leaves them out.- A snooze publishes a
closewith the reasonsnoozed, the closing item carryingsnoozed_until. When the item wakes (its time comes, its fact changes, the person wakes or restores it) anopenfollows with the sameidandsince, so a subscriber that knows nothing of snoozing sees the item close and open again. - When the fact behind a snoozed item ends (the pane leaves
needs_input, a client focuses a finished pane, the pane or session closes, the thread is read), acloseis published for it with that reason. A subscriber that took thesnoozedclose as final gets aclosefor an id it no longer holds, which changes nothing for it. dismiss-attentionaccepts the id of a snoozed item. A dismiss of anything but anoutboxitem or anaskcan be undone for 10 seconds withmark-attentionrestore, which reopens it with its id andsince. A held approval or plan comes back withoutrequest_id, since the dismiss ended its hold, and a plan comes back as kindapproval, withoutplan_sha,plan_linesordeny_message.- A hold that
request-approvalstarts on a pane whose approval the person snoozed wakes the approval first, so the Inbox can answer it. - The saved queue holds snoozed
finishedanderroreditems withsnoozed_until, and they come back asleep after a restart; one whose time passed while the daemon was down wakes on start. An older daemon reading the file lists them as open. not_humanis raised bymark-attentionas bydismiss-attention.
Reviewing is built. review-diff, review-note and send-review answer
instead of internal (see review-diff,
review-note and send-review). What changes for
an existing caller:
remove-worktree, and sokeep-fanandtuios worktree rm, drop the review notes kept on the worktree they remove, whether or not the directory was still there. Their answers are unchanged.- A window closing drops the review notes kept for that pane. Nothing is published for it.
- The daemon keeps a new file,
review/notes.jsonunder the state directory (mode 0600), besideattention/items.json. An older daemon ignores it. send-review's result, aslist-verbsdescribed it before it was built, nameddelivered. It carriesdeliveringinstead, withqueue-prompt's meaning, and gainsidsandqueued: the message is typed by the delivery queue, so the answer can only say whether it is next and the agent at rest.review-diff's result gainssession,window,uncommitted,against_treeandnotesbeyond whatlist-verbslisted before it was built, andreview-note's gainssession,window,worktree,id,removed, and onclearkept, the count of notes left because the caller may not change them.- A pane without
adminmayaddoredita note only on a pane it could type into itself (one that holds nothing it does not), since a note is typed into its pane when it is sent. Elsewhere it isforbidden. send-reviewlabels every note written by someone other than the sender with its author ("(written by pane NAME, not by the person)"), and withholds a note whose author may not type into the pane now, or whose pane is gone: it is not typed and not marked sent, and the result lists it inwithheldwithwithheld_reason. When every note picked is withheld it isforbiddenand nothing is queued. Before this, a pane's note sent by the person was typed under the header "from the person" with nothing to tell it apart.- A pane whose process runs on another machine is
not_repo, and its hint now points attuios worktree pullinstead of aHOST:SESSIONreview: reviewing a session on a linked machine is not supported yet, andtuios reviewrefuses aHOST:target before it dials. - A message has a state between unread and read: seen.
read-agent-messageswithtoset to a window andpeek: truestampsseen_at(unix nanoseconds) on the unread directed messages it returns, and leavesread_atat zero, but only when the caller is that inbox's reader: the caller runs in the panetonames. A peek of a pane's inbox from another pane, from outside every pane, or over a link stamps nothing, because nobody looked as the recipient. Forto: "human"the reader is a caller that may act as the person (the CLI outside every pane, an attached client). A peek that getspeek_forced, and a read with noto, stamp nothing. A marking read setsread_atand keepsseen_at. Messages gainseen_atandwas_seen(true when the message was seen, and not read, before this call), each omitted when unset. The answer gainsseen(how many of theunreadmessages were already seen),marked_readandmarked_seen(how many messages this call changed).unreadkeeps its meaning: the returned messages not read before this call, seen ones included, andunread: truestill returns the seen ones.list-agentsentries gainseen, the part ofunreadthat was seen. Attention items of kindmailgainseen, the part ofcountthat was seen. TheMsgAgentMailpush gainsseen_idsandseen_at, a receipt for a peek. Compatibility: a peer that does not know these fields sees a seen message withread_atzero, so it counts it as unread, which it still is. A client that gets a receipt with onlyseen_idsignores it. Nothing is required of an older peer.
list-verbs
list-verbs is the discovery entry point. It returns every verb with its full
parameter schema and runnable examples, the protocol range, the error-code
catalog, and the envelope shapes, which together are enough to drive the control
plane without reading this document.
Request:
{"id": 1, "verb": "list-verbs"}Response (abridged):
{"id": 1, "result": {
"type": "verb_list",
"version": 1,
"min_version": 1,
"daemon_version": "1.4.0",
"verbs": [
{
"verb": "capture-pane",
"description": "Capture a pane's content.",
"params": [
{"name": "session", "type": "string", "description": "Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one."},
{"name": "source", "type": "string", "description": "Which buffer to capture.",
"accepted": ["visible", "recent"], "default": "visible"}
],
"examples": ["{\"id\":1,\"verb\":\"capture-pane\",\"params\":{\"session\":\"work\",\"source\":\"recent\"}}"]
}
],
"error_codes": [{"code": "session_not_found", "description": "The named session does not exist. ..."}],
"envelope": {"request": "{\"id\":<any>,\"verb\":\"<name>\",\"params\":{...}}", "...": "..."}
}}Pass a verb param to describe only that verb. Each parameter carries its
name, type (string, int, bool, []string, []int, or object for
a JSON object such as set-agent-meta's tokens), description, and
optionally required, accepted, and default. The accepted lists are the
same lists the handlers enforce, so they cannot drift from the implementation.
A verb's returns use the same shape. A returned field that can be null as
well as its type carries "nullable": true, as evidence_age_ms does.
A verb that keeps the connection after its reply, as an event stream, a byte
stream or a connection to something else, carries stream. "stream": {}
means it always does, as subscribe and stream-pane do. With param it
does only when that param is one of values, a bool param as "true":
speed-test has {"param": "mode", "values": ["sink", "source"]}. A caller
that sends one request and reads one reply, such as tuios call, cannot make
such a call.
From the shell, tuios list-verbs and tuios list-verbs --json render the same
catalog.
Control Protocol
Drive a TUIOS daemon from scripts and programs with line-delimited JSON on its socket.
Verbs: Discovery
Verbs: Discovery: part of the Control Protocol of TUIOS.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.