Program Status

Any program in a pane can say what it does: a build, a deploy script, a package manager or a coding agent. The program writes one escape sequence. TUIOS shows the state in the rail, the Inbox and the pane's title bar. The program needs no hook, no socket and no plugin.

The sequence is the Program Status Protocol, OSC 7501, revision 0.2. Read the specification for the full grammar.

What a program sends

A report is one OSC sequence. It holds key=value pairs, separated by :, and ends with ST (ESC \) or BEL.

printf '\e]7501;state=working:app=build:progress=40:msg=Q29tcGlsaW5n\e\\'

Each report replaces its record. A key that a report does not send is gone from the record. Send app and title in every report that must keep them.

Report from a script

tuios status writes the sequence and does the base64. It needs no daemon, so a script can use it in any terminal.

tuios status working --app build --msg 'Compiling' --progress 40
tuios status blocked --kind permission --app deploy --msg 'Approve deploy to production?'
tuios status done --app build --msg 'Built 12 crates'
tuios status error --app build --msg 'Linker failed'
tuios status --clear

The command writes to the controlling terminal (/dev/tty). The report stays correct when the script's output goes to a file or a pipe. --stdout writes to standard output instead. tuios status refuses a report that a terminal must discard, and says why.

A shell function

A script that cannot call tuios can use this function:

status() {
  printf '\e]7501;state=%s:msg=%s\e\\' "$1" "$(printf '%s' "$2" | base64 | tr -d '\n')"
}

status working "Syncing photos"
rsync -a ~/Photos backup:/photos && status done "Photos synced" || status error "rsync failed"

A program that exits right after its work must report done or error first. That record then stays for you to find.

The states

TUIOS turns the most urgent record of the pane into the pane's agent state:

state=clear with an id removes that record and every record under it. Without an id, it removes every record of the pane.

More than one record

A program can keep one record for each of its parts. The id is a path: build/test is under build, and build is under the root record.

• The pane shows the most urgent record. blocked comes first, then error, done, working and idle.
• A record without app takes the app of its nearest parent.
• A pane holds at most 256 records. A new record past that removes the record that changed least recently.

What TUIOS shows

• The rail. The agent row shows the app as the agent's name and the progress beside it, such as build · 40%. The second line shows the title and the message. The progress token of [appearance.sidebar.agent_row] sets where the progress goes.
• The Inbox. A blocked record opens an approval or a question item. An error record opens an error item, and a done record opens a finished item. The item names the pane by its title and its id, such as build [3f2a9c1e]. The detail of the item lists every record of the pane. For kind=auth the Inbox gives no answer. Type the login in the pane.
• Notifications. A record raises the same alerts, hooks and push notifications as any other agent state. A pane whose state comes from OSC 7501 sends a notification, a bell, a sound or a client hook at most once in 30 seconds.
• Scripts. tuios get-agent-state and tuios list-agents report source: "program" and the records as program_status.

A harness hook in the same pane wins. When a hook reports, the records still show, but the pane's state is the hook's. When the last record ends, TUIOS clears the state and looks at the pane again.

How long a record stays

There is no heartbeat. A program does not have to send its state again.

A shell without OSC 133 marks does not tell TUIOS when a prompt starts. TUIOS then records the foreground process group with each report. When no process is left in that group, the program has exited and its records go.

A program that reports and exits at once, such as tuios status working typed at a prompt, can be gone before TUIOS reads the foreground. Its record then stays until the next prompt mark, the next report or a clear. A shell with OSC 133 marks does not have this gap.

Keys from tuios send-text or tuios send-keys do not count as your typing. Keys from an attached client do.

Check for support

A program sends OSC 7501 ; ? ST. A terminal that reads the protocol answers with the same sequence. TUIOS answers from the pane's emulator, with the terminator that the query used.

Send a primary device attributes query (CSI c) after the question. If that answer comes first, the terminal does not read the protocol.

TUIOS sends back only this fixed answer. A program cannot read the records.

Limits

A report that breaks a limit is discarded. TUIOS applies nothing from it.

• A msg or title that does not decode, is not UTF-8, or holds a control character discards the report.
• A report without state, or with an unknown state, is ignored. So is a report with a bad id.
• A kind with a state other than blocked is ignored. So is a progress outside 0 to 100.
• TUIOS shows markup as text and removes invisible format characters before it shows a message.
• app is only a label. TUIOS does not look it up as a harness.

TUIOS in a terminal that reads OSC 7501

TUIOS is a program too. In a terminal that reads the protocol, TUIOS reports the agent states of its panes to that terminal. Each pane has one record, with the id <session>/<pane>. A client asks its terminal OSC 7501 ; ? at start, and reports only when the terminal answers. When a client detaches, it clears its records.

To turn this off:

[agents]
host_program_status = "off"   # "auto" is the default

Related