Skip to content

feat(cli): report agent lifecycle with OSC 7501 - #1663

Open
demonodojo wants to merge 3 commits into
CodebuffAI:mainfrom
demonodojo:feat/osc-7501-program-status
Open

demonodojo wants to merge 3 commits into
CodebuffAI:mainfrom
demonodojo:feat/osc-7501-program-status

Conversation

@demonodojo

Copy link
Copy Markdown

Terminals such as Herdr only list a program as an agent when it reports working/blocked/idle/done over the open Program Status Protocol. Emit those states from the CLI's own turn and ask-user state, and clear them on exit.

Generated with Codebuff 🤖

Terminals such as Herdr only list a program as an agent when it reports
working/blocked/idle/done over the open Program Status Protocol. Emit those
states from the CLI's own turn and ask-user state, and clear them on exit.

Generated with Codebuff 🤖
Co-Authored-By: Codebuff <noreply@codebuff.com>
@codebuff-team

Copy link
Copy Markdown
Contributor

Nice shape for a first PR: program-status.ts is cleanly separated from the hook, the tests in program-status.test.ts actually exercise nextProgramStatusUpdate's state machine (idle → working → blocked → done), and reusing writeTerminalControlSync/the /dev/tty pattern from terminal-title.ts keeps this consistent with how the CLI already does out-of-band terminal writes. Hooking reportClear() into renderer-cleanup.ts so the status doesn't get stuck on exit is the right instinct.

Two things I'd want resolved before this is portable:

  1. BlockedKind defines 'permission' | 'question', but nextProgramStatusUpdate in program-status.ts (lines ~46-48) hardcodes kind: 'question' whenever isAsking is true. useProgramStatus only reads askUserState !== null from the chat store, so permission prompts and clarifying questions are indistinguishable to the terminal even though the protocol was designed to tell them apart. Either drop 'permission' from the type until it's wired up, or thread the actual ask-user kind through.

  2. OSC 7501 isn't a registered/reserved sequence - it's specific to Herdr. Worth confirming in the PR description what happens on terminals that don't ignore unrecognized OSC codes gracefully (some emulators echo unknown private-use OSCs visibly rather than swallowing them). A one-line note on what was actually tested (which terminals, what happens on non-Herdr ones) would make this much easier to evaluate for porting.

The core wiring and tests are good; I'd like the kind-mapping gap closed and terminal-compatibility risk addressed before recommending a port.

@codebuff-team codebuff-team added bot:triaged Classified by the community triage bot pr:needs-work Right idea, not mergeable as written labels Nov 14, 2026
The block kind advertised 'permission', but the CLI has no permission
prompt, so every blocked report claimed 'question' anyway. Narrow the
type to the one kind the CLI can actually raise and document how unknown
OSC 7501 behaves on terminals that do not implement it.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@demonodojo

Copy link
Copy Markdown
Author

What

Reports the CLI's lifecycle to Herdr with OSC 7501, writing straight to /dev/tty (same approach as terminal-title.ts, since OpenTUI captures stdout), and clears the status from renderer-cleanup.ts on exit so it does not get stuck.

Sequence: ESC ] 7501 ; state=<state>:app=<program>[:kind=<kind>] ESC \ with state one of idle, working, blocked, done, clear.

Blocked kind

blocked only ever carries kind=question: ask_user is the CLI's only blocking prompt. permission was removed from BlockedKind instead of threading a kind through, because the CLI has no permission prompt to report — advertising it would have the terminal announce a state the UI never shows. It can come back when such a prompt exists.

Terminal compatibility

OSC 7501 is not a registered/reserved sequence; it is Herdr's private convention. Terminal parsers consume an OSC string up to its terminator and discard the codes they do not implement, so xterm/VTE, iTerm2, WezTerm, kitty, Alacritty and Windows Terminal print nothing for this report. The write is best-effort and silent, so a non-interactive process without /dev/tty is unaffected.

Tested here: unit tests cover the emitted bytes and the idle → working → blocked → done state machine. No manual test in Herdr or in a graphical emulator was run.

Tests

bun test src/utils/__tests__/program-status.test.ts  →  10 pass

Comment thread cli/src/utils/program-status.ts Outdated
Comment on lines +17 to +18
import { IS_FREEBUFF } from './constants'
import { writeTerminalControlSync } from './terminal-io'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wrapper needs the env helper. terminal-title.ts keeps isInTmux/isInScreen private, so this mirrors them here for now; hoisting both into terminal-io.ts would remove the duplication.

Suggested change
import { IS_FREEBUFF } from './constants'
import { writeTerminalControlSync } from './terminal-io'
import { IS_FREEBUFF } from './constants'
import { getCliEnv } from './env'
import { writeTerminalControlSync } from './terminal-io'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved in 9408534. isInTmux, isInScreen and the passthrough wrapper were hoisted into cli/src/utils/terminal-io.ts as wrapForMultiplexer(sequence, env). terminal-title.ts now calls that shared helper instead of keeping its private copies, and program-status.ts imports it, so there is no duplicated wrapper. The wrapper's behaviour is covered by the new cases in terminal-io.test.ts.

Comment on lines +85 to +93
export function reportProgramStatus(
state: ProgramStatusState,
options: { kind?: BlockedKind; ttyPath?: string } = {},
): boolean {
return writeTerminalControlSync(
buildProgramStatusSequence(state, { kind: options.kind }),
options.ttyPath,
)
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bare OSC written to /dev/tty is dropped by tmux and screen; both only forward inside a DCS passthrough. buildProgramStatusSequence stays pure and tested, reportProgramStatus wraps on the way out.

Suggested change
export function reportProgramStatus(
state: ProgramStatusState,
options: { kind?: BlockedKind; ttyPath?: string } = {},
): boolean {
return writeTerminalControlSync(
buildProgramStatusSequence(state, { kind: options.kind }),
options.ttyPath,
)
}
export function reportProgramStatus(
state: ProgramStatusState,
options: { kind?: BlockedKind; ttyPath?: string } = {},
): boolean {
return writeTerminalControlSync(
wrapForMultiplexer(buildProgramStatusSequence(state, { kind: options.kind })),
options.ttyPath,
)
}
/**
* tmux and screen drop escape sequences written to /dev/tty unless they
* arrive inside a DCS passthrough. Same wrapper as `buildTitleSequence` in
* terminal-title.ts, which keeps its helpers private; hoist both later.
*/
function wrapForMultiplexer(sequence: string): string {
const env = getCliEnv()
if (env.TMUX) {
return `\x1bPtmux;${sequence.replace(/\x1b/g, '\x1b\x1b')}\x1b\\`
}
if (env.STY || (env.TERM ?? '').startsWith('screen')) {
return `\x1bP${sequence}\x1b\\`
}
return sequence
}

@josemi-entaina josemi-entaina Nov 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved in 9408534. reportProgramStatus now passes the built sequence through wrapForMultiplexer before writeTerminalControlSync: tmux gets ESC P tmux; ... ESC \ with the inner ESCs doubled, screen gets a plain DCS passthrough, and outside a multiplexer the sequence is unchanged. buildProgramStatusSequence stays pure. Added tests for the tmux and screen reports in program-status.test.ts and for the wrapper itself in terminal-io.test.ts.

@jond34

jond34 commented Nov 17, 2026

Copy link
Copy Markdown

Not Herdr-specific, and not a Herdr idea. The reason all of these projects started emitting in October is one shared problem: a program that alternates between working, waiting on you, and done, running in a tab or pane you aren't looking at. The options before this were scraping the window title, where a single agent cost Herdr ten rule changes in three months, or a per-app socket that doesn't cross SSH or a container. The pty crosses all of it: https://mitchellh.com/writing/program-status-osc7501

Senders converged on it:

Readers: iTerm2 3.7.5 on 2026-10-14 (https://iterm2.com/downloads/stable/iTerm2-3_7_5.changelog), libghostty on 2026-10-06 (ghostty-org/ghostty#14560), kitty 0.50.0 on 2026-11-03 (kovidgoyal/kitty#10638), Zellij 0.46.0 on 2026-11-11, which is a multiplexer consuming the sequence rather than passing it through (https://zellij.dev/news/terminal-inbox-session-previews/). Spec with revision history: https://www.superlogical.com/rex/docs/build/program-status

On the reservation question: nothing allocates OSC numbers, they get claimed by convention and unknown ones are meant to be ignored, which is how OSC 8, 133, 21337 and 7501 coexist. xterm's ctlseqs doesn't list 7501, and doesn't list 133 or the OSC 8 hyperlink either (https://invisible-island.net/xterm/ctlseqs/ctlseqs.html). The senders gate on the OSC 7501;? query and the spec requires ST termination, so a terminal without support sees nothing it isn't already ignoring.

Gap in this PR: writes to /dev/tty are dropped inside tmux. That's where a large share of agent sessions actually run, so the reports go missing exactly where someone is juggling panes and most needs them. Wrapping the sequence in a DCS passthrough gets it out, with a catch worth knowing: tmux only forwards \ePtmux;... when allow-passthrough is set, and on forwards only while the pane is visible, so a hidden agent pane needs all (https://man.openbsd.org/tmux#allow-passthrough). With the option off the bytes are discarded, so it degrades to today's behaviour instead of printing garbage. terminal-title.ts already has that wrapper in this codebase; the two review suggestions above apply it here.

@jond34

jond34 commented Nov 17, 2026

Copy link
Copy Markdown

One cost note, since it changes the size of this. Freebuff's CLI already pins @opentui/core 0.3.4 (cli/package.json), and OpenTUI added renderer.setProgramStatus(status) in v0.6.3 on 2026-10-13, which writes this exact report: https://github.com/anomalyco/opentui/releases/tag/v0.6.3

Latest is 0.9.2. So there are two shapes for this patch: the /dev/tty writer in this PR, or a dependency bump plus one call with OpenTUI owning the bytes. The bump is the real cost and I haven't measured it, so this is an option rather than a recommendation.

@demonodojo

Copy link
Copy Markdown
Author

What

Reports the CLI's lifecycle over OSC 7501, writing straight to /dev/tty (same approach as terminal-title.ts, since OpenTUI captures stdout), and clears the status from renderer-cleanup.ts on exit so it does not get stuck.

Sequence: ESC ] 7501 ; state=<state>:app=<program>[:kind=<kind>] ESC \ with state one of idle, working, blocked, done, clear.

Blocked kind

blocked only ever carries kind=question: ask_user is the CLI's only blocking prompt. permission was removed from BlockedKind instead of threading a kind through, because the CLI has no permission prompt to report — advertising it would have the terminal announce a state the UI never shows. It can come back when such a prompt exists.

Multiplexers

Bare escape sequences written to /dev/tty are dropped inside tmux and screen, which is where many agent sessions run. reportProgramStatus now pushes the built sequence through the shared wrapForMultiplexer helper in terminal-io.ts (the same DCS passthrough terminal-title.ts uses; the helper was hoisted out of that module rather than duplicated):

  • tmux: ESC P tmux; <sequence with ESC doubled> ESC \
  • screen: ESC P <sequence> ESC \

With tmux's allow-passthrough off the wrapped bytes are discarded, so the report degrades to today's behaviour rather than printing garbage. tmux with allow-passthrough on only forwards while the pane is visible; a hidden agent pane needs all. buildProgramStatusSequence stays pure and tested; only the write is wrapped.

Terminal compatibility

OSC 7501 is not a registered/reserved sequence; it is claimed by convention (the same way OSC 8, 133 and 21337 coexist). Terminal parsers consume an OSC string up to its terminator and discard the codes they do not implement, so xterm/VTE, iTerm2, WezTerm, kitty, Alacritty and Windows Terminal print nothing for this report. The write is best-effort and silent, so a non-interactive process without /dev/tty is unaffected.

Tested here: unit tests cover the emitted bytes, the tmux/screen passthrough wrappers, and the idle → working → blocked → done state machine. No manual test in Herdr or in a graphical emulator was run.

Tests

bun test cli/src/utils/__tests__/program-status.test.ts cli/src/utils/__tests__/terminal-io.test.ts  →  26 pass

@josemi-entaina

Copy link
Copy Markdown

Review follow-up — what is now resolved in 9408534:

  • Blocked kind: BlockedKind is narrowed to 'question'; permission was removed instead of reporting a kind the CLI cannot actually raise (da76c14).
  • Multiplexers: reportProgramStatus wraps the OSC 7501 sequence with the shared wrapForMultiplexer helper in terminal-io.ts (hoisted out of terminal-title.ts), so reports survive tmux/screen DCS passthrough instead of being dropped on /dev/tty. With allow-passthrough off the bytes are discarded, so behaviour degrades to today's.
  • Terminal compatibility: unknown OSCs are consumed and discarded by xterm/VTE, iTerm2, WezTerm, kitty, Alacritty and Windows Terminal; the write is best-effort and silent when there is no /dev/tty. No manual test in Herdr or a graphical emulator was run.
  • Tests: bun test cli/src/utils/__tests__/program-status.test.ts cli/src/utils/__tests__/terminal-io.test.ts → 26 pass, 0 fail.

Both inline review threads have replies pointing at the same commit.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot:triaged Classified by the community triage bot pr:needs-work Right idea, not mergeable as written

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants