@raidou/pi-notify 0.6.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 A notification extension for the [pi](https://github.com/earendil-works/pi-coding-agent) coding agent.
 
-`@raidou/pi-notify` fires a native desktop notification on idle, configured tool calls (e.g., `Tool call: ask_user`), and custom pi events (default: `permissions:ui_prompt`).
+`@raidou/pi-notify` fires a native desktop notification on idle, tool calls (optional, e.g. `Tool call: ask_user`), user-facing UI prompts (via pi's `ui_prompt_start`, e.g. permission approvals or `select`/`confirm`/`input` dialogs, requires pi >= 0.85.0), and custom pi events.
 
 ## Installation
 
@@ -25,12 +25,11 @@ All options live under the `piNotify` key in `~/.pi/agent/settings.json`. Everyt
 {
   "piNotify": {
     "enabled": true, // master on/off switch (default: true)
-    "notifyTools": ["ask_user", "ask_user_question"], // tools that trigger "Tool call" notifications
+    "notifyTools": [], // tools that trigger "Tool call" notifications (default: empty, i.e. no tool notifications)
     "tmuxSymbol": "🔔", // symbol appended to tmux window title (empty string to disable)
     "finished": true, // enable/disable "Idle" notification
     "events": {
-      "permissions:ui_prompt": "Permission prompt", // custom event channel -> notification message
-      "my:custom:event": "Custom event triggered", // add your own custom events
+      "my:custom:event": "Custom event triggered", // custom event channel -> notification message
       "other:event": false, // set to false to disable a specific event
     },
     "finishedThrottleSecs": 0, // 0 = always notify; >0 = skip finished toasts for runs shorter than N seconds
@@ -42,11 +41,13 @@ All options live under the `piNotify` key in `~/.pi/agent/settings.json`. Everyt
 
 ## What triggers a notification
 
-| Event             | Source                                                      | Default body                                |
-| ----------------- | ----------------------------------------------------------- | ------------------------------------------- |
-| **Finished**      | `agent_settled` (pi idle, no active jobs)                   | `Idle`                                      |
-| **Tool calls**    | `tool_call` on tools in `notifyTools`                       | `Tool call: <toolName>`                     |
-| **Custom events** | Custom pi event channels (default: `permissions:ui_prompt`) | Customizable (default: `Permission prompt`) |
+| Event             | Source                                                                | Default body                      |
+| ----------------- | --------------------------------------------------------------------- | --------------------------------- |
+| **Finished**      | `agent_settled` (pi idle, no active jobs)                             | `Idle`                            |
+| **Tool calls**    | `tool_call` on tools in `notifyTools` (default: none)                 | `Tool call: <toolName>`           |
+| **UI prompts**    | `ui_prompt_start` (requires pi >= 0.85.0)                             | `Waiting: <kind>[ — <title>]` |
+| **Custom events** | Custom pi event channels configured in `events`                       | Customizable                      |
+| **External API**  | `pi.events.emit('pi-notify:notify', 'message')` from other extensions | The emitted message               |
 
 ### Job tracking for background tasks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidou/pi-notify",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Desktop notification extension for the pi coding agent.",
   "keywords": [
     "pi",
@@ -34,16 +34,17 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.80.7",
     "emittery": "^2.0.0",
     "lodash-es": "^4.18.1",
     "node-notifier": "^10.0.1",
     "proper-lockfile": "^4.1.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.79.0"
+    "@earendil-works/pi-coding-agent": ">=0.85.0",
+    "@earendil-works/pi-tui": ">=0.85.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-tui": "0.85.1",
     "@raidou/eslint-config-base": "^4.4.3",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^22.0.0",

package/src/config.ts

@@ -28,20 +28,8 @@ export interface ResolvedNotifyConfig {
   readonly tmuxSymbol: string
 }
 
-/**
- * Default tool names that trigger notifications.
- *
- * Note: These are built-in pi tool names. If pi renames these tools, the default should be updated.
- * Source: @earendil-works/pi-coding-agent
- */
-const DEFAULT_NOTIFY_TOOLS = ['ask_user', 'ask_user_question'] as const
-
 const DEFAULT_TMUX_SYMBOL = '🔔'
 
-const DEFAULT_EVENTS: NotifyEventsConfig = {
-  'permissions:ui_prompt': 'Permission prompt',
-}
-
 const SETTINGS_PATH = join(getAgentDir(), 'settings.json')
 
 function readRawConfig(): NotifyConfig {
@@ -59,11 +47,10 @@ function readRawConfig(): NotifyConfig {
 
 export function loadConfig(): ResolvedNotifyConfig {
   const cfg = readRawConfig()
-  const events = cfg.events ?? DEFAULT_EVENTS
   return {
     enabled: cfg.enabled ?? true,
-    notifyTools: new Set(cfg.notifyTools ?? DEFAULT_NOTIFY_TOOLS),
-    events,
+    notifyTools: new Set(cfg.notifyTools ?? []),
+    events: cfg.events ?? {},
     finished: cfg.finished ?? true,
     onlyNotifyWhenUnfocused: cfg.onlyNotifyWhenUnfocused ?? true,
     unfocusedActivityThresholdMs: Math.max(

package/src/dashboard/session-store.test.ts

@@ -171,10 +171,11 @@ describe('SessionStore', () => {
     )
     store.register(vi.fn())
 
-    expect(emitSpy).toHaveBeenCalledTimes(4)
+    expect(emitSpy).toHaveBeenCalledTimes(5)
     expect(emitSpy).toHaveBeenCalledWith('running', expect.any(Function))
     expect(emitSpy).toHaveBeenCalledWith('idle', expect.any(Function))
     expect(emitSpy).toHaveBeenCalledWith('tool', expect.any(Function))
+    expect(emitSpy).toHaveBeenCalledWith('ui_prompt', expect.any(Function))
     expect(emitSpy).toHaveBeenCalledWith('event', expect.any(Function))
     expect(piOnSpy).toHaveBeenCalledWith('session_start', expect.any(Function))
   })
@@ -347,7 +348,7 @@ describe('SessionStore', () => {
     nowSpy.mockRestore()
   })
 
-  it('does not update state on tool emission outside notifyTools', async () => {
+  it('updates state immediately on event emission', async () => {
     await updateState(() => ({ version: 2, sessions: {} }))
     const pi = makeFakePi()
     const jobTracker = {
@@ -359,8 +360,8 @@ describe('SessionStore', () => {
       pi as unknown as ExtensionAPI,
       jobTracker,
       {
-        notifyTools: new Set(['read']),
-        events: {},
+        notifyTools: new Set(['bash']),
+        events: { 'permissions:ui_prompt': 'msg' },
       } as unknown as ResolvedNotifyConfig,
     )
     tracker.register(() => {})
@@ -374,20 +375,53 @@ describe('SessionStore', () => {
     })
     await new Promise((resolve) => setTimeout(resolve, 20))
 
-    expect(readState().sessions[String(process.pid)]?.state).toBe('idle')
+    pi.emitEvent('permissions:ui_prompt', {})
+    await new Promise((resolve) => setTimeout(resolve, 20))
 
-    pi.emit('tool_call', {
-      type: 'tool_call',
-      toolCallId: 't1',
-      toolName: 'grep',
+    const record = readState().sessions[String(process.pid)]
+    expect(record?.state).toBe('event:permissions:ui_prompt')
+  })
+
+  it('updates state immediately on ui_prompt emission', async () => {
+    await updateState(() => ({ version: 2, sessions: {} }))
+    const pi = makeFakePi()
+    const jobTracker = {
+      hasActiveJobs: false,
+      onStart: () => () => {},
+      onEnd: () => () => {},
+    } as unknown as JobTracker
+    const tracker = new StateTracker(
+      pi as unknown as ExtensionAPI,
+      jobTracker,
+      {
+        notifyTools: new Set([]),
+        events: {},
+      } as unknown as ResolvedNotifyConfig,
+    )
+    tracker.register(() => {})
+
+    const store = new SessionStore(pi as unknown as ExtensionAPI, tracker)
+    store.register(() => {})
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
     })
     await new Promise((resolve) => setTimeout(resolve, 20))
 
+    pi.emit('ui_prompt_start', {
+      type: 'ui_prompt_start',
+      reason: 'ui_prompt',
+      kind: 'confirm',
+    })
+
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
     const record = readState().sessions[String(process.pid)]
-    expect(record?.state).toBe('idle')
+    expect(record?.state).toBe('ui_prompt:confirm')
   })
 
-  it('updates state immediately on event emission', async () => {
+  it('does not update state on tool emission outside notifyTools', async () => {
     await updateState(() => ({ version: 2, sessions: {} }))
     const pi = makeFakePi()
     const jobTracker = {
@@ -399,8 +433,8 @@ describe('SessionStore', () => {
       pi as unknown as ExtensionAPI,
       jobTracker,
       {
-        notifyTools: new Set(['bash']),
-        events: { 'permissions:ui_prompt': 'msg' },
+        notifyTools: new Set(['read']),
+        events: {},
       } as unknown as ResolvedNotifyConfig,
     )
     tracker.register(() => {})
@@ -414,11 +448,17 @@ describe('SessionStore', () => {
     })
     await new Promise((resolve) => setTimeout(resolve, 20))
 
-    pi.emitEvent('permissions:ui_prompt', {})
+    expect(readState().sessions[String(process.pid)]?.state).toBe('idle')
+
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'grep',
+    })
     await new Promise((resolve) => setTimeout(resolve, 20))
 
     const record = readState().sessions[String(process.pid)]
-    expect(record?.state).toBe('event:permissions:ui_prompt')
+    expect(record?.state).toBe('idle')
   })
 
   it('ignores tool and event emissions before session_start', async () => {

package/src/dashboard/session-store.ts

@@ -79,6 +79,9 @@ export class SessionStore extends Registrar {
       this.stateTracker.events.on('tool', async ({ data }) => {
         await this.saveSession(`tool_call:${data}`)
       }),
+      this.stateTracker.events.on('ui_prompt', async ({ data }) => {
+        await this.saveSession(`ui_prompt:${data}`)
+      }),
       this.stateTracker.events.on('event', async ({ data }) => {
         await this.saveSession(`event:${data}`)
       }),

package/src/dashboard/state-store.ts

@@ -54,7 +54,11 @@ export async function readSessions(): Promise<SessionRecord[]> {
 }
 
 export type SessionState =
-  'running' | 'idle' | `tool_call:${string}` | `event:${string}`
+  | 'running'
+  | 'idle'
+  | `tool_call:${string}`
+  | `event:${string}`
+  | `ui_prompt:${string}`
 
 export interface SessionRecord {
   pid: number
@@ -112,8 +116,12 @@ function parseSessionRecord(value: unknown): SessionRecord | undefined {
 
 function isActivityState(
   value: string,
-): value is `tool_call:${string}` | `event:${string}` {
-  return value.startsWith('tool_call:') || value.startsWith('event:')
+): value is `tool_call:${string}` | `event:${string}` | `ui_prompt:${string}` {
+  return (
+    value.startsWith('tool_call:') ||
+    value.startsWith('event:') ||
+    value.startsWith('ui_prompt:')
+  )
 }
 
 function isSessionState(value: unknown): value is SessionState {

package/src/dashboard/ui/dashboard.test.ts

@@ -8,6 +8,7 @@ import { Dashboard } from './dashboard.js'
 const theme = {
   fg: (color: ThemeColor, text: string) => `\x1b[90m${text}\x1b[0m`,
   bold: (text: string) => `\x1b[1m${text}\x1b[0m`,
+  underline: (text: string) => `\x1b[4m${text}\x1b[0m`,
 } as unknown as Theme
 
 const ANSI_RE =

package/src/state-tracker.test.ts

@@ -89,7 +89,7 @@ const BASE_CONFIG: ResolvedNotifyConfig = {
   enabled: true,
   notifyTools: new Set(['bash', 'read']),
   events: {
-    'permissions:ui_prompt': 'msg',
+    'my:custom:event': 'msg',
     'disabled:channel': false,
   },
   finished: true,
@@ -171,6 +171,19 @@ describe('StateTracker', () => {
     expect(states).toEqual(['running'])
   })
 
+  it('re-emits running after a notified custom event resets the state', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emitEvent('my:custom:event', {})
+    pi.emit('turn_start')
+
+    await flush()
+
+    expect(states).toEqual(['running', 'running'])
+  })
+
   it('re-emits running after a notified tool call resets the state', async () => {
     const pi = makeFakePi()
     const { states } = makeTracker(pi)
@@ -220,12 +233,12 @@ describe('StateTracker', () => {
       events.push(event.data)
     })
 
-    pi.emitEvent('permissions:ui_prompt', {})
+    pi.emitEvent('my:custom:event', {})
     pi.emitEvent('disabled:channel', {})
 
     await flush()
 
-    expect(events).toEqual(['permissions:ui_prompt'])
+    expect(events).toEqual(['my:custom:event'])
   })
 
   it('unsubscribes from channel events on stop', async () => {
@@ -237,7 +250,7 @@ describe('StateTracker', () => {
     })
 
     tracker.stop()
-    pi.emitEvent('permissions:ui_prompt', {})
+    pi.emitEvent('my:custom:event', {})
 
     await flush()
 
@@ -262,7 +275,7 @@ describe('StateTracker', () => {
     const pi = makeFakePi()
     const { bodies } = makeTracker(pi)
 
-    pi.emitEvent('permissions:ui_prompt', {})
+    pi.emitEvent('my:custom:event', {})
 
     expect(bodies).toEqual(['msg'])
   })
@@ -297,6 +310,56 @@ describe('StateTracker', () => {
     expect(bodies).toEqual(['custom payload'])
   })
 
+  it('notifies on ui_prompt_start with kind and title', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('ui_prompt_start', {
+      type: 'ui_prompt_start',
+      reason: 'ui_prompt',
+      kind: 'confirm',
+      title: 'Apply changes?',
+    })
+
+    expect(bodies).toEqual(['Waiting: Confirm — Apply changes?'])
+  })
+
+  it('notifies on ui_prompt_start without a title', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('ui_prompt_start', {
+      type: 'ui_prompt_start',
+      reason: 'ui_prompt',
+      kind: 'select',
+    })
+
+    expect(bodies).toEqual(['Waiting: Select'])
+  })
+
+  it('emits ui_prompt with the raw kind and resets running', async () => {
+    const pi = makeFakePi()
+    const { tracker, states } = makeTracker(pi)
+    const kinds: string[] = []
+    tracker.events.on('ui_prompt', (event) => {
+      kinds.push(event.data)
+    })
+
+    pi.emit('turn_start')
+    pi.emit('ui_prompt_start', {
+      type: 'ui_prompt_start',
+      reason: 'ui_prompt',
+      kind: 'confirm',
+      title: 'Apply changes?',
+    })
+    pi.emit('turn_start')
+
+    await flush()
+
+    expect(kinds).toEqual(['confirm'])
+    expect(states).toEqual(['running', 'running'])
+  })
+
   it('notifies for tools in notifyTools', () => {
     const pi = makeFakePi()
     const { bodies } = makeTracker(pi)
@@ -323,6 +386,22 @@ describe('StateTracker', () => {
     expect(bodies).toEqual([])
   })
 
+  it('does not notify when notifyTools is empty', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi, {
+      ...BASE_CONFIG,
+      notifyTools: new Set([]),
+    })
+
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'bash',
+    })
+
+    expect(bodies).toEqual([])
+  })
+
   it('notifies Idle on idle when there was activity', async () => {
     const pi = makeFakePi()
     const { bodies } = makeTracker(pi)

package/src/state-tracker.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import type {
+  ExtensionAPI,
+  UIPromptKind,
+} from '@earendil-works/pi-coding-agent'
 import Emittery from 'emittery'
 
 import type { ResolvedNotifyConfig } from './config.js'
@@ -10,12 +13,27 @@ export const PI_NOTIFY_EVENT = 'pi-notify:notify'
 
 const IDLE_TIMEOUT_MS = 10000
 
+const PROMPT_KIND_LABELS: Record<UIPromptKind, string> = {
+  select: 'Select',
+  confirm: 'Confirm',
+  input: 'Input',
+  editor: 'Editor',
+  custom: 'Prompt',
+}
+
+function promptMessage(kind: UIPromptKind, title?: string): string {
+  const label = PROMPT_KIND_LABELS[kind]
+  if (!title) return `Waiting: ${label}`
+  return `Waiting: ${label} — ${title}`
+}
+
 export class StateTracker extends Registrar {
   readonly events = new Emittery<{
     running: never
     idle: never
     tool: string
     event: string
+    ui_prompt: string
   }>()
 
   private readonly jobTracker: JobTracker
@@ -80,6 +98,14 @@ export class StateTracker extends Registrar {
     this.unsubscribes.push(customEventUnsub)
   }
 
+  private setupUiPrompt() {
+    this.pi.on('ui_prompt_start', (event) => {
+      this.notify(promptMessage(event.kind, event.title))
+      this.running = false
+      void this.events.emit('ui_prompt', event.kind)
+    })
+  }
+
   private setupToolCall() {
     this.pi.on('tool_call', (event) => {
       if (this.config.notifyTools.has(event.toolName)) {
@@ -95,6 +121,7 @@ export class StateTracker extends Registrar {
     this.notify = notify
 
     this.setupPiEvents()
+    this.setupUiPrompt()
     this.setupToolCall()
 
     this.pi.on('turn_start', () => {