@pi-archimedes/notify 2.3.0 → 2.5.0

package/README.md

@@ -11,7 +11,7 @@ Get notified when Pi finishes long tasks or needs an answer, without constant po
 - **Terminal-aware dispatch** — auto-detects your terminal and uses the optimal protocol (OSC 99, OSC 9, OSC 777, or PowerShell toasts)
 - **tmux passthrough** — all sequences wrapped via DCS for correct rendering inside tmux
 - **Per-trigger toggles** — independently enable/disable notifications for task completion and unanswered questions
-- **Bus-driven** — listens for `agent_end` and `ASK_REQUEST` bus events, so it works with any package that emits them
+- **Pi-native triggers** — keyed on pi's `agent_settled` and `ui_prompt_start` lifecycle events, so task completion works and *any* blocking extension prompt (ask, sudo, mcp OAuth) can hold your attention
 
 ## Install
 
@@ -27,17 +27,18 @@ pi install npm:pi-archimedes
 
 ## Usage
 
-When the agent finishes a task (`agent_end`) or a question is asked (`ASK_REQUEST`), a timer starts. If you don't interact for the configured delay, a desktop notification fires. Any keystroke — even just pressing a key without submitting — cancels the timer immediately.
+When the agent's run has settled (`agent_settled`) or an extension opens a blocking prompt (`ui_prompt_start` — ask, sudo, mcp OAuth), a timer starts. If you don't interact for the configured delay, a desktop notification fires. Any keystroke — even just pressing a key without submitting — cancels the timer immediately.
 
 ## Settings
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `enabled` | bool | `true` | Enable desktop notifications |
 | `notifyOnAgentEnd` | bool | `true` | Notify when agent finishes a task |
 | `notifyOnQuestion` | bool | `true` | Notify when a question needs your answer |
 | `delayMs` | number | `30000` | Milliseconds to wait before sending notification (default 30 seconds) |
 
+On/off is managed by the suite: toggle via `/plugins` (`archimedes.notify.enabled`, default on).
+
 Settings are stored in `~/.pi/agent/settings.json` under the `archimedes.notify` namespace.
 
 ## Terminal compatibility
@@ -53,6 +54,6 @@ Settings are stored in `~/.pi/agent/settings.json` under the `archimedes.notify`
 
 ## Integration
 
-When installed via `pi-archimedes` (the meta package), the notify package is automatically registered and its settings appear in the `/archimedes` settings panel. Standalone installs work independently — any package emitting `agent_end` or `ASK_REQUEST` bus events will trigger notifications.
+When installed via `pi-archimedes` (the meta package), the notify package is automatically registered and its settings appear in the `/archimedes` settings panel. Standalone installs work independently — any blocking extension UI prompt will trigger the question notification.
 
 ← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/notify",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -14,15 +14,15 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.3.0"
+    "@pi-archimedes/core": "2.5.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/default-export.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from "vitest";
+import defaultExport from "./index.js";
+
+describe("notify default export (standalone factory)", () => {
+	it("is a function that registers the notify handlers (registerNotify subscribes its own session events)", () => {
+		expect(typeof defaultExport).toBe("function");
+
+		const on = vi.fn();
+		const pi = { on } as any;
+
+		defaultExport(pi);
+
+		const events = on.mock.calls.map((c: Array<unknown>) => c[0]);
+		expect(events).toEqual(
+			expect.arrayContaining([
+				"agent_settled",
+				"ui_prompt_end",
+			"ui_prompt_start",
+				"input",
+				"before_agent_start",
+				"agent_start",
+				"session_start",
+				"session_shutdown",
+			]),
+		);
+	});
+});

package/src/index.ts

@@ -1,28 +1,27 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
 import { loadConfig, saveConfig } from "@pi-archimedes/core/settings-io";
-import { getBus, Events } from "@pi-archimedes/core/bus";
 import { execFile } from "node:child_process";
 
 // ── Trigger constants ────────────────────────────────────────────────────────
 
 const TRIGGER = {
-  AGENT_END: "agent_end",
-  ASK_REQUEST: "ask_request",
+  AGENT_SETTLED: "agent_settled",
+  UI_PROMPT: "ui_prompt",
 } as const;
 type TriggerType = (typeof TRIGGER)[keyof typeof TRIGGER];
 
 // ── Config ──────────────────────────────────────────────────────────────────
 
 export interface NotifyConfig {
-  enabled: boolean;
+  // suite-managed by meta's plugin gate (archimedes.notify.enabled — see ADR 0012); notify never reads this
+  enabled?: boolean;
   notifyOnAgentEnd: boolean;
   notifyOnQuestion: boolean;
   delayMs: number;
 }
 
 export const DEFAULT_NOTIFY_CONFIG: NotifyConfig = {
-  enabled: true,
   notifyOnAgentEnd: true,
   notifyOnQuestion: true,
   delayMs: 30_000,
@@ -153,15 +152,11 @@ export function scheduleNotify(trigger: TriggerType): void {
   // Load config fresh on each trigger
   const config = loadNotifyConfig();
 
-  if (!config.enabled) {
+  if (trigger === TRIGGER.AGENT_SETTLED && !config.notifyOnAgentEnd) {
     return;
   }
 
-  if (trigger === TRIGGER.AGENT_END && !config.notifyOnAgentEnd) {
-    return;
-  }
-
-  if (trigger === TRIGGER.ASK_REQUEST && !config.notifyOnQuestion) {
+  if (trigger === TRIGGER.UI_PROMPT && !config.notifyOnQuestion) {
     return;
   }
 
@@ -178,7 +173,7 @@ export function scheduleNotify(trigger: TriggerType): void {
 
 /** Fire the actual notification based on the pending trigger. */
 function fireNotification(trigger: TriggerType | null): void {
-  if (trigger === TRIGGER.AGENT_END) {
+  if (trigger === TRIGGER.AGENT_SETTLED) {
     notify("Pi", "Task complete — waiting for input");
   } else {
     notify("Pi", "A question needs your answer");
@@ -189,15 +184,22 @@ function fireNotification(trigger: TriggerType | null): void {
 
 /** Register the notify extension with the Pi agent. */
 export function registerNotify(pi: ExtensionAPI): void {
-  pi.on("agent_end", () => scheduleNotify(TRIGGER.AGENT_END));
+  pi.on("agent_settled", () => scheduleNotify(TRIGGER.AGENT_SETTLED));
+  // Any blocking extension UI prompt (ask, sudo, mcp OAuth) — fires in the
+  // parent process for direct and subagent-relayed prompts alike.
+  pi.on("ui_prompt_start", (_event) => scheduleNotify(TRIGGER.UI_PROMPT));
   pi.on("input", () => cancelPending());
   pi.on("before_agent_start", () => cancelPending());
   pi.on("agent_start", () => cancelPending());
-
-  // Listen for ask requests from the bus (ask package emits this)
-  const unsubAskRequest = getBus().on(Events.ASK_REQUEST, () =>
-    scheduleNotify(TRIGGER.ASK_REQUEST),
-  );
+  // A prompt that closes without terminal input (e.g. the mcp OAuth
+  // loader finishing from the browser's `done()`) cancels the question
+  // timer so a long-gone prompt does not fire a stale "question needs
+  // your answer". Scoped so it never wipes a pending "task complete" timer.
+  pi.on("ui_prompt_end", () => {
+    if (pendingTrigger === TRIGGER.UI_PROMPT) {
+      cancelPending();
+    }
+  });
 
   // Listen for raw terminal keystrokes — cancel on any key press
   let unsubTerminalInput: (() => void) | null = null;
@@ -213,18 +215,19 @@ export function registerNotify(pi: ExtensionAPI): void {
   });
 }
 
+// ── Default export (for standalone pi.extensions loading) ─────────────────
+
+// registerNotify subscribes its own session_start/session_shutdown (and
+// agent/input) handlers internally, so the default factory just registers it.
+export default function (pi: ExtensionAPI): void {
+  registerNotify(pi);
+}
+
 // ── Settings UI ─────────────────────────────────────────────────────────────
 
 /** Build settings UI items for the notify package. */
 export function getNotifySettingsItems(config: NotifyConfig): SettingItem[] {
   return [
-    {
-      id: "enabled",
-      label: "Notifications",
-      description: "Enable desktop notifications",
-      currentValue: config.enabled ? "On" : "Off",
-      values: ["On", "Off"],
-    },
     {
       id: "notifyOnAgentEnd",
       label: "Notify on task complete",