repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: design os notifier redesign

4fa8d5bf3981ce82fd72ec35c9b5c3e3e8956c2d

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/specs/2026-07-12-os-notifier-design.md

Added
new file mode 100644
1 +# OS Notifier Redesign
3 +## Goal
5 +Replace `terminal-notifier` with a simpler `os-notifier` extension.
7 +The extension sends rich completion notifications for direct interactive Pi work.
8 +It uses native OS notification bridges first and terminal OSC notifications only as fallback.
9 +It does not notify for RPC, JSON, print, SDK-driven, extension-driven, or queued subagent-style work.
11 +## Scope
13 +Rename:
15 +- `extensions/terminal-notifier` to `extensions/os-notifier`
16 +- `@bugabinga/pi-ext-terminal-notifier` to `@bugabinga/pi-ext-os-notifier`
17 +- repository documentation and lockfile references
19 +Remove the unused `notify:send` listener and `notify:ui` emitter.
20 +No extension in this repository consumes either event.
22 +Keep terminal focus detection and rich notification metadata.
23 +Do not add settings, commands, tools, npm dependencies, daemons, or persistent state.
25 +## Eligibility
27 +A completion notification is eligible only when all conditions hold:
29 +- Pi runs in TUI mode: `ctx.mode === "tui"`.
30 +- The completed agent run belongs to direct input with `event.source === "interactive"`.
31 +- The terminal is unfocused when `agent_end` fires.
33 +The extension records input origin in extension-instance memory because `agent_end` does not expose it.
34 +It tracks the active run separately from queued follow-up origins so later input cannot reclassify an active run.
35 +Pi dispatches extension events serially, so this is event-order bookkeeping rather than cross-thread synchronization.
36 +State is cleared on completion and session shutdown.
37 +Nothing is written to disk or session history.
39 +Interactive steering makes the active run eligible.
40 +Interactive queued follow-up input makes its later run eligible.
41 +RPC, SDK, extension, JSON, and print activity never makes a run eligible.
43 +Every eligible unfocused completion notifies, regardless of duration.
44 +Focused completions are discarded rather than deferred.
46 +## Outcomes and Urgency
48 +The last assistant message determines the outcome:
50 +- normal stop: finished, `info`
51 +- aborted stop: stopped, `warning`
52 +- error stop: failed, `error`
54 +Urgency maps naturally where supported:
56 +- `info` to low
57 +- `warning` to normal
58 +- `error` to critical
60 +Linux exposes this mapping through `notify-send` urgency.
61 +The chosen macOS and Windows bridges do not expose equivalent urgency, so their titles communicate outcome without synthetic urgency or emoji.
62 +OSC fallback prefixes warning and error bodies because OSC has no portable urgency field.
64 +## Notification Content
66 +Preserve all useful existing context:
68 +- outcome
69 +- elapsed duration
70 +- project directory basename
71 +- Git branch
72 +- Pi session name
73 +- model name, or provider and model ID
74 +- bounded last user prompt snippet
75 +- bounded error detail for failures
77 +Control characters are removed from all dynamic text.
78 +Arguments are passed without shell interpolation.
79 +Prompt and error text remain bounded so OS notification bodies cannot grow without limit.
81 +## Native Delivery
83 +Each notification attempts one platform-native bridge:
85 +- Linux: `notify-send`
86 +- macOS: `osascript` notification command
87 +- Windows: PowerShell WinRT toast
89 +The implementation spawns the bridge directly for the notification.
90 +It does not run a startup availability probe because that costs another process and proves only presence, not successful delivery.
91 +A successful native command ends delivery.
92 +A spawn error or nonzero exit emits exactly one terminal fallback:
94 +- Kitty environments: OSC 99
95 +- other terminals: OSC 777
97 +There are no startup warning notifications.
98 +The implementation uses Node standard library APIs and OS-provided commands only.
99 +Linux systems without `notify-send` fall back to OSC without requiring installation.
101 +Per-notification process startup is accepted because notifications are infrequent.
102 +A persistent helper would reduce launch latency but add lifecycle and failure-state complexity.
103 +Native Node addons would add runtime dependencies and packaging burden.
105 +## Structure
107 +`index.ts` owns:
109 +- input eligibility bookkeeping
110 +- outcome and metadata formatting
111 +- platform command construction
112 +- native execution and OSC fallback
113 +- Pi lifecycle hooks
115 +`focus.ts` remains the small, reference-counted DECSET `?1004` focus helper.
116 +No backend interface, factory, configuration layer, or compatibility event bridge is introduced.
118 +## Failure Handling
120 +Native delivery is best-effort and never blocks or fails the Pi turn.
121 +Spawn errors and nonzero exits fall back once to OSC.
122 +OSC write failures are ignored because no further backend remains.
123 +Focus setup and teardown remain best-effort and session-scoped.
125 +## Tests
127 +Tests cover:
129 +- outcome, urgency, sanitization, bounds, and rich metadata formatting
130 +- Linux, macOS, and Windows command arguments without shell interpolation
131 +- native backend choice and Kitty/generic OSC fallback choice
132 +- direct interactive TUI eligibility
133 +- suppression for RPC, JSON, print, SDK-style, and extension input
134 +- active-run versus queued-follow-up origin bookkeeping
135 +- focused-terminal suppression
136 +- native success and native failure through a controlled fake executable on the current platform
137 +- loading through the real Pi extension harness
139 +Tests use the existing Vitest and Pi harness setup.
140 +No new test dependency is added.
142 +## Acceptance Criteria
144 +- The extension and package are named `os-notifier` everywhere.
145 +- Direct interactive TUI completions notify only while the terminal is unfocused.
146 +- Non-interactive and subagent-style runs do not notify.
147 +- Linux, macOS, and Windows attempt their native bridge first.
148 +- Native command failure produces one OSC fallback.
149 +- Success, abort, and failure use info, warning, and error semantics respectively.
150 +- Rich metadata is retained and bounded.
151 +- The dead extension event bridge is gone.
152 +- `mise run ci` passes.