repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/os-notifier/README.md

Raw

Rendered preview

os-notifier

Native-first OS notifications when direct interactive Pi work completes or blocks awaiting input.

Install / load

Loaded through the root pi-ext package. Requires Pi 0.80.6 or newer for agent_settled. See root README.

Commands / tools / settings

Commands: none.

Tools: none.

Settings: none.

Hooks:

session_start attaches terminal focus tracking and publishes pane identity in TUI mode.
input records candidate direct interactive input origin.
before_agent_start confirms the accepted input that starts a lifecycle.
agent_start starts duration measurement for the active lifecycle.
agent_end records the latest low-level outcome.
ui_prompt_start notifies once when eligible work blocks on an extension UI prompt while unfocused.
ui_prompt_end rearms blocked-input notification delivery.
agent_settled sends the final eligible notification while unfocused.
session_shutdown clears in-memory state, pane identity, and focus tracking.

Eligibility

Notifications require all of:

ctx.mode === "tui"
input source interactive
terminal unfocused when the blocking prompt starts or at agent_settled

RPC, JSON, print, SDK-driven, extension-driven, and subagent-style turns stay silent. The accepted input that starts the lifecycle determines eligibility. Later steering and follow-ups do not reclassify extension-driven work. Focused completions and prompt waits are discarded rather than deferred. Only Pi extension UI prompts are detected; arbitrary subprocesses waiting on stdin are outside this extension's scope.

Native delivery

The extension attempts one OS bridge:

Linux: notify-send
macOS: osascript
Windows: PowerShell WinRT toast

A spawn error, nonzero exit, or five-second timeout emits one terminal fallback. Kitty receives OSC 99; other terminals receive OSC 777. No startup probe or warning notification is emitted.

Linux urgency maps info to low, warning to normal, and error to critical. macOS and Windows communicate outcome through the title because these bridges expose no equivalent urgency. OSC fallback prefixes warnings and errors.

Content

Completion notifications include outcome, duration, project, Git branch, session name, model, bounded user prompt, and bounded failure detail. Blocked-input notifications include prompt kind, title, project, Git branch, and session name. The accepted starting prompt remains available when a retry's final event omits user messages. Dynamic text is sanitized and passed without shell interpolation.

Focus tracking uses DECSET ?1004, shared through globalThis and reference-counted. TUI sessions publish agent identity, session name, and project as OSC 1337 pane user variables and clear them on shutdown.

Debugging

Opt-in metadata-only tracing follows debug contract. Safe events: session.start, session.shutdown, notification.deliver.start, notification.deliver.finish, notification.deliver.error.

# os-notifier

Native-first OS notifications when direct interactive Pi work completes or blocks awaiting input.

## Install / load

Loaded through the root pi-ext package.
Requires Pi 0.80.6 or newer for `agent_settled`.
See [root README](../../README.md).

## Commands / tools / settings

Commands: none.

Tools: none.

Settings: none.

Hooks:

- `session_start` attaches terminal focus tracking and publishes pane identity in TUI mode.
- `input` records candidate direct interactive input origin.
- `before_agent_start` confirms the accepted input that starts a lifecycle.
- `agent_start` starts duration measurement for the active lifecycle.
- `agent_end` records the latest low-level outcome.
- `ui_prompt_start` notifies once when eligible work blocks on an extension UI prompt while unfocused.
- `ui_prompt_end` rearms blocked-input notification delivery.
- `agent_settled` sends the final eligible notification while unfocused.
- `session_shutdown` clears in-memory state, pane identity, and focus tracking.

## Eligibility

Notifications require all of:

- `ctx.mode === "tui"`
- input source `interactive`
- terminal unfocused when the blocking prompt starts or at `agent_settled`

RPC, JSON, print, SDK-driven, extension-driven, and subagent-style turns stay silent.
The accepted input that starts the lifecycle determines eligibility.
Later steering and follow-ups do not reclassify extension-driven work.
Focused completions and prompt waits are discarded rather than deferred.
Only Pi extension UI prompts are detected; arbitrary subprocesses waiting on stdin are outside this extension's scope.

## Native delivery

The extension attempts one OS bridge:

- Linux: `notify-send`
- macOS: `osascript`
- Windows: PowerShell WinRT toast

A spawn error, nonzero exit, or five-second timeout emits one terminal fallback.
Kitty receives OSC 99; other terminals receive OSC 777.
No startup probe or warning notification is emitted.

Linux urgency maps `info` to low, `warning` to normal, and `error` to critical.
macOS and Windows communicate outcome through the title because these bridges expose no equivalent urgency.
OSC fallback prefixes warnings and errors.

## Content

Completion notifications include outcome, duration, project, Git branch, session name, model, bounded user prompt, and bounded failure detail.
Blocked-input notifications include prompt kind, title, project, Git branch, and session name.
The accepted starting prompt remains available when a retry's final event omits user messages.
Dynamic text is sanitized and passed without shell interpolation.

Focus tracking uses DECSET `?1004`, shared through `globalThis` and reference-counted.
TUI sessions publish agent identity, session name, and project as OSC 1337 pane user variables and clear them on shutdown.

## Debugging

Opt-in metadata-only tracing follows [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `notification.deliver.start`, `notification.deliver.finish`, `notification.deliver.error`.