repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

fix(os-notifier): bind eligibility to starting input

fd71f4ea9af5fbe90928ac85c0506de5ad43512f

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

docs/super/plans/2026-07-12-os-notifier.md

Modified
133 133 - encode Windows PowerShell script as UTF-16LE Base64 for `-EncodedCommand`
134 134 - pass macOS title/body through `osascript` argv to avoid shell interpolation
135 135 - add `oscBackend(env)`
136 -- add minimal candidate/prepared/active eligibility bookkeeping driven by `input`, `before_agent_start`, user `message_start`, `agent_start`, and `agent_settled`; handled input cannot leak, while accepted steering, retries, and follow-ups stay within the active lifecycle
136 +- add minimal candidate/prepared/active eligibility bookkeeping driven by `input`, `before_agent_start`, `agent_start`, and `agent_settled`; handled input cannot leak, pre-prompt compaction ordering remains correct, and active steering cannot reclassify extension-driven work
137 137 - remove `notify:send`, `notify:ui`, startup probes, backend caching, and warning notifications
139 139 - [ ] **Step 6: Run extension tests**
181 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.
183 +Use `execFile(command, args, callback)` without a shell and with a five-second timeout.
184 +On `error`, timeout, or nonzero command completion, write exactly one selected OSC fallback.
185 185 Trigger delivery from `agent_settled`, using the latest `agent_end` outcome.
186 186 Ignore OSC write errors.
187 187 Do not block or throw into Pi lifecycle handlers.

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

Modified
34 34 The extension records input origin in extension-instance memory because `agent_end` does not expose it.
35 35 It records idle `input` as a candidate, then confirms it at `before_agent_start` only when Pi accepts the prompt.
36 36 This prevents handled input from leaking eligibility into extension-triggered runs that start without an `input` event.
37 -Pi drains steering and queued follow-ups inside the active agent lifecycle.
38 -Interactive input received while active becomes a candidate, then a user `message_start` confirms Pi accepted it before making the lifecycle eligible.
39 -Handled active input therefore cannot create a notification or leak into the next run.
37 +The accepted input that starts the lifecycle determines eligibility.
38 +Later steering and queued follow-ups do not reclassify extension-driven work.
39 +If pre-prompt compaction starts the lifecycle before `before_agent_start`, that hook still promotes its accepted input into the active lifecycle.
40 40 Pi dispatches extension events serially, so this is event-order bookkeeping rather than cross-thread synchronization.
41 41 State is cleared on completion and session shutdown.
42 42 Nothing is written to disk or session history.
44 -Interactive steering and queued follow-up input make the active agent lifecycle eligible.
45 44 RPC, SDK, extension, JSON, and print activity never makes a run eligible.
47 46 Low-level `agent_end` events update the latest outcome without notifying.
124 123 ## Failure Handling
126 125 Native delivery is best-effort and never blocks or fails the Pi turn.
127 -Spawn errors and nonzero exits fall back once to OSC.
126 +Spawn errors, nonzero exits, and a five-second native-command timeout fall back once to OSC.
128 127 OSC write failures are ignored because no further backend remains.
129 128 Focus setup and teardown remain best-effort and session-scoped.
137 136 - native backend choice and Kitty/generic OSC fallback choice
138 137 - direct interactive TUI eligibility
139 138 - suppression for RPC, JSON, print, SDK-style, and extension input
140 -- candidate, accepted, and active-lifecycle input-origin bookkeeping
139 +- candidate, accepted, and active-lifecycle input-origin bookkeeping, including pre-prompt compaction ordering
141 140 - focused-terminal suppression and no notification before `agent_settled`
142 141 - native success and native failure through a controlled fake executable on the current platform
143 142 - loading through the real Pi extension harness

extensions/os-notifier/README.md

Modified
21 21 - `session_start` attaches terminal focus tracking in TUI mode.
22 22 - `input` records candidate direct interactive input origin.
23 -- `before_agent_start` confirms accepted idle prompt input.
24 -- `message_start` confirms accepted interactive steering and follow-ups.
23 +- `before_agent_start` confirms the accepted input that starts a lifecycle.
25 24 - `agent_start` starts duration measurement for the active lifecycle.
26 25 - `agent_end` records the latest low-level outcome.
27 26 - `agent_settled` sends the final eligible notification while unfocused.
36 35 - terminal unfocused at `agent_settled`
38 37 RPC, JSON, print, SDK-driven, extension-driven, and subagent-style turns stay silent.
39 -Interactive steering and queued follow-ups make their active agent lifecycle eligible.
38 +The accepted input that starts the lifecycle determines eligibility.
39 +Later steering and follow-ups do not reclassify extension-driven work.
40 40 Focused completions are discarded rather than deferred.
42 42 ## Native delivery
47 47 - macOS: `osascript`
48 48 - Windows: PowerShell WinRT toast
50 -A spawn error or nonzero exit emits one terminal fallback.
50 +A spawn error, nonzero exit, or five-second timeout emits one terminal fallback.
51 51 Kitty receives OSC 99; other terminals receive OSC 777.
52 52 No startup probe or warning notification is emitted.

extensions/os-notifier/__tests__/harness.test.ts

Modified
86 86 expect(writes).toHaveLength(1);
87 87 expect(writes[0]).toContain("\u001b]777;notify;Title;❌ Body\u0007");
90 + it("kills a hung native command and falls back", async () => {
91 + const writes: string[] = [];
92 + await deliverNative(
93 + {
94 + command: process.execPath,
95 + args: ["-e", "setInterval(() => {}, 1000)"],
96 + },
97 + "Title",
98 + "Body",
99 + "warning",
100 + "osc777",
101 + (value) => writes.push(value),
102 + 20,
103 + );
104 + expect(writes).toHaveLength(1);
105 + });
91 108 describe("os-notifier turn eligibility", () => {
108 125 expect(state.settle()).toBe(false);
111 - it("attributes queued follow-up input to the active lifecycle without leaking", () => {
112 - const state = new TurnEligibility();
113 - state.input("extension");
114 - state.prepare();
115 - state.start("tui");
116 - state.input("interactive", "followUp");
117 - state.confirmUserMessage();
118 - expect(state.settle()).toBe(true);
128 + it("keeps eligibility bound to the accepted input that started the lifecycle", () => {
129 + const extensionRun = new TurnEligibility();
130 + extensionRun.input("extension");
131 + extensionRun.prepare();
132 + extensionRun.start("tui");
133 + extensionRun.input("interactive", "followUp");
134 + expect(extensionRun.settle()).toBe(false);
120 - state.input("extension");
121 - state.prepare();
122 - state.start("tui");
123 - expect(state.settle()).toBe(false);
124 - });
126 - it("interactive steering makes the active run eligible", () => {
127 - const state = new TurnEligibility();
128 - state.input("extension");
129 - state.prepare();
130 - state.start("tui");
131 - state.input("interactive", "steer");
132 - state.confirmUserMessage();
133 - expect(state.settle()).toBe(true);
134 - });
136 - it("does not accept handled interactive input during an active run", () => {
137 - const state = new TurnEligibility();
138 - state.input("extension");
139 - state.prepare();
140 - state.start("tui");
141 - state.input("interactive", "steer");
142 - expect(state.settle()).toBe(false);
136 + const interactiveRun = new TurnEligibility();
137 + interactiveRun.input("interactive");
138 + interactiveRun.prepare();
139 + interactiveRun.start("tui");
140 + interactiveRun.input("extension", "followUp");
141 + expect(interactiveRun.settle()).toBe(true);
145 144 it("preserves eligibility across low-level retries until settlement", () => {
151 150 expect(state.settle()).toBe(true);
153 + it("accepts input prepared after a pre-prompt compaction run starts", () => {
154 + const state = new TurnEligibility();
155 + state.input("interactive");
156 + state.start("tui");
157 + state.prepare();
158 + expect(state.settle()).toBe(true);
159 + });
154 161 it("does not consume handled interactive input for an extension-triggered run", () => {
155 162 const state = new TurnEligibility();
156 163 state.input("interactive");

extensions/os-notifier/index.ts

Modified
287 287 severity: NotificationSeverity,
288 288 fallback: OscBackend,
289 289 write: (value: string) => unknown = (value) => process.stdout.write(value),
290 + timeoutMs = 5000,
290 291 ): Promise<void> {
291 292 return new Promise((resolveDelivery) => {
292 293 const useFallback = () => {
302 303 return;
305 - execFile(command.command, command.args, { env: command.env }, (error) => {
306 - if (error) useFallback();
307 - else resolveDelivery();
308 - });
306 + execFile(
307 + command.command,
308 + command.args,
309 + { env: command.env, timeout: timeoutMs },
310 + (error) => {
311 + if (error) useFallback();
312 + else resolveDelivery();
313 + },
314 + );
309 315 } catch {
310 316 useFallback();
318 324 export class TurnEligibility {
319 325 private active = false;
320 326 private activeTui = false;
321 - private activeCandidate = false;
322 327 private current = false;
323 328 private pending = false;
324 329 private prepared = false;
326 331 input(source: InputSource, _behavior?: StreamingBehavior): void {
327 - const eligible = source === "interactive";
328 - if (this.active) {
329 - this.activeCandidate = eligible;
330 - return;
331 - }
332 - this.pending = eligible;
332 + if (this.active) return;
333 + this.pending = source === "interactive";
335 336 prepare(): void {
337 + if (this.active) {
338 + this.current ||= this.activeTui && this.pending;
339 + this.pending = false;
340 + return;
336 342 this.prepared = this.pending;
337 343 this.pending = false;
340 - confirmUserMessage(): void {
341 - this.current ||= this.activeTui && this.activeCandidate;
342 - this.activeCandidate = false;
343 - }
345 346 start(mode: string): void {
346 347 if (this.active) return;
347 348 this.active = true;
363 364 private reset(): void {
364 365 this.active = false;
365 366 this.activeTui = false;
366 - this.activeCandidate = false;
367 367 this.current = false;
368 368 this.pending = false;
369 369 this.prepared = false;
391 391 eligibility.prepare();
394 - pi.on("message_start", async (event) => {
395 - if (event.message.role === "user") eligibility.confirmUserMessage();
396 - });
398 394 pi.on("agent_start", async (_event, ctx) => {
399 395 eligibility.start(ctx.mode);
400 396 agentStartedAt ??= Date.now();