1 +#
OS Notifier Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Replace `terminal-notifier` with a cross-platform, native-first `os-notifier` that only notifies for direct interactive TUI runs.
7 +**Architecture:** Keep the existing reference-counted focus helper. Rebuild `index.ts` around pure formatting/command helpers, minimal in-memory input-origin bookkeeping, and one native spawn whose failure callback emits OSC fallback.
9 +**Tech Stack:** TypeScript, Node.js standard library, Pi extension API, Vitest, Pi test harness
13 +**Phase:** Single-plan implementation
17 +##
Task 1: Rename the Extension 21 +- Rename: `extensions/terminal-notifier` to `extensions/os-notifier`
22 +- Modify: `extensions/os-notifier/package.json`
23 +- Modify: `README.md`
24 +- Modify: `package-lock.json`
26 +- [ ] **Step 1: Rename the directory and package metadata**
31 +mv extensions/terminal-notifier extensions/os-notifier
34 +Change the package name to `@bugabinga/pi-ext-os-notifier`, description to `Native-first OS notifications for Pi.`, and root README table entry/link to `os-notifier`.
36 +- [ ] **Step 2: Regenerate workspace lockfile references**
41 +npm install --package-lock-only --ignore-scripts
44 +Expected: `package-lock.json` contains `extensions/os-notifier` and no `terminal-notifier` references.
46 +- [ ] **Step 3: Verify rename completeness**
51 +rg
'terminal-notifier' README.md package-lock.json extensions/os-notifier
54 +Expected: only historical changelog entries remain; package, source, tests, and README use `os-notifier`.
56 +- [ ] **Step 4: Commit the rename**
59 +git add README.md package-lock.json extensions/terminal-notifier extensions/os-notifier
60 +git commit -m
"refactor: rename terminal notifier to os notifier" 63 +##
Task 2: Specify Native Delivery and Eligibility 67 +- Modify: `extensions/os-notifier/__tests__/harness.test.ts`
68 +- Modify: `extensions/os-notifier/index.ts`
70 +- [ ] **Step 1: Replace old backend tests with failing native command tests**
72 +Add table tests asserting:
75 +expect(
nativeCommand(
"linux",
"Title",
"Body",
"info")).
toEqual({
76 + command:
"notify-send",
77 + args: [
"--app-name=Pi",
"--urgency=low",
"Title",
"Body"],
79 +expect(
nativeCommand(
"darwin",
"Title",
"Body",
"warning").command).
toBe(
82 +expect(
nativeCommand(
"win32",
"Title",
"Body",
"error").command).
toBe(
85 +expect(
oscBackend({ KITTY_WINDOW_ID:
"1" })).
toBe(
"osc99");
86 +expect(
oscBackend({})).
toBe(
"osc777");
89 +Assert command arguments carry quoted/control-character input as data rather than interpolating it into a shell command.
91 +- [ ] **Step 2: Add failing eligibility state tests**
93 +Export a small `TurnEligibility` class and test:
96 +const state
= new TurnEligibility();
97 +state.
input(
"interactive",
undefined);
99 +expect(state.
end()).
toBe(
true);
101 +state.
input(
"rpc",
undefined);
103 +expect(state.
end()).
toBe(
false);
105 +state.
input(
"interactive",
"followUp");
107 +expect(state.
end()).
toBe(
false);
110 +Add a queued-follow-up test proving input arriving during an active run applies to the next `agent_start`, not the active run.
112 +- [ ] **Step 3: Add failing metadata tests**
114 +Retain existing rich-content assertions and add bounded error-detail and control-character sanitization assertions.
115 +Verify normal, aborted, and error outcomes map to info, warning, and error.
117 +- [ ] **Step 4: Run extension tests and confirm failure**
122 +mise run test
-- os-notifier
125 +Expected: FAIL because native command and eligibility exports do not exist yet.
127 +- [ ] **Step 5: Implement pure formatting, command, and eligibility helpers**
131 +- retain bounded metadata formatting and direct `.git/HEAD` branch lookup
132 +- add `nativeCommand(platform, title, body, severity)` returning executable plus argument array
133 +- encode Windows PowerShell script as UTF-16LE Base64 for `-EncodedCommand`
134 +- pass macOS title/body through `osascript` argv to avoid shell interpolation
135 +- add `oscBackend(env)`
136 +- add minimal active/pending eligibility bookkeeping driven by `input`, `agent_start`, and `agent_end`
137 +- remove `notify:send`, `notify:ui`, startup probes, backend caching, and warning notifications
139 +- [ ] **Step 6: Run extension tests**
144 +mise run test
-- os-notifier
149 +- [ ] **Step 7: Commit behavior**
152 +git add extensions/os-notifier/index.ts extensions/os-notifier/__tests__/harness.test.ts
153 +git commit -m
"feat(os-notifier): add native-first notifications" 156 +##
Task 3: Verify Native Failure Fallback and Integration 160 +- Modify: `extensions/os-notifier/__tests__/harness.test.ts`
161 +- Modify: `extensions/os-notifier/README.md`
162 +- Modify: `extensions/os-notifier/CHANGELOG.md`
164 +- [ ] **Step 1: Add a failing delivery-path test**
166 +Create a controlled executable in a test temporary directory, prepend it to `PATH`, and exercise the exported delivery function.
167 +Assert exit zero writes no OSC.
168 +Replace it with a nonzero executable and assert exactly one OSC sequence is written.
169 +Use Node file APIs and a platform-appropriate executable fixture; do not invoke shell discovery helpers.
171 +- [ ] **Step 2: Run the focused test and confirm failure**
176 +mise run test
-- os-notifier
179 +Expected: FAIL until delivery exposes completion/failure behavior suitable for deterministic testing.
181 +- [ ] **Step 3: Implement one-shot native delivery with OSC fallback**
183 +Use `execFile(command, args, callback)` without a shell.
184 +On `error` or nonzero command completion, write exactly one selected OSC fallback.
185 +Ignore OSC write errors.
186 +Do not block or throw into Pi lifecycle handlers.
188 +- [ ] **Step 4: Update documentation**
192 +- TUI plus interactive-input eligibility
193 +- unfocused-only behavior
194 +- Linux/macOS/Windows native commands
195 +- OSC 99/777 failure fallback
196 +- metadata and urgency mapping
197 +- absence of settings, commands, tools, and extension event bridge
199 +Add an unreleased changelog entry for the rename and redesign.
201 +- [ ] **Step 5: Run focused and repository checks**
206 +mise run test
-- os-notifier
212 +Expected: every command exits zero.
214 +- [ ] **Step 6: Verify repository invariants**
219 +test -d extensions/os-notifier
220 +test ! -e extensions/terminal-notifier
221 +rg
'terminal-notifier' README.md package-lock.json extensions/os-notifier
224 +Expected: the directory assertions pass; only historical changelog references may match.
226 +- [ ] **Step 7: Commit final integration**
229 +git add extensions/os-notifier/README.md extensions/os-notifier/CHANGELOG.md extensions/os-notifier/__tests__/harness.test.ts extensions/os-notifier/index.ts
230 +git commit -m
"test(os-notifier): verify fallback delivery"