@raidou/pi-notify 0.3.1 → 0.5.0

package/README.md

@@ -10,11 +10,33 @@ A notification extension for the [pi](https://github.com/earendil-works/pi-codin
 pi install npm:@raidou/pi-notify
 ```
 
-Or, for local development, add the repo path to your `~/.pi/agent/settings.json`:
+Or, for local development
+
+```bash
+cd path/to/pi-notify
+pi install .
+```
+
+## Configuration
+
+All options live under the `piNotify` key in `~/.pi/agent/settings.json`. Everything is optional.
 
 ```jsonc
 {
-  "extensions": ["/absolute/path/to/pi-notify"],
+  "piNotify": {
+    "enabled": true, // master on/off switch (default: true)
+    "notifyTools": ["ask_user", "ask_user_question"], // tools that trigger "Tool call" 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
+      "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
+    "onlyNotifyWhenUnfocused": true, // only notify when user has been inactive
+    "unfocusedActivityThresholdSecs": 30, // seconds of inactivity before considering user "unfocused"
+  },
 }
 ```
 
@@ -44,43 +66,21 @@ function endBackgroundJob(jobId: string): void {
 
 Events are automatically cleaned up on `session_shutdown`.
 
-## Configuration
+## Commands
 
-All options live under the `piNotify` key in `~/.pi/agent/settings.json`. Everything is optional.
+### `/notify-dashboard`
 
-```jsonc
-{
-  "piNotify": {
-    "enabled": true, // master on/off switch (default: true)
-    "notifyTools": ["ask_user", "ask_user_question"], // tools that trigger "Tool call" 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
-    },
-    "finishedThrottleSecs": 0, // 0 = always notify; >0 = skip finished toasts for runs shorter than N seconds
-    "onlyNotifyWhenUnfocused": true, // only notify when user has been inactive
-    "unfocusedActivityThresholdSecs": 30, // seconds of inactivity before considering user "unfocused"
-  },
-}
-```
+Open a full-screen TUI dashboard listing all pi sessions, with summary counts (total, running, idle) and an auto-refresh every second.
 
-### Disabling specific events
+Columns: `SESSION_ID` (last 6 chars), `PID`, `STATE` (running/idle, color-coded), `PROJECT`, `UPTIME`.
 
-To disable a specific event, set its message to an empty string:
+Keybindings:
 
-```jsonc
-{
-  "piNotify": {
-    "events": {
-      "permissions:ui_prompt": "", // disable permission notifications
-    },
-  },
-}
-```
+- `↑` / `↓` or `j` / `k` — scroll
+- `r` — refresh
+- `q` or `esc` — close
 
-## Testing
+### `/notify-test`
 
 Run `/notify-test` inside pi to fire a test notification.
 Pass a string argument (e.g., `/notify-test hello`) to override the body.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@raidou/pi-notify",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Desktop notification extension for the pi coding agent.",
   "keywords": [
-    "pi-package",
     "pi",
+    "pi-package",
     "pi-extension",
     "pi-coding-agent",
     "notifications",
@@ -28,22 +28,29 @@
   },
   "main": "./src/index.ts",
   "scripts": {
-    "test": "pnpm run test:types && pnpm run test:lint",
+    "test": "pnpm run test:types && pnpm run test:lint && pnpm run test:unit",
     "test:types": "tsc --noEmit",
-    "test:lint": "eslint --fix ."
+    "test:lint": "eslint --fix .",
+    "test:unit": "vitest run"
   },
   "dependencies": {
     "@earendil-works/pi-tui": "0.80.7",
-    "node-notifier": "^10.0.1"
+    "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"
   },
   "devDependencies": {
     "@raidou/eslint-config-base": "^4.4.3",
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^22.0.0",
+    "@types/proper-lockfile": "^4.1.4",
     "eslint": "^10.7.0",
     "prettier": "^3.9.5",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.11"
   }
 }

package/src/config.ts

@@ -3,8 +3,9 @@ import { join } from 'node:path'
 
 import { getAgentDir } from '@earendil-works/pi-coding-agent'
 
+// `false` disables the event
 interface NotifyEventsConfig {
-  readonly [channel: string]: string
+  readonly [channel: string]: string | false
 }
 
 interface NotifyConfig {
@@ -12,7 +13,6 @@ interface NotifyConfig {
   readonly notifyTools?: readonly string[]
   readonly events?: NotifyEventsConfig
   readonly finished?: boolean
-  readonly finishedThrottleSecs?: number
   readonly onlyNotifyWhenUnfocused?: boolean
   readonly unfocusedActivityThresholdSecs?: number
   readonly tmuxSymbol?: string
@@ -23,7 +23,6 @@ export interface ResolvedNotifyConfig {
   readonly notifyTools: ReadonlySet<string>
   readonly events: NotifyEventsConfig
   readonly finished: boolean
-  readonly finishedThrottleMs: number
   readonly onlyNotifyWhenUnfocused: boolean
   readonly unfocusedActivityThresholdMs: number
   readonly tmuxSymbol: string
@@ -66,7 +65,6 @@ export function loadConfig(): ResolvedNotifyConfig {
     notifyTools: new Set(cfg.notifyTools ?? DEFAULT_NOTIFY_TOOLS),
     events,
     finished: cfg.finished ?? true,
-    finishedThrottleMs: Math.max(0, (cfg.finishedThrottleSecs ?? 0) * 1000),
     onlyNotifyWhenUnfocused: cfg.onlyNotifyWhenUnfocused ?? true,
     unfocusedActivityThresholdMs: Math.max(
       0,

package/src/dashboard/command.ts

@@ -1,33 +1,30 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
-
+import { Registrar } from '../shared/registrar.js'
 import { readSessions } from './state-store.js'
-import { createDashboard } from './ui.js'
-
-export class DashboardCommand {
-  constructor(private readonly pi: ExtensionAPI) {}
+import { Dashboard } from './ui/dashboard.js'
 
-  register(): void {
+export class DashboardCommand extends Registrar {
+  protected override setup(): void {
     this.pi.registerCommand('notify-dashboard', {
       description: 'Show all pi sessions notify dashboard',
       handler: async (_args, ctx) => {
-        const initialSessions = readSessions()
+        const initialSessions = await readSessions()
 
         await ctx.ui.custom<unknown>((tui, theme, _keybindings, done) => {
-          const dashboard = createDashboard({
+          let closed = false
+          const dashboard = new Dashboard({
             tui,
             theme,
             initialSessions,
             onRefresh: async () => readSessions(),
             onClose: () => {
+              if (closed) return
+              closed = true
+              dashboard.dispose()
               done(undefined)
             },
           })
 
-          return {
-            render: dashboard.render.bind(dashboard),
-            handleInput: dashboard.handleInput.bind(dashboard),
-            invalidate: dashboard.invalidate.bind(dashboard),
-          }
+          return dashboard
         })
 
         return undefined

package/src/dashboard/consts.ts

@@ -0,0 +1,6 @@
+import { join } from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+
+export const STATE_FILE = join(getAgentDir(), 'pi-notify', 'state.json')
+export const STATE_TMP_FILE = `${STATE_FILE}.tmp`

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

@@ -0,0 +1,438 @@
+import { rmSync, unlinkSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+vi.mock('./consts.js', async () => {
+  const { mkdtempSync } = await import('node:fs')
+  const path = await import('node:path')
+  const { tmpdir } = await import('node:os')
+
+  const stateDir = mkdtempSync(path.join(tmpdir(), 'pi-notify-test-'))
+  return {
+    STATE_FILE: path.join(stateDir, 'state.json'),
+    STATE_TMP_FILE: path.join(stateDir, 'state.json.tmp'),
+  }
+})
+
+import type { ResolvedNotifyConfig } from '../config.js'
+import type { JobTracker } from '../jobs.js'
+import { StateTracker } from '../state-tracker.js'
+import { STATE_FILE } from './consts.js'
+import { SessionStore } from './session-store.js'
+import { readState, updateState } from './state-store.js'
+
+type EventsListener = (payload: unknown) => void
+
+interface FakeStateTracker {
+  events: {
+    on(event: string, listener: EventsListener): () => void
+    emit(event: string, data?: unknown): void
+  }
+}
+
+interface FakeSessionManager {
+  getSessionId(): string
+}
+
+interface FakePiContext {
+  cwd: string
+  sessionManager: FakeSessionManager
+}
+
+interface FakePi {
+  listeners: Map<string, Set<(...args: unknown[]) => void>>
+  eventListeners: Map<string, Set<EventsListener>>
+  on(event: string, listener: (...args: unknown[]) => void): void
+  events: { on(event: string, listener: EventsListener): () => void }
+  emit(event: string, ...args: unknown[]): void
+  emitEvent(event: string, payload: unknown): void
+  emitSessionStart(ctx: FakePiContext): void
+}
+
+function makeFakePi(): FakePi {
+  const listeners = new Map<string, Set<(...args: unknown[]) => void>>()
+  const eventListeners = new Map<string, Set<EventsListener>>()
+  const pi: FakePi = {
+    listeners,
+    eventListeners,
+    on(event, listener) {
+      let set = listeners.get(event)
+      if (!set) {
+        set = new Set()
+        listeners.set(event, set)
+      }
+      set.add(listener)
+    },
+    events: {
+      on(event, listener) {
+        let set = eventListeners.get(event)
+        if (!set) {
+          set = new Set()
+          eventListeners.set(event, set)
+        }
+        set.add(listener)
+        return () => {
+          set.delete(listener)
+        }
+      },
+    },
+    emit(event, ...args) {
+      const set = listeners.get(event)
+      if (!set) return
+      for (const listener of [...set]) listener(...args)
+    },
+    emitEvent(event, payload) {
+      const set = eventListeners.get(event)
+      if (!set) return
+      for (const listener of [...set]) listener(payload)
+    },
+    emitSessionStart(ctx) {
+      const set = listeners.get('session_start')
+      if (!set) return
+      for (const listener of [...set]) listener(undefined, ctx)
+    },
+  }
+  return pi
+}
+
+function makeFakeStateTracker(): FakeStateTracker {
+  const listeners = new Map<string, Set<EventsListener>>()
+  return {
+    events: {
+      on(event, listener) {
+        let set = listeners.get(event)
+        if (!set) {
+          set = new Set()
+          listeners.set(event, set)
+        }
+        set.add(listener)
+        return () => {
+          set.delete(listener)
+        }
+      },
+      emit(event, data?: unknown) {
+        const set = listeners.get(event)
+        if (!set) return
+        for (const listener of [...set]) listener({ data })
+      },
+    },
+  }
+}
+
+const SESSION_ID = 'test-session-123'
+const META = {
+  cwd: '/test/project',
+  projectName: 'test-project',
+}
+
+afterAll(() => {
+  rmSync(dirname(STATE_FILE), { recursive: true, force: true })
+})
+
+describe('SessionStore', () => {
+  const testLockFile = `${STATE_FILE}.lock`
+
+  beforeEach(async () => {
+    try {
+      unlinkSync(testLockFile)
+    } catch {
+      // ignore
+    }
+    await updateState(() => ({ version: 2, sessions: {} }))
+  })
+
+  afterEach(() => {
+    try {
+      unlinkSync(testLockFile)
+    } catch {
+      // ignore
+    }
+  })
+
+  it('creates instance and registers event listeners', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+    const emitSpy = vi.spyOn(stateTracker.events, 'on')
+    const piOnSpy = vi.spyOn(pi, 'on')
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    expect(emitSpy).toHaveBeenCalledTimes(4)
+    expect(emitSpy).toHaveBeenCalledWith('running', expect.any(Function))
+    expect(emitSpy).toHaveBeenCalledWith('idle', expect.any(Function))
+    expect(emitSpy).toHaveBeenCalledWith('tool', expect.any(Function))
+    expect(emitSpy).toHaveBeenCalledWith('event', expect.any(Function))
+    expect(piOnSpy).toHaveBeenCalledWith('session_start', expect.any(Function))
+  })
+
+  it('handles session_start event without errors', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    expect(() => {
+      pi.emitSessionStart({
+        cwd: META.cwd,
+        sessionManager: { getSessionId: () => SESSION_ID },
+      })
+    }).not.toThrow()
+  })
+
+  it('handles running event without errors', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
+    })
+
+    expect(() => {
+      stateTracker.events.emit('running')
+    }).not.toThrow()
+  })
+
+  it('handles idle event without errors', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
+    })
+
+    expect(() => {
+      stateTracker.events.emit('idle')
+    }).not.toThrow()
+  })
+
+  it('ignores running event when session not started', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    expect(() => {
+      stateTracker.events.emit('running')
+    }).not.toThrow()
+  })
+
+  it('ignores idle event when session not started', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    expect(() => {
+      stateTracker.events.emit('idle')
+    }).not.toThrow()
+  })
+
+  it('writes running and idle states to state.json', async () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(() => {})
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
+    })
+    await new Promise((resolve) => setTimeout(resolve, 10))
+
+    stateTracker.events.emit('running')
+    await new Promise((resolve) => setTimeout(resolve, 10))
+
+    let record = readState().sessions[String(process.pid)]
+    expect(record?.state).toBe('running')
+
+    stateTracker.events.emit('idle')
+    await new Promise((resolve) => setTimeout(resolve, 10))
+
+    record = readState().sessions[String(process.pid)]
+    expect(record?.state).toBe('idle')
+  })
+
+  it('stops without errors after session started', () => {
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(vi.fn())
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
+    })
+
+    expect(() => {
+      store.stop()
+    }).not.toThrow()
+  })
+
+  it('clears runningSince on idle transition without accumulating duration', async () => {
+    await updateState(() => ({ version: 2, sessions: {} }))
+    const now = Date.now()
+    const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(now)
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(() => {})
+
+    pi.emitSessionStart({
+      cwd: META.cwd,
+      sessionManager: { getSessionId: () => SESSION_ID },
+    })
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    stateTracker.events.emit('running')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    nowSpy.mockReturnValue(now + 5000)
+    stateTracker.events.emit('idle')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    const record = readState().sessions[String(process.pid)]
+    expect(record).not.toHaveProperty('runningTime')
+    expect(record?.startedRunningAt).toBeUndefined()
+    nowSpy.mockRestore()
+  })
+
+  it('does not update state on tool emission outside notifyTools', async () => {
+    await updateState(() => ({ version: 2, sessions: {} }))
+    const pi = makeFakePi()
+    const jobTracker = {
+      hasActiveJobs: false,
+      onEnd: () => () => {},
+    } as unknown as JobTracker
+    const tracker = new StateTracker(
+      pi as unknown as ExtensionAPI,
+      jobTracker,
+      {
+        notifyTools: new Set(['read']),
+        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))
+
+    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('idle')
+  })
+
+  it('updates state immediately on event emission', async () => {
+    await updateState(() => ({ version: 2, sessions: {} }))
+    const pi = makeFakePi()
+    const jobTracker = {
+      hasActiveJobs: false,
+      onEnd: () => () => {},
+    } as unknown as JobTracker
+    const tracker = new StateTracker(
+      pi as unknown as ExtensionAPI,
+      jobTracker,
+      {
+        notifyTools: new Set(['bash']),
+        events: { 'permissions:ui_prompt': 'msg' },
+      } 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.emitEvent('permissions:ui_prompt', {})
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    const record = readState().sessions[String(process.pid)]
+    expect(record?.state).toBe('event:permissions:ui_prompt')
+  })
+
+  it('ignores tool and event emissions before session_start', async () => {
+    await updateState(() => ({ version: 2, sessions: {} }))
+    const pi = makeFakePi()
+    const stateTracker = makeFakeStateTracker()
+    const store = new SessionStore(
+      pi as unknown as ExtensionAPI,
+      stateTracker as unknown as StateTracker,
+    )
+    store.register(() => {})
+
+    stateTracker.events.emit('tool', 'grep')
+    stateTracker.events.emit('event', 'permissions:ui_prompt')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    expect(readState().sessions).toEqual({})
+  })
+})