@pi-unipi/notify 2.1.2 → 2.2.0

package/README.md

@@ -24,9 +24,12 @@ Notify subscribes to Pi lifecycle events and routes notifications based on your
 | `workflow_end` | On | Workflow command completes |
 | `ralph_loop_end` | On | Ralph loop completes |
 | `mcp_server_error` | On | MCP server error |
-| `agent_end` | Off | Agent finishes responding |
+| `agent_end` | Off | Low-level agent run ends (may fire again on retries) |
+| `agent_settled` | Off | Agent fully settles after retries, compaction, and queued continuations |
 | `memory_consolidated` | Off | Memory auto-saved |
 | `session_shutdown` | Off | Session ends |
+| `ask_user_prompt` | Off | Agent asked a question and is waiting for an answer |
+| `permission_request` | Off | A permission prompt is about to be shown (requires [`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system)) |
 
 Notify registers with the info-screen dashboard, showing enabled platforms and last notification time. The footer subscribes to `NOTIFICATION_SENT` events to display notification stats.
 

package/events.ts

@@ -14,6 +14,7 @@ import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
 import { sendNtfyNotification } from "./platforms/ntfy.js";
 import { buildAskUserPromptMessage } from "./ask-user-prompt-message.js";
+import { buildPermissionPromptMessage } from "./permission-prompt-message.js";
 import { summarizeLastMessage } from "./summarize.js";
 
 // Event emitted by @juicesharp/rpiv-ask-user-question before showing its UI.
@@ -21,6 +22,13 @@ import { summarizeLastMessage } from "./summarize.js";
 // `./events` contract in npm.
 const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt" as const;
 
+// Event emitted by @gotgenes/pi-permission-system immediately before the
+// user-facing permission UI is invoked. Fires only for prompts a human must
+// answer — policy auto-allow/deny and session approvals do not emit it.
+// Kept as a local string (like the rpiv event above) because it belongs to a
+// third-party package rather than the unipi event contract.
+const PERMISSION_UI_PROMPT_EVENT = "permissions:ui_prompt" as const;
+
 /** Stored session context for modelRegistry access */
 let sessionCtx: ExtensionContext | null = null;
 
@@ -50,20 +58,22 @@ export const BUILTIN_EVENTS: Record<
   string,
   { hook: string; label: string }
 > = {
-  agent_end: { hook: "agent_end", label: "Agent Complete" },
+  agent_end: { hook: "agent_end", label: "Agent Run Complete" },
+  agent_settled: { hook: "agent_settled", label: "Agent Complete" },
   workflow_end: { hook: UNIPI_EVENTS.WORKFLOW_END, label: "Workflow Done" },
   ralph_loop_end: { hook: UNIPI_EVENTS.RALPH_LOOP_END, label: "Ralph Complete" },
   mcp_server_error: { hook: UNIPI_EVENTS.MCP_SERVER_ERROR, label: "MCP Error" },
   memory_consolidated: { hook: UNIPI_EVENTS.MEMORY_CONSOLIDATED, label: "Memory Saved" },
   session_shutdown: { hook: "session_shutdown", label: "Session End" },
   ask_user_prompt: { hook: UNIPI_EVENTS.ASK_USER_PROMPT, label: "Question Asked" },
+  permission_request: { hook: PERMISSION_UI_PROMPT_EVENT, label: "Permission Request" },
 };
 
 /**
  * Pi lifecycle event types (dispatched by ExtensionRunner).
  * These must use pi.on() — not pi.events.on() — to receive events.
  */
-const LIFECYCLE_EVENTS = new Set(["agent_end", "session_shutdown"]);
+const LIFECYCLE_EVENTS = new Set(["agent_end", "agent_settled", "session_shutdown"]);
 
 /**
  * Register event listeners for all enabled notification events.
@@ -77,9 +87,9 @@ export function registerEventListeners(
   // Remove all previously registered EventBus listeners to prevent accumulation
   // across reloads (EventBus persists but module instances are replaced).
   unregisterAll();
-  // Register built-in events (except agent_end which has custom logic)
+  // Register built-in events (except agent lifecycle notifications which have custom logic)
   for (const [eventKey, def] of Object.entries(BUILTIN_EVENTS)) {
-    if (eventKey === "agent_end") continue; // handled separately below
+    if (isAgentNotificationEvent(eventKey)) continue; // handled separately below
 
     const eventConfig = config.events[eventKey];
     if (!eventConfig?.enabled) continue;
@@ -95,8 +105,8 @@ export function registerEventListeners(
       );
     };
 
-    // pi lifecycle events (agent_end, session_shutdown) are dispatched via
-    // ExtensionRunner — must use pi.on(). These are stored in
+    // Pi lifecycle events are dispatched via ExtensionRunner — must use
+    // pi.on(). These are stored in
     // extension.handlers and automatically replaced on reload, so they
     // do NOT accumulate like EventBus listeners.
     if (LIFECYCLE_EVENTS.has(eventKey)) {
@@ -120,55 +130,8 @@ export function registerEventListeners(
     }));
   }
 
-  // agent_end — custom handler with session name and recap support
-  const agentEndConfig = config.events["agent_end"];
-  if (agentEndConfig?.enabled) {
-    const handler = (payload: unknown) => {
-      // Fire-and-forget: build message and dispatch in background,
-      // don't block agent_end from completing
-      const sessionName = pi.getSessionName?.();
-      const title = `Pi — ${BUILTIN_EVENTS.agent_end.label}`;
-
-      if (config.recap.enabled) {
-        // Recap mode: summarize asynchronously, then dispatch
-        const lastText = extractLastAssistantText(payload);
-        if (lastText && sessionCtx?.modelRegistry) {
-          const provider = extractProvider(config.recap.model);
-          const modelId = extractModelId(config.recap.model);
-          const model = sessionCtx.modelRegistry.find(provider, modelId);
-          if (model) {
-            sessionCtx.modelRegistry.getApiKeyAndHeaders(model)
-              .then((apiKeyResult) => {
-                const apiKey = apiKeyResult.ok ? (apiKeyResult as { apiKey?: string }).apiKey : undefined;
-                if (apiKey) {
-                  return summarizeLastMessage(lastText, apiKey, model.baseUrl, model.api, modelId)
-                    .then((recap) => sessionName ? `${sessionName}: ${recap}` : recap);
-                }
-                return buildAgentEndMessage(sessionName);
-              })
-              .catch(() => buildAgentEndMessage(sessionName))
-              .then((message) =>
-                dispatchNotification(pi, title, message, agentEndConfig.platforms, "agent_end", config, cwd)
-              )
-              .catch(() => {
-                // Silently ignore — background agent_end notification failure is non-blocking.
-              });
-            return;
-          }
-        }
-      }
-
-      // No recap or recap unavailable: dispatch immediately in background
-      const message = buildAgentEndMessage(sessionName);
-      dispatchNotification(pi, title, message, agentEndConfig.platforms, "agent_end", config, cwd).catch(
-        () => {
-          // Silently ignore — background agent_end notification failure is non-blocking.
-        }
-      );
-    };
-
-    (pi as any).on("agent_end", handler);
-  }
+  registerAgentNotification(pi, "agent_end", config, cwd);
+  registerAgentNotification(pi, "agent_settled", config, cwd);
 
   // Listen for dynamic module events
   const moduleHandler = async (payload: unknown) => {
@@ -335,25 +298,109 @@ function buildEventMessage(eventKey: string, payload: unknown): string {
     case "mcp_server_error":
       return `Server "${String(p.name || "unknown")}" error: ${String(p.error || "unknown error")}`;
     case "agent_end":
-      return "Agent finished responding";
+      return "Agent run finished responding";
+    case "agent_settled":
+      return "Agent is complete";
     case "memory_consolidated":
       return `Memory consolidated (${p.count || 0} items)`;
     case "session_shutdown":
       return "Session ending";
     case "ask_user_prompt":
       return buildAskUserPromptMessage(payload);
+    case "permission_request":
+      return buildPermissionPromptMessage(payload);
     default:
       return p.message ? String(p.message) : "Event occurred";
   }
 }
 
-/** Build agent_end message using session name */
-function buildAgentEndMessage(sessionName: string | undefined): string {
-  if (sessionName) return `${sessionName} - Agent is complete`;
-  return "Agent is complete";
+/** Register an agent lifecycle notification with session name and recap support. */
+function registerAgentNotification(
+  pi: ExtensionAPI,
+  eventKey: "agent_end" | "agent_settled",
+  config: NotifyConfig,
+  cwd: string
+): void {
+  const eventConfig = config.events[eventKey];
+  if (!eventConfig?.enabled) return;
+
+  const handler = (payload: unknown) => {
+    // Fire-and-forget: build message and dispatch in background,
+    // don't block agent lifecycle hooks from completing.
+    const sessionName = pi.getSessionName?.();
+    const title = `Pi — ${BUILTIN_EVENTS[eventKey].label}`;
+
+    if (config.recap.enabled) {
+      // Recap mode: summarize asynchronously, then dispatch.
+      // agent_settled does not currently include a messages payload, so fall
+      // back to the latest assistant message in the session.
+      const lastText = extractLastAssistantText(payload) ?? extractLastAssistantTextFromSession();
+      if (lastText && sessionCtx?.modelRegistry) {
+        const provider = extractProvider(config.recap.model);
+        const modelId = extractModelId(config.recap.model);
+        const model = sessionCtx.modelRegistry.find(provider, modelId);
+        if (model) {
+          sessionCtx.modelRegistry.getApiKeyAndHeaders(model)
+            .then((apiKeyResult) => {
+              const apiKey = apiKeyResult.ok ? (apiKeyResult as { apiKey?: string }).apiKey : undefined;
+              if (apiKey) {
+                return summarizeLastMessage(lastText, apiKey, model.baseUrl, model.api, modelId)
+                  .then((recap) => sessionName ? `${sessionName}: ${recap}` : recap);
+              }
+              return buildAgentLifecycleMessage(eventKey, sessionName);
+            })
+            .catch(() => buildAgentLifecycleMessage(eventKey, sessionName))
+            .then((message) =>
+              dispatchNotification(pi, title, message, eventConfig.platforms, eventKey, config, cwd)
+            )
+            .catch(() => {
+              // Silently ignore — background agent notification failure is non-blocking.
+            });
+          return;
+        }
+      }
+    }
+
+    // No recap or recap unavailable: dispatch immediately in background.
+    const message = buildAgentLifecycleMessage(eventKey, sessionName);
+    dispatchNotification(pi, title, message, eventConfig.platforms, eventKey, config, cwd).catch(
+      () => {
+        // Silently ignore — background agent notification failure is non-blocking.
+      }
+    );
+  };
+
+  (pi as any).on(eventKey, handler);
+}
+
+/** Whether an event key is an agent lifecycle notification with custom handling. */
+function isAgentNotificationEvent(eventKey: string): eventKey is "agent_end" | "agent_settled" {
+  return eventKey === "agent_end" || eventKey === "agent_settled";
+}
+
+/** Build agent lifecycle message using session name. */
+function buildAgentLifecycleMessage(
+  eventKey: "agent_end" | "agent_settled",
+  sessionName: string | undefined
+): string {
+  const status = eventKey === "agent_end" ? "Agent run is complete" : "Agent is complete";
+  if (sessionName) return `${sessionName} - ${status}`;
+  return status;
+}
+
+/** Extract text from the latest assistant message in the current session. */
+function extractLastAssistantTextFromSession(): string | null {
+  const entries = sessionCtx?.sessionManager.getEntries() ?? [];
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type !== "message") continue;
+    const text = extractAssistantText(entry.message);
+    if (text) return text;
+  }
+  return null;
 }
 
-/** Extract text from the last assistant message in agent_end payload */
+/** Extract text from the last assistant message in an agent lifecycle payload. */
 function extractLastAssistantText(payload: unknown): string | null {
   const p = payload as { messages?: Array<{ role?: string; content?: unknown }> };
   if (!p?.messages || !Array.isArray(p.messages)) return null;
@@ -363,21 +410,31 @@ function extractLastAssistantText(payload: unknown): string | null {
     const msg = p.messages[i];
     if (msg?.role !== "assistant") continue;
 
-    const content = msg.content;
-    if (typeof content === "string") return content;
-    if (Array.isArray(content)) {
-      // Extract text blocks from content array
-      const textParts: string[] = [];
-      for (const block of content) {
-        if (typeof block === "object" && block !== null) {
-          const b = block as { type?: string; text?: string };
-          if (b.type === "text" && typeof b.text === "string") {
-            textParts.push(b.text);
-          }
+    const text = extractAssistantText(msg);
+    if (text) return text;
+  }
+
+  return null;
+}
+
+/** Extract text from an assistant message-like object. */
+function extractAssistantText(message: { role?: string; content?: unknown }): string | null {
+  if (message.role !== "assistant") return null;
+
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    // Extract text blocks from content array.
+    const textParts: string[] = [];
+    for (const block of content) {
+      if (typeof block === "object" && block !== null) {
+        const b = block as { type?: string; text?: string };
+        if (b.type === "text" && typeof b.text === "string") {
+          textParts.push(b.text);
         }
       }
-      if (textParts.length > 0) return textParts.join("\n");
     }
+    if (textParts.length > 0) return textParts.join("\n");
   }
 
   return null;
@@ -394,11 +451,3 @@ function extractModelId(modelRef: string): string {
   const slashIdx = modelRef.indexOf("/");
   return slashIdx > 0 ? modelRef.slice(slashIdx + 1) : modelRef;
 }
-
-/** Resolve API key for a provider from environment variables */
-function resolveApiKey(modelRef: string): string | undefined {
-  const provider = extractProvider(modelRef);
-  // Try standard env var patterns
-  const envKey = `${provider.toUpperCase().replace(/-/g, "_")}_API_KEY`;
-  return process.env[envKey];
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
@@ -20,7 +20,7 @@
     "notifications"
   ],
   "scripts": {
-    "test": "tsc --noEmit && node --experimental-strip-types --test src/__tests__/*.test.ts",
+    "test": "tsc --noEmit && npx tsx --test src/__tests__/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "files": [
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "*",
+    "@pi-unipi/core": "2.2.0",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/settings.ts

@@ -24,9 +24,11 @@ export const DEFAULT_CONFIG: NotifyConfig = {
     ralph_loop_end: { enabled: true, platforms: [] },
     mcp_server_error: { enabled: true, platforms: [] },
     agent_end: { enabled: false, platforms: [] },
+    agent_settled: { enabled: false, platforms: [] },
     memory_consolidated: { enabled: false, platforms: [] },
     session_shutdown: { enabled: false, platforms: [] },
     ask_user_prompt: { enabled: false, platforms: [] },
+    permission_request: { enabled: false, platforms: [] },
   },
   native: {
     enabled: true,

package/skills/configure-notify/SKILL.md

@@ -34,8 +34,11 @@ Help users configure the `@pi-unipi/notify` notification system.
     "ralph_loop_end": { "enabled": true, "platforms": [] },
     "mcp_server_error": { "enabled": true, "platforms": [] },
     "agent_end": { "enabled": false, "platforms": [] },
+    "agent_settled": { "enabled": false, "platforms": [] },
     "memory_consolidated": { "enabled": false, "platforms": [] },
-    "session_shutdown": { "enabled": false, "platforms": [] }
+    "session_shutdown": { "enabled": false, "platforms": [] },
+    "ask_user_prompt": { "enabled": false, "platforms": [] },
+    "permission_request": { "enabled": false, "platforms": [] }
   },
   "native": {
     "enabled": true,
@@ -150,12 +153,38 @@ ntfy uses dedicated `ntfy.json` files at both global and project scope, with ful
 | `workflow_end` | On | Workflow command completes |
 | `ralph_loop_end` | On | Ralph loop completes |
 | `mcp_server_error` | On | MCP server error |
-| `agent_end` | Off | Agent finishes responding |
+| `agent_end` | Off | Low-level agent run ends (may fire again on retries) |
+| `agent_settled` | Off | Agent fully settles after retries, compaction, and queued continuations |
 | `memory_consolidated` | Off | Memory auto-saved |
 | `session_shutdown` | Off | Session ends |
+| `ask_user_prompt` | Off | Agent asked a question and is waiting for an answer |
+| `permission_request` | Off | A permission prompt is about to be shown |
 
 Each event can override `platforms` — empty array means use `defaultPlatforms`.
 
+### `permission_request`
+
+Fires on the `permissions:ui_prompt` broadcast from
+[`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system),
+emitted immediately before the user-facing permission UI is invoked. Policy
+auto-allow, policy deny, session approvals, and infrastructure auto-allowed
+requests do **not** emit it, so this event does not produce notification spam.
+Forwarded subagent prompts are handled too — the parent UI session emits the
+event right before showing the forwarded dialog, and the notification is
+suffixed with `(forwarded)`.
+
+The notification is formatted defensively from the payload's `agentName`,
+`surface`, `value` and `message` fields:
+
+```text
+Pi — Permission Request
+Current agent requested bash 'npm test'. Allow this command?
+```
+
+Enable it when you run Pi in a background pane and don't want to miss a
+permission prompt. If the permission system is not installed the event simply
+never fires.
+
 ## Agent workflow
 
 ### Reading current config

package/tui/gotify-setup.ts

@@ -11,6 +11,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { sendGotifyNotification } from "../platforms/gotify.js";
 import { updateConfig, loadConfig } from "../settings.js";
+import { boxInnerWidth } from "@pi-unipi/core";
 
 type SetupPhase =
   | "instructions"
@@ -235,7 +236,7 @@ export class GotifySetupOverlay implements Component {
   }
 
   render(width: number): string[] {
-    const innerWidth = Math.max(22, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     lines.push(this.borderLine(innerWidth, "top"));

package/tui/ntfy-setup.ts

@@ -11,6 +11,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { sendNtfyNotification } from "../platforms/ntfy.js";
 import { loadNtfyConfig, saveNtfyConfig, getNtfyConfigScope } from "../ntfy-config.js";
+import { boxInnerWidth } from "@pi-unipi/core";
 
 type SetupPhase =
   | "instructions"
@@ -281,7 +282,7 @@ export class NtfySetupOverlay implements Component {
   }
 
   render(width: number): string[] {
-    const innerWidth = Math.max(22, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     lines.push(this.borderLine(innerWidth, "top"));

package/tui/recap-model-selector.ts

@@ -8,7 +8,7 @@
 import type { Component } from "@earendil-works/pi-tui";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { readModelCache, type CachedModel } from "@pi-unipi/core";
+import { readModelCache, type CachedModel, boxInnerWidth } from "@pi-unipi/core";
 import { loadConfig, saveConfig } from "../settings.js";
 
 const DEFAULT_MODEL = "openrouter/openai/gpt-oss-20b";
@@ -170,7 +170,7 @@ export class RecapModelSelectorOverlay implements Component {
   }
 
   render(width: number): string[] {
-    const innerWidth = Math.max(40, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     lines.push(this.borderLine(innerWidth, "top"));

package/tui/settings-overlay.ts

@@ -15,6 +15,7 @@ import {
 } from "../settings.js";
 import { loadNtfyConfig, saveNtfyConfig, getNtfyConfigScope } from "../ntfy-config.js";
 import type { NotifyConfig, NtfyConfig } from "../types.js";
+import { boxInnerWidth } from "@pi-unipi/core";
 
 /** Section types */
 type Section = "platforms" | "events" | "recap";
@@ -174,7 +175,7 @@ export class NotifySettingsOverlay implements Component {
   }
 
   render(width: number): string[] {
-    const innerWidth = Math.max(22, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     lines.push(this.borderLine(innerWidth, "top"));

package/tui/telegram-setup.ts

@@ -10,6 +10,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { pollForChatId } from "../platforms/telegram.js";
 import { updateConfig } from "../settings.js";
+import { boxInnerWidth } from "@pi-unipi/core";
 
 type SetupPhase = "instructions" | "token" | "polling" | "success" | "error" | "timeout";
 
@@ -224,7 +225,7 @@ export class TelegramSetupOverlay implements Component {
   }
 
   render(width: number): string[] {
-    const innerWidth = Math.max(22, width - 2);
+    const innerWidth = boxInnerWidth(width);
     const lines: string[] = [];
 
     lines.push(this.borderLine(innerWidth, "top"));