diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..4849d0d --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# panto-report-status + +Reports panto's lifecycle through **OSC 7501**, the terminal-native +[Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status). +For the native Herdr app / herdr-core, Rex, Orca, and other supporting terminals. +No Herdr commands, sockets, hooks, or terminal-specific environment variables. + +For the **classic Herdr TUI**, use +[panto-herdr](https://code.tjp.lol/public/panto-herdr) instead. Choose one reporter +for your host; this extension does not publish Herdr-specific session metadata. + +## Install + +Use this checkout in your panto configuration: + +```toml +[extensions] +paths = ["/absolute/path/to/panto-report-status"] +``` + +Once the rock is published, `rocks = ["panto-report-status"]` is the alternative; +run `panto update` and start a new session. The extension's policy name is +`report-status`. + +## Reporting + +Uses the same lifecycle events as panto-herdr, with OSC's explicit completion +states rather than relying on Herdr to infer completion from `idle`. + +| panto event | OSC state | +| --- | --- | +| `session_ready` | `idle` | +| `turn_start`, `agent_submission`, `render_thinking` | `working`, message `thinking` | +| `render_tool_details`, `render_assistant_text` | `working`, message `tool:<name>` or `responding` | +| `command_start` | `working`, message `compacting`, `shell`, or `cmd:<name>` | +| `render_compaction` | refines already-active foreground work; never starts work | +| `turn_end` | `done`, `error` for `reason=failed`, or `idle` for interruption/exit request | +| `command_end` | `done`; this event does not carry a success/failure result | +| `background_work_start` / `background_work_end` | remains `working` until foreground work and all background work end | +| `session_end` | `clear`; later work callbacks cannot revive the report | + +Foreground completion is retained while background work finishes. Reports use +the root record with `app=panto`; messages are short, control-free ASCII labels, +base64-encoded on the wire. Duplicate reports are suppressed. A `done` or `error` +report is not immediately replaced with `idle`; the host decides how to present +unseen results, notifications, and sounds. Normal session exit clears the report. + +Writes synchronously to stdout only while it is the same terminal detected at +activation. Pipes and files receive no escape sequences. Only the outermost +panto in a terminal reports: `PANTO_REPORT_STATUS_OWNER` identifies the terminal +and owning PID, surviving `/new` while silencing nested panto processes in that +terminal. A panto in a different terminal can report normally. + +No capability query is needed: the protocol permits reports without a handshake. +Unsupported terminals ignore the sequences. An intervening multiplexer can +consume or discard them; run directly in the supporting host's pane. + +**Limitations:** no generic panto approval/question lifecycle event is available, +so this extension cannot reliably report `blocked`. It does not guess from text. +Background-work events have no individual task identity or outcome, so they use +one counter rather than child records or percentages. OSC does not publish a +transcript path or conversation-resume command. Write errors go through panto's +normal event-error handling; there is no protocol-level acknowledgement. + +## Compatibility + +- [Native Herdr / herdr-core](https://herdr.dev/core/) consumes OSC 7501 status. +- [Rex](https://www.superlogical.com/rex/docs/build/program-status#in-rex) uses it + for session/tab indicators and Lua events. +- [Orca v1.4.245](https://github.com/stablyai/orca/blob/v1.4.245/src/main/agent-hooks/README.md) + supports OSC 7501 for programs without managed integrations. Hooks take + precedence when present; OSC supplies status, not full native-chat/resume data. + +These are documented host capabilities, not a claim of live panto testing in +all three applications. + +## Check + +```sh +panto lua _selfcheck.lua +# Or: lua _selfcheck.lua +``` + +The check stubs panto and luv; it never emits to a live terminal. |