@pi-archimedes/notify 2.10.4 → 2.11.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Step away without losing track.**
 
-Leave the terminal for a coffee. When the work has actually settled — or something needs your decision — notify tells you, once, after a short delay. Type anything and the pending alert is cancelled; there's no inactivity scrutiny, no focus tracking. Keystrokes are the only signal.
+Leave the terminal for a coffee. When the work has actually settled — or something needs your decision — notify tells you, once, after a short delay. Press a key and the pending alert is cancelled; there's no inactivity scrutiny, no focus tracking. Keystrokes are the only signal — a terminal answering Pi's own questions (colour palette, device attributes, cell size) is not one.
 
 ## Install
 
@@ -31,7 +31,7 @@ After installing Pi, choose one installation command above, then `cd` into your
 - **Settled runs** — on Pi's `agent_settled` event: the run has fully settled (no automatic retry, compaction, or queued continuation still to fire), not merely "a turn ended".
 - **Blocking prompts** — on `ui_prompt_start`: any extension prompt is waiting on you (a tabbed ask, a sudo password or command-confirm prompt) — direct **or** subagent-relayed, since the event fires in the parent process.
 
-The alert fires after a fixed `delayMs` (30 s by default) from the trigger. It is a delay, not an idle timer: nothing measures how long you've been reading. Any input in the terminal cancels pending alerts immediately, a new agent run cancels them, and a prompt that closes without you typing (say, a confirm dialog that times out and auto-declines) cancels its own timer — so a long-gone question can't ring.
+The alert fires after a fixed `delayMs` (30 s by default) from the trigger. It is a delay, not an idle timer: nothing measures how long you've been reading. A keystroke in the terminal cancels a pending alert immediately — and only a keystroke: pi-tui's decoder decides, so protocol traffic that reaches the listener (a device-attributes reply, a cell-size report, focus and mouse sequences) cannot silently swallow an alert nobody dismissed. Anything you actually typed counts, including the characters the decoder has no name for — an accented key or an IME commit on a terminal that doesn't speak the Kitty keyboard protocol. A new agent run cancels pending alerts, whichever kind of run start it was, and a prompt that closes without you typing (say, a confirm dialog that times out and auto-declines) cancels its own timer — so a long-gone question can't ring.
 
 ## Terminal delivery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/notify",
-  "version": "2.10.4",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -18,15 +18,15 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.10.4"
+    "@pi-archimedes/core": "2.11.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-tui": ">=0.84.4"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/cancel-pending.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── What this pins ──────────────────────────────────────────────────────────
+//
+// Two cancel paths, both of which pi 1.x changed underneath us:
+//
+// 1. `before_agent_start`. pi 1.2.0 made the event a union on `messageType`
+//    ("user" for a submitted prompt, "custom" for `pi.sendMessage(…,
+//    { triggerTurn: true })` fired while idle) and fires it for both. A run
+//    that is *starting* makes a pending "Task complete — waiting for input"
+//    stale either way, so the handler stays unconditional and this file pins
+//    both members of the union.
+//
+// 2. Terminal input. The cancel used to be "any byte that reaches the
+//    listener". pi now puts far more protocol traffic through the terminal —
+//    and `TuiBase.handleTerminalInput()` (pi-tui `dist/tui.js`) forwards some
+//    of it to extension listeners and swallows the rest:
+//      - OSC 10/11/4 colour replies and the colour-scheme report are consumed
+//        *before* listeners run, so a palette reply can never reach notify;
+//      - a primary-device-attributes reply (`ESC [ ? … c`) is consumed before
+//        listeners only while a colour query is pending, so a late or
+//        unsolicited one *is* forwarded;
+//      - a cell-size report (`ESC [ 6 ; h ; w t`) is consumed only *after*
+//        listeners, so it always reaches them.
+//    So a reply is not a keystroke: only input pi-tui decodes to a key
+//    (`parseKey`) cancels.
+
+vi.mock("@pi-archimedes/core/settings-io", () => ({
+  loadConfig: vi.fn(),
+  saveConfig: vi.fn(),
+}));
+
+import { loadConfig } from "@pi-archimedes/core/settings-io";
+import { DEFAULT_NOTIFY_CONFIG, registerNotify } from "./index.js";
+
+const DELAY_MS = 1_000;
+
+/** The OSC 777 fallback payload `notify()` writes for each trigger. */
+const TASK_COMPLETE_OSC = "\x1b]777;notify;Pi;Task complete — waiting for input\x07";
+const QUESTION_OSC = "\x1b]777;notify;Pi;A question needs your answer\x07";
+
+interface Harness {
+  /** Fire a pi event at the handlers `registerNotify` subscribed. */
+  emit(event: string, payload?: unknown): void;
+  /** Feed one chunk of raw terminal input to the registered listener. */
+  terminalInput(data: string): void;
+  /** Notification payloads written to stderr so far. */
+  written(): string[];
+  /** Let the pending notification's delay elapse (and then some). */
+  waitPastDelay(): void;
+}
+
+function setup(): Harness {
+  vi.mocked(loadConfig).mockReturnValue({ ...DEFAULT_NOTIFY_CONFIG, delayMs: DELAY_MS });
+  // Fall through to the OSC 777 dispatcher: no terminal-specific branch.
+  vi.stubEnv("WT_SESSION", "");
+  vi.stubEnv("KITTY_WINDOW_ID", "");
+  vi.stubEnv("TERM_PROGRAM", "");
+  vi.stubEnv("ITERM_SESSION_ID", "");
+  vi.stubEnv("TMUX", "");
+  const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+  const handlers: Record<string, Array<(payload: unknown, ctx: unknown) => void>> = {};
+  let terminalListener: ((data: string) => unknown) | undefined;
+
+  const pi = {
+    on: vi.fn((event: string, handler: (payload: unknown, ctx: unknown) => void) => {
+      (handlers[event] ??= []).push(handler);
+    }),
+  } as unknown as Parameters<typeof registerNotify>[0];
+
+  registerNotify(pi);
+
+  const ctx = {
+    hasUI: true,
+    ui: {
+      onTerminalInput: vi.fn((handler: (data: string) => unknown) => {
+        terminalListener = handler;
+        return () => {
+          terminalListener = undefined;
+        };
+      }),
+    },
+  };
+  for (const handler of handlers["session_start"] ?? []) handler(undefined, ctx);
+
+  return {
+    emit(event, payload) {
+      for (const handler of handlers[event] ?? []) handler(payload ?? { type: event }, ctx);
+    },
+    terminalInput(data) {
+      terminalListener?.(data);
+    },
+    written() {
+      return write.mock.calls.map((call) => String(call[0]));
+    },
+    waitPastDelay() {
+      vi.advanceTimersByTime(DELAY_MS * 2);
+    },
+  };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+});
+
+describe("notify cancel-on-input under pi 1.x terminal traffic", () => {
+  it("does not cancel on a forwarded primary-device-attributes reply", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    // The DA1 reply shape pi-tui forwards to extension listeners.
+    harness.terminalInput("\x1b[?62;1;9c");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toContain(TASK_COMPLETE_OSC);
+  });
+
+  it("does not cancel on a cell-size report", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    // ESC [ 6 ; height ; width t — consumed by pi-tui only after listeners.
+    harness.terminalInput("\x1b[6;24;80t");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toContain(TASK_COMPLETE_OSC);
+  });
+
+  it("does not cancel on a colour reply or a colour-scheme report", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.terminalInput("\x1b]10;rgb:ffff/ffff/ffff\x07");
+    harness.terminalInput("\x1b]11;rgb:0000/0000/0000\x1b\\");
+    harness.terminalInput("\x1b]4;1;rgb:ff00/0000/0000\x1b\\");
+    harness.terminalInput("\x1b[?u"); // the Kitty keyboard-protocol query reply
+    harness.waitPastDelay();
+
+    expect(harness.written()).toContain(TASK_COMPLETE_OSC);
+  });
+
+  it("does not cancel on focus, mouse or bracketed-paste traffic", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    // None of these is typing, and pi-tui passes all of them to listeners: focus
+    // in/out, an SGR mouse press, and the bracketed-paste marker.
+    harness.terminalInput("\x1b[I");
+    harness.terminalInput("\x1b[O");
+    harness.terminalInput("\x1b[<0;10;10M");
+    harness.terminalInput("\x1b[200~");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toContain(TASK_COMPLETE_OSC);
+  });
+
+  it("cancels on a plain keystroke", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.terminalInput("a");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  // What `parseKey()` names is not the whole set of keystrokes. pi-tui's
+  // `StdinBuffer` splits batched input into single sequences before listeners
+  // run, so a typed character reaches us on its own — but the decoder only
+  // resolves ASCII bytes and escape sequences. A character outside ASCII
+  // arrives as itself (`é` is the two bytes C3 A9 on any terminal that did not
+  // take the Kitty keyboard protocol, which is Terminal.app, VTE, xterm and
+  // tmux), `parseKey()` has no name for it, and the keystroke would be missed:
+  // the alert fires at someone sitting at the keyboard, typing an accented
+  // letter. Under Kitty the same key arrives as CSI-u and does decode, so this
+  // is exactly the legacy-terminal path.
+  it("cancels on a typed character pi-tui's decoder does not name", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.terminalInput("é"); // one key press, no Kitty protocol
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("cancels on a typed CJK character", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.terminalInput("中");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("does not cancel on the ASCII tail of a reply split across reads", () => {
+    const harness = setup();
+
+    // A reply whose ESC header pi-tui consumed can leave a bare tail (digits
+    // and semicolons) to be flushed as input. It is printable ASCII with no
+    // escape byte, so "is it text?" is the wrong question to ask — only a
+    // character that could only have come from a key press cancels.
+    harness.emit("agent_settled");
+    harness.terminalInput("62;1;9c");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toContain(TASK_COMPLETE_OSC);
+  });
+
+  it("cancels on a Kitty-protocol key press and on its release", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.terminalInput("\x1b[97:1u"); // CSI-u press for 'a'
+    harness.waitPastDelay();
+    expect(harness.written()).toEqual([]);
+
+    harness.emit("agent_settled");
+    harness.terminalInput("\x1b[97:3u"); // the matching release
+    harness.waitPastDelay();
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("fires when the terminal stays quiet", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([TASK_COMPLETE_OSC]);
+  });
+});
+
+describe("notify cancel-on-run-start (pi 1.2.0 before_agent_start union)", () => {
+  const base = {
+    type: "before_agent_start",
+    systemPrompt: "prompt",
+    systemPromptOptions: {},
+  };
+
+  it("cancels a pending notification for a user-prompt run", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.emit("before_agent_start", { ...base, messageType: "user", prompt: "hi" });
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("cancels a pending notification for an idle custom message with triggerTurn", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.emit("before_agent_start", {
+      ...base,
+      messageType: "custom",
+      message: { role: "custom", customType: "note", content: "hello", display: true },
+    });
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("cancels on agent_start as before", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.emit("agent_start");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+});
+
+describe("notify ui_prompt_end scoping (ADR 0013)", () => {
+  it("cancels a pending question notification when the prompt closes", () => {
+    const harness = setup();
+
+    harness.emit("ui_prompt_start");
+    harness.emit("ui_prompt_end");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([]);
+  });
+
+  it("leaves a pending task-complete notification alone", () => {
+    const harness = setup();
+
+    harness.emit("agent_settled");
+    harness.emit("ui_prompt_end");
+    harness.waitPastDelay();
+
+    expect(harness.written()).toEqual([TASK_COMPLETE_OSC]);
+    expect(harness.written()).not.toContain(QUESTION_OSC);
+  });
+});

package/src/index.ts

@@ -1,9 +1,21 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
+import { parseKey } from "@earendil-works/pi-tui";
 import { loadConfig, saveConfig } from "@pi-archimedes/core/settings-io";
 import { execFile } from "node:child_process";
 
 // ── Trigger constants ────────────────────────────────────────────────────────
+//
+// Relation to pi's own OSC 7501 program status (pi >= 1.1.0):
+// pi's ProgramStatusReporter already reports this session's state to the
+// terminal — `done` when a run settles and `blocked` when a dialog opens
+// (`pi-coding-agent/dist/modes/interactive/program-status-reporter.js`,
+// encoded by pi-tui's `formatProgramStatus`). The two triggers below map onto
+// it one-for-one: AGENT_SETTLED <-> `done`, UI_PROMPT <-> `blocked`. We emit
+// nothing 7501-related; what this package adds on top of that report is the
+// DELAYED desktop notification (OSC 777/9/99, Windows toast, tmux DCS wrap)
+// and the cancellation rules below — pi reports state changes immediately and
+// to the terminal only. Full comparison: docs/features/notify.md.
 
 const TRIGGER = {
   AGENT_SETTLED: "agent_settled",
@@ -39,6 +51,58 @@ export function saveNotifyConfig(config: NotifyConfig): void {
 
 // ── Terminal detection helpers ──────────────────────────────────────────────
 
+/**
+ * Did the user press a key, or is this the terminal answering a question?
+ *
+ * pi-tui decodes input for us, and the decode is the test: `parseKey()` returns
+ * a key id for a keystroke (legacy byte, escape sequence, Kitty CSI-u press,
+ * repeat **or** release) and `undefined` for everything else. Cancel on the
+ * keystrokes only.
+ *
+ * The rule used to be "any byte that reaches the listener", which pi 1.x makes
+ * wrong, because far more protocol traffic goes through the terminal now and
+ * `TuiBase.handleTerminalInput()` (pi-tui `dist/tui.js:687-712`) forwards some
+ * of it to extension listeners and swallows the rest:
+ *
+ * - The colour-scheme report is consumed before listeners, unconditionally. The
+ *   OSC 10/11/4 colour replies go through the same pending-query branch as the
+ *   device-attributes reply below, so during pi's palette query — at startup and
+ *   on every theme switch, when that branch is armed — they are swallowed there;
+ *   a reply that turns up with no query outstanding is forwarded like any other
+ *   byte.
+ * - A primary-device-attributes reply (`ESC [ ? … c`) is swallowed only while a
+ *   colour query is pending (`tui.js`, `pendingTerminalColorQueries`), so a
+ *   late or unsolicited one — the shape is `\x1b[?62;1;9c` — **is** forwarded.
+ * - A cell-size report (`ESC [ 6 ; height ; width t`) is consumed only *after*
+ *   listeners, so it always reaches them.
+ * - Focus in/out, mouse reporting, bracketed-paste markers and the Kitty
+ *   protocol query reply reach listeners too, and none of them is typing.
+ *
+ * So a reply used to be able to cancel an alert nobody asked for. A mouse event
+ * no longer counts either — notify's contract is keystrokes (see README), and
+ * `parseKey()` is what says whether one happened.
+ *
+ * The decoder is the test, but not the whole test: it names ASCII bytes and
+ * escape sequences, and nothing else. A character outside ASCII is delivered as
+ * itself — `é` is the two bytes C3 A9 on every terminal that did not take the
+ * Kitty keyboard protocol (Terminal.app, VTE/GNOME Terminal, xterm, tmux) — and
+ * `parseKey()` returns `undefined` for it. Treating that as "not a keystroke"
+ * would fire an alert at someone standing at the keyboard typing an accented
+ * letter, which is the failure this handler exists to prevent, so a printable
+ * character with no control byte in it counts as typing too. The test stays
+ * narrow on purpose: the `é`-shaped answer cannot mistake protocol traffic for
+ * a key press, because every reply pi-tui forwards opens with `ESC`, and the
+ * only other printable bytes a listener can see are the *tail* of a reply split
+ * across two reads (`62;1;9c`) — printable ASCII, still no key press.
+ */
+const TYPED_NON_ASCII = /[\u00a0-\uffff]/;
+const CONTROL_BYTE = /[\u0000-\u001f\u007f-\u009f]/;
+
+function isKeystroke(data: string): boolean {
+  if (parseKey(data) !== undefined) return true;
+  return TYPED_NON_ASCII.test(data) && !CONTROL_BYTE.test(data);
+}
+
 /** Wrap an OSC sequence for tmux passthrough. */
 export function wrapForTmux(sequence: string): string {
   if (!process.env.TMUX) {
@@ -189,6 +253,13 @@ export function registerNotify(pi: ExtensionAPI): void {
   // parent process for direct and subagent-relayed prompts alike.
   pi.on("ui_prompt_start", (_event) => scheduleNotify(TRIGGER.UI_PROMPT));
   pi.on("input", () => cancelPending());
+  // Any run that *starts* makes a pending alert stale, so this handler takes no
+  // filter. pi 1.2.0 made `before_agent_start` a union on `messageType` —
+  // `"user"` for a submitted prompt, RPC prompt or `pi.sendUserMessage()`, and
+  // `"custom"` for `pi.sendMessage(…, { triggerTurn: true })` fired while idle,
+  // which is new traffic that fires it too — and both members mean the same
+  // thing here: work is beginning, so "Task complete — waiting for input" is
+  // now a lie, whoever caused the run. Same reason `agent_start` cancels.
   pi.on("before_agent_start", () => cancelPending());
   pi.on("agent_start", () => cancelPending());
   // A prompt that closes without terminal input (e.g. a ctx.ui.confirm
@@ -201,11 +272,14 @@ export function registerNotify(pi: ExtensionAPI): void {
     }
   });
 
-  // Listen for raw terminal keystrokes — cancel on any key press
+  // Listen for raw terminal keystrokes — cancel on any key press, and only on
+  // one: terminal protocol traffic is not a keystroke (see `isKeystroke`).
   let unsubTerminalInput: (() => void) | null = null;
   pi.on("session_start", (_event, ctx: ExtensionContext) => {
-    unsubTerminalInput = ctx.ui.onTerminalInput((_data) => {
-      cancelPending();
+    unsubTerminalInput = ctx.ui.onTerminalInput((data) => {
+      if (isKeystroke(data)) {
+        cancelPending();
+      }
     });
   });