@raidou/pi-notify 0.3.1 → 0.5.0

package/src/shared/registrar.test.ts

@@ -0,0 +1,137 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Registrar } from './registrar.js'
+import type { NotifyAction, Unsubscribe } from './types.js'
+
+type Listener = (...args: unknown[]) => void
+type EventsListener = (payload: unknown) => void
+
+interface FakePi {
+  listeners: Map<string, Set<Listener>>
+  eventListeners: Map<string, Set<EventsListener>>
+  on(event: string, listener: Listener): void
+  events: { on(event: string, listener: EventsListener): Unsubscribe }
+  emit(event: string, ...args: unknown[]): void
+  emitEvent(event: string, payload: unknown): void
+}
+
+function makeFakePi(): FakePi {
+  const listeners = new Map<string, Set<Listener>>()
+  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)
+    },
+  }
+  return pi
+}
+
+class TrackingRegistrar extends Registrar {
+  setupCalls = 0
+  notifyUsed: NotifyAction | undefined
+  stopCalls = 0
+
+  protected override setup(notify: NotifyAction): void {
+    this.setupCalls += 1
+    this.notifyUsed = notify
+    const unsub: Unsubscribe = () => {}
+    this.unsubscribes.push(unsub)
+    this.unsubscribes.push(unsub)
+  }
+
+  override stop(): void {
+    super.stop()
+    this.stopCalls += 1
+  }
+
+  get isRegistered() {
+    return this.registered
+  }
+  get unsubscribesCount() {
+    return this.unsubscribes.length
+  }
+}
+
+describe('Registrar', () => {
+  it('runs setup once and is idempotent', () => {
+    const pi = makeFakePi()
+    const reg = new TrackingRegistrar(pi as unknown as ExtensionAPI)
+    const notify = vi.fn() as unknown as NotifyAction
+    reg.register(notify)
+    reg.register(notify)
+    expect(reg.setupCalls).toBe(1)
+    expect(reg.notifyUsed).toBe(notify)
+  })
+
+  it('passes notify to setup', () => {
+    const pi = makeFakePi()
+    const reg = new TrackingRegistrar(pi as unknown as ExtensionAPI)
+    const notify = vi.fn() as unknown as NotifyAction
+    reg.register(notify)
+    expect(reg.notifyUsed).toBe(notify)
+  })
+
+  it('triggers stop on session_shutdown', () => {
+    const pi = makeFakePi()
+    const reg = new TrackingRegistrar(pi as unknown as ExtensionAPI)
+    const notify = vi.fn() as unknown as NotifyAction
+    reg.register(notify)
+    expect(reg.stopCalls).toBe(0)
+    pi.emit('session_shutdown')
+    expect(reg.stopCalls).toBe(1)
+    expect(reg.isRegistered).toBe(false)
+  })
+
+  it('clears unsubscribes on stop', () => {
+    const pi = makeFakePi()
+    const reg = new TrackingRegistrar(pi as unknown as ExtensionAPI)
+    const notify = vi.fn() as unknown as NotifyAction
+    reg.register(notify)
+    expect(reg.unsubscribesCount).toBe(2)
+    reg.stop()
+    expect(reg.unsubscribesCount).toBe(0)
+    expect(reg.isRegistered).toBe(false)
+  })
+
+  it('re-registers after stop', () => {
+    const pi = makeFakePi()
+    const reg = new TrackingRegistrar(pi as unknown as ExtensionAPI)
+    const notify = vi.fn() as unknown as NotifyAction
+    reg.register(notify)
+    pi.emit('session_shutdown')
+    expect(reg.setupCalls).toBe(1)
+    reg.register(notify)
+    expect(reg.setupCalls).toBe(2)
+  })
+})

package/src/shared/registrar.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { NotifyAction, Unsubscribe } from './types.js'
+
+export abstract class Registrar {
+  protected readonly pi: ExtensionAPI
+  protected registered = false
+  protected unsubscribes: Unsubscribe[] = []
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi
+  }
+
+  register(notify: NotifyAction): void {
+    if (this.registered) return
+    this.registered = true
+    this.setup(notify)
+    this.pi.on('session_shutdown', () => {
+      this.stop()
+    })
+  }
+
+  protected abstract setup(notify: NotifyAction): void
+
+  stop(): void {
+    for (const unsubscribe of this.unsubscribes) unsubscribe()
+    this.unsubscribes = []
+    this.registered = false
+  }
+}

package/src/{types.ts → shared/types.ts}

@@ -1,3 +1,7 @@
 export type Unsubscribe = () => void
 
 export type NotifyAction = (body: string) => void
+
+export interface Registerable {
+  register(notify: NotifyAction): void
+}

package/src/state-tracker.test.ts

@@ -0,0 +1,360 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { JobTracker } from './jobs.js'
+import { PI_NOTIFY_EVENT, StateTracker } from './state-tracker.js'
+
+type EventsListener = (payload?: unknown) => void
+
+interface FakePi {
+  listeners: Map<string, Set<(payload?: unknown) => void>>
+  eventListeners: Map<string, Set<EventsListener>>
+  on(event: string, listener: (payload?: unknown) => void): void
+  events: { on(event: string, listener: EventsListener): () => void }
+  emit(event: string, payload?: unknown): void
+  emitEvent(event: string, payload?: unknown): void
+}
+
+function makeFakePi(): FakePi {
+  const listeners = new Map<string, Set<(payload?: unknown) => void>>()
+  const eventListeners = new Map<string, Set<EventsListener>>()
+  return {
+    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, payload) {
+      const set = listeners.get(event)
+      if (!set) return
+      for (const listener of [...set]) listener(payload)
+    },
+    emitEvent(event, payload) {
+      const set = eventListeners.get(event)
+      if (!set) return
+      for (const listener of [...set]) listener(payload)
+    },
+  }
+}
+
+function makeFakeJobTracker(): JobTracker {
+  return {
+    hasActiveJobs: false,
+    onEnd: () => () => {},
+  } as unknown as JobTracker
+}
+
+async function flush(): Promise<void> {
+  for (let i = 0; i < 5; i++) await Promise.resolve()
+}
+
+const BASE_CONFIG: ResolvedNotifyConfig = {
+  enabled: true,
+  notifyTools: new Set(['bash', 'read']),
+  events: {
+    'permissions:ui_prompt': 'msg',
+    'disabled:channel': false,
+  },
+  finished: true,
+  onlyNotifyWhenUnfocused: true,
+  unfocusedActivityThresholdMs: 0,
+  tmuxSymbol: '',
+} as unknown as ResolvedNotifyConfig
+
+function makeTracker(
+  pi: FakePi,
+  config: ResolvedNotifyConfig = BASE_CONFIG,
+): {
+  tracker: StateTracker
+  states: string[]
+  bodies: string[]
+} {
+  const states: string[] = []
+  const bodies: string[] = []
+  const tracker = new StateTracker(
+    pi as unknown as ExtensionAPI,
+    makeFakeJobTracker(),
+    config,
+  )
+  tracker.register((body) => bodies.push(body))
+  tracker.events.on('running', () => {
+    states.push('running')
+  })
+  tracker.events.on('idle', () => {
+    states.push('idle')
+  })
+  return { tracker, states, bodies }
+}
+
+describe('StateTracker', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('emits running on turn_start', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+
+    await flush()
+
+    expect(states).toEqual(['running'])
+  })
+
+  it('emits idle after the idle timeout following agent_settled', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+
+    await flush()
+
+    expect(states).toEqual(['running', 'idle'])
+  })
+
+  it('does not emit running repeatedly while already running', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emit('message_start')
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'read',
+    })
+    pi.emit('turn_start')
+
+    await flush()
+
+    expect(states).toEqual(['running'])
+  })
+
+  it('emits tool only for tools in notifyTools', async () => {
+    const pi = makeFakePi()
+    const { tracker } = makeTracker(pi)
+    const tools: string[] = []
+    tracker.events.on('tool', (event) => {
+      tools.push(event.data)
+    })
+
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'bash',
+    })
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't2',
+      toolName: 'grep',
+    })
+
+    await flush()
+
+    expect(tools).toEqual(['bash'])
+  })
+
+  it('emits event for configured channels and not for disabled ones', async () => {
+    const pi = makeFakePi()
+    const { tracker } = makeTracker(pi)
+    const events: string[] = []
+    tracker.events.on('event', (event) => {
+      events.push(event.data)
+    })
+
+    pi.emitEvent('permissions:ui_prompt', {})
+    pi.emitEvent('disabled:channel', {})
+
+    await flush()
+
+    expect(events).toEqual(['permissions:ui_prompt'])
+  })
+
+  it('unsubscribes from channel events on stop', async () => {
+    const pi = makeFakePi()
+    const { tracker } = makeTracker(pi)
+    const events: string[] = []
+    tracker.events.on('event', (event) => {
+      events.push(event.data)
+    })
+
+    tracker.stop()
+    pi.emitEvent('permissions:ui_prompt', {})
+
+    await flush()
+
+    expect(events).toEqual([])
+  })
+
+  it('emits running again after becoming idle', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+    pi.emit('turn_start')
+
+    await flush()
+
+    expect(states).toEqual(['running', 'idle', 'running'])
+  })
+
+  it('notifies with the configured message when a custom event fires', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emitEvent('permissions:ui_prompt', {})
+
+    expect(bodies).toEqual(['msg'])
+  })
+
+  it('does not notify for events disabled with false', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emitEvent('disabled:channel', {})
+
+    expect(bodies).toEqual([])
+  })
+
+  it('does not notify for events disabled with an empty string', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi, {
+      ...BASE_CONFIG,
+      events: { 'my:custom:event': '' },
+    })
+
+    pi.emitEvent('my:custom:event', {})
+
+    expect(bodies).toEqual([])
+  })
+
+  it('notifies from the custom channel', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emitEvent(PI_NOTIFY_EVENT, 'custom payload')
+
+    expect(bodies).toEqual(['custom payload'])
+  })
+
+  it('notifies for tools in notifyTools', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'read',
+    })
+
+    expect(bodies).toEqual(['Tool call: read'])
+  })
+
+  it('does not notify for tools not in notifyTools', () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't1',
+      toolName: 'grep',
+    })
+
+    expect(bodies).toEqual([])
+  })
+
+  it('notifies Idle on idle when there was activity', async () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+
+    await flush()
+
+    expect(bodies).toEqual(['Idle'])
+  })
+
+  it('does not notify Idle on idle without activity', async () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi)
+
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+
+    await flush()
+
+    expect(bodies).toEqual([])
+  })
+
+  it('does not notify Idle when finished is disabled', async () => {
+    const pi = makeFakePi()
+    const { bodies } = makeTracker(pi, {
+      ...BASE_CONFIG,
+      finished: false,
+    })
+
+    pi.emit('turn_start')
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+
+    await flush()
+
+    expect(bodies).toEqual([])
+  })
+
+  it('resets the idle timer on activity', async () => {
+    const pi = makeFakePi()
+    const { states } = makeTracker(pi)
+
+    pi.emit('turn_start')
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(9000)
+    pi.emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 't2',
+      toolName: 'bash',
+    })
+    vi.advanceTimersByTime(9000)
+
+    await flush()
+
+    expect(states).toEqual(['running'])
+
+    pi.emit('agent_settled')
+    vi.advanceTimersByTime(10000)
+
+    await flush()
+
+    expect(states).toEqual(['running', 'idle'])
+  })
+})

package/src/state-tracker.ts

@@ -0,0 +1,123 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import Emittery from 'emittery'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { JobTracker } from './jobs.js'
+import { Registrar } from './shared/registrar.js'
+import type { NotifyAction } from './shared/types.js'
+
+export const PI_NOTIFY_EVENT = 'pi-notify:notify'
+
+const IDLE_TIMEOUT_MS = 10000
+
+export class StateTracker extends Registrar {
+  readonly events = new Emittery<{
+    running: never
+    idle: never
+    tool: string
+    event: string
+  }>()
+
+  private readonly jobTracker: JobTracker
+  private readonly config: ResolvedNotifyConfig
+  private idleTimer: NodeJS.Timeout | null = null
+  private running = false
+  private hasActivity = false
+  private notify: NotifyAction = () => {}
+
+  constructor(
+    pi: ExtensionAPI,
+    jobTracker: JobTracker,
+    config: ResolvedNotifyConfig,
+  ) {
+    super(pi)
+    this.jobTracker = jobTracker
+    this.config = config
+  }
+
+  private startIdleTimer(): void {
+    if (this.jobTracker.hasActiveJobs) return
+    this.clearIdleTimer()
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null
+      this.running = false
+      void this.events.emit('idle')
+      if (this.hasActivity && this.config.finished) {
+        this.notify('Idle')
+      }
+    }, IDLE_TIMEOUT_MS)
+  }
+
+  private clearIdleTimer(): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer)
+      this.idleTimer = null
+    }
+  }
+
+  private markRunning(): void {
+    if (this.running) return
+    this.running = true
+    void this.events.emit('running')
+  }
+
+  private setupPiEvents() {
+    for (const [channel, message] of Object.entries(this.config.events)) {
+      if (typeof message !== 'string' || message === '') continue
+      const unsubscribe = this.pi.events.on(channel, () => {
+        this.notify(message)
+        void this.events.emit('event', channel)
+      })
+      this.unsubscribes.push(unsubscribe)
+    }
+
+    const customEventUnsub = this.pi.events.on(PI_NOTIFY_EVENT, (payload) => {
+      this.notify(String(payload))
+      void this.events.emit('event', PI_NOTIFY_EVENT)
+    })
+    this.unsubscribes.push(customEventUnsub)
+  }
+
+  private setupToolCall() {
+    this.pi.on('tool_call', (event) => {
+      if (this.config.notifyTools.has(event.toolName)) {
+        this.notify(`Tool call: ${event.toolName}`)
+        void this.events.emit('tool', event.toolName)
+      }
+      this.clearIdleTimer()
+    })
+  }
+
+  protected override setup(notify: NotifyAction): void {
+    this.notify = notify
+
+    this.setupPiEvents()
+    this.setupToolCall()
+
+    this.pi.on('turn_start', () => {
+      this.hasActivity = true
+      this.markRunning()
+      this.clearIdleTimer()
+    })
+
+    this.pi.on('message_start', () => {
+      this.clearIdleTimer()
+    })
+
+    this.pi.on('agent_settled', () => {
+      this.startIdleTimer()
+    })
+
+    this.unsubscribes.push(
+      this.jobTracker.onEnd(() => {
+        this.startIdleTimer()
+      }),
+    )
+  }
+
+  override stop(): void {
+    super.stop()
+    this.clearIdleTimer()
+    this.hasActivity = false
+  }
+}

package/src/states.ts

@@ -1,9 +1,11 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
 export class SessionState {
+  private readonly pi: ExtensionAPI
   public hasUI = false
 
-  constructor(private readonly pi: ExtensionAPI) {
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi
     this.register()
   }