@raidou/pi-pm-subagents 0.1.1

package/src/prompts/roles.ts

@@ -0,0 +1,119 @@
+import { readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { CONFIG_DIR_NAME, getAgentDir } from '@earendil-works/pi-coding-agent'
+
+import { loadMarkdown, type PromptDefinition } from '../utils/markdown.js'
+import { composeTools } from '../utils/tools.js'
+
+const DEFAULT_ROLE = 'worker'
+
+const roles: Map<string, PromptDefinition> = new Map()
+
+export async function loadMarkdownRolesFromDir(
+  dir: string,
+): Promise<Map<string, PromptDefinition>> {
+  const loadedRoles = new Map<string, PromptDefinition>()
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+
+    await Promise.all(
+      entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map(async (entry) => {
+          const roleName = entry.name.slice(0, -'.md'.length)
+          const definition = await loadMarkdown(join(dir, entry.name))
+          if (definition) {
+            loadedRoles.set(roleName, definition)
+          }
+        }),
+    )
+  } catch {
+    // Ignore unreadable directories silently
+  }
+
+  return loadedRoles
+}
+
+async function loadBuiltins(): Promise<Map<string, PromptDefinition>> {
+  return new Map<string, PromptDefinition>([
+    [DEFAULT_ROLE, { fm: {}, systemPrompt: '' }],
+  ])
+}
+
+export interface LoadRolesOptions {
+  /** Skip roles bundled with the plugin (agents/ directory in the package root). */
+  skipPluginAgents?: boolean
+}
+
+export async function loadRoles(
+  cwd: string,
+  options: LoadRolesOptions = {},
+): Promise<void> {
+  roles.clear()
+  const addRoles = (newRoles: Map<string, PromptDefinition>) => {
+    for (const [name, role] of newRoles) {
+      roles.set(name, role)
+    }
+  }
+
+  addRoles(await loadBuiltins())
+  if (!options.skipPluginAgents) {
+    // Bundled agents live in the package root, next to src/.
+    const here = dirname(fileURLToPath(import.meta.url))
+    addRoles(await loadMarkdownRolesFromDir(join(here, '../..', 'agents')))
+  }
+  addRoles(await loadMarkdownRolesFromDir(join(getAgentDir(), 'agents')))
+  addRoles(await loadMarkdownRolesFromDir(join(cwd, CONFIG_DIR_NAME, 'agents')))
+}
+
+export function resolveRole(name: string = DEFAULT_ROLE): PromptDefinition {
+  if (roles.size === 0) {
+    throw new Error('Roles not loaded. Call loadRoles() first.')
+  }
+  const role = roles.get(name)
+  if (!role) {
+    throw new Error(
+      `Role "${name}" not found. Available roles: ${[...roles.keys()].join(', ')}`,
+    )
+  }
+  return role
+}
+
+export function listRoles(): string[] {
+  return [...roles.keys()]
+}
+
+function formatRoleEntry(
+  [name, role]: [string, PromptDefinition],
+  baseTools: readonly string[],
+): string {
+  const parts: string[] = []
+  if (role.fm.description) {
+    parts.push(role.fm.description)
+  }
+  const effective = composeTools(baseTools, {
+    tools: role.fm.tools,
+    extraTools: role.fm.extraTools,
+    removeTools: role.fm.removeTools,
+  })
+  if (effective.length > 0) parts.push(`tools: ${effective.join(', ')}`)
+  if (parts.length > 0) return `  - ${name}: ${parts.join('; ')}`
+  return `  - ${name}`
+}
+
+export function rolesDescription(baseTools: readonly string[] = []): string {
+  if (roles.size === 0) {
+    return ''
+  }
+
+  return [...roles.entries()]
+    .map((e) => formatRoleEntry(e, baseTools))
+    .join('\n')
+}
+
+export function clearRoles(): void {
+  roles.clear()
+}

package/src/subagent/activity.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { ActivityReporter, MAX_ACTIVITY_BYTES } from './activity.js'
+import type { LiveSubagent } from './manager.js'
+
+const makeSubagent = (id: number, messages: unknown[]): LiveSubagent =>
+  ({
+    id,
+    title: `task-${id}`,
+    text: `task-${id}`,
+    status: 'running',
+    startedAt: Date.now() - 1000,
+    session: { messages: messages as never },
+    followUpCount: 0,
+    activeTools: [],
+  }) as unknown as LiveSubagent
+
+const assistant = (text: string) =>
+  ({
+    role: 'assistant',
+    content: [{ type: 'text', text }],
+    timestamp: Date.now(),
+  }) as unknown as never
+
+describe('ActivityReporter.formatActivityReport', () => {
+  it('returns last assistant message text', () => {
+    const messages = [assistant('Working on it')]
+    const subagent = makeSubagent(1, messages)
+    const report = ActivityReporter.formatActivityReport(subagent)
+    expect(report).toBe('Working on it')
+  })
+
+  it('returns fallback for subagent with no valid last message', () => {
+    const subagent = makeSubagent(1, [])
+    const report = ActivityReporter.formatActivityReport(subagent)
+    expect(report).toBe('(Just started, waiting for first message)')
+  })
+
+  it('truncates long message text to MAX_ACTIVITY_BYTES', () => {
+    const longText = 'a'.repeat(MAX_ACTIVITY_BYTES * 2)
+    const messages = [assistant(longText)]
+    const subagent = makeSubagent(1, messages)
+    const report = ActivityReporter.formatActivityReport(subagent)
+    expect(report).toContain('[Output truncated')
+  })
+})
+
+describe('ActivityReporter integration', () => {
+  it('starts and stops without errors', () => {
+    vi.useFakeTimers()
+    let reportCount = 0
+
+    const activityReporter = new ActivityReporter({
+      list: () => [],
+      onActivity: () => {
+        reportCount += 1
+      },
+    })
+
+    activityReporter.start()
+    activityReporter.stop()
+    vi.advanceTimersByTime(5 * 60 * 1000)
+
+    expect(reportCount).toBe(0)
+  })
+
+  it('does not call onActivity when no running subagents', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+
+    const activityReporter = new ActivityReporter({
+      list: () =>
+        [
+          { id: 1, status: 'done', title: 'Task 1' },
+          { id: 2, status: 'failed', title: 'Task 2' },
+        ] as LiveSubagent[],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 100,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(100)
+
+    expect(reports).toHaveLength(0)
+  })
+
+  it('calls onActivity with subagent and report when running subagents exist', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+    const subagent = makeSubagent(1, [assistant('Doing task')])
+    subagent.startedAt = Date.now() - 60000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [subagent],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 100,
+      notificationIntervalMs: 1000,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(100)
+
+    expect(reports).toHaveLength(1)
+    expect(reports[0]?.subagent.id).toBe(1)
+    expect(reports[0]?.report).toBe('Doing task')
+  })
+
+  it('respects custom checkIntervalMs', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+    const subagent = makeSubagent(1, [])
+    subagent.startedAt = Date.now() - 60000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [subagent],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 200,
+      notificationIntervalMs: 1000,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(199)
+    expect(reports).toHaveLength(0)
+
+    vi.advanceTimersByTime(1)
+    expect(reports).toHaveLength(1)
+  })
+
+  it('does not leak timers on multiple starts', () => {
+    vi.useFakeTimers()
+    let reportCount = 0
+    const subagent = makeSubagent(1, [])
+    subagent.startedAt = Date.now() - 60000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [subagent],
+      onActivity: () => {
+        reportCount += 1
+      },
+      checkIntervalMs: 50,
+      notificationIntervalMs: 100,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(50)
+    expect(reportCount).toBe(1)
+
+    vi.advanceTimersByTime(50)
+    expect(reportCount).toBe(1)
+
+    activityReporter.start()
+    vi.advanceTimersByTime(50)
+    expect(reportCount).toBe(2)
+  })
+})
+
+describe('ActivityReporter per-subagent throttling', () => {
+  it('throttles notifications per subagent based on notificationIntervalMs', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+    const subagent = makeSubagent(1, [])
+    subagent.startedAt = Date.now() - 60000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [subagent],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 100,
+      notificationIntervalMs: 200,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(1)
+
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(1)
+
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(2)
+  })
+
+  it('tracks per-subagent throttling independently', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+    const s1 = makeSubagent(1, [])
+    s1.startedAt = Date.now() - 60000
+    const s2 = makeSubagent(2, [])
+    s2.startedAt = Date.now() - 60000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [s1, s2],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 100,
+      notificationIntervalMs: 200,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(2)
+
+    s1.status = 'done'
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(2)
+
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(3)
+    expect(reports[2]?.subagent.id).toBe(2)
+  })
+
+  it('does not send report when subagent is not due yet', () => {
+    vi.useFakeTimers()
+    const reports: { subagent: LiveSubagent; report: string }[] = []
+    const subagent = makeSubagent(1, [])
+    subagent.startedAt = Date.now() - 1000
+
+    const activityReporter = new ActivityReporter({
+      list: () => [subagent],
+      onActivity: (subagent, report) => reports.push({ subagent, report }),
+      checkIntervalMs: 100,
+      notificationIntervalMs: 1500,
+    })
+
+    activityReporter.start()
+    vi.advanceTimersByTime(100)
+    expect(reports).toHaveLength(0)
+
+    vi.advanceTimersByTime(400)
+    expect(reports).toHaveLength(1)
+  })
+})

package/src/subagent/activity.ts

@@ -0,0 +1,60 @@
+import { lastMessageText } from '../utils/messages.js'
+import type { LiveSubagent } from './manager.js'
+
+const CHECK_INTERVAL_MS = 60 * 1000
+const NOTIFICATION_INTERVAL_MS = 5 * 60 * 1000
+export const MAX_ACTIVITY_BYTES = 1000
+
+export class ActivityReporter {
+  private timer: ReturnType<typeof setInterval> | undefined
+  private lastSentAt = new Map<number, number>()
+
+  constructor(
+    private readonly options: {
+      list: () => readonly LiveSubagent[]
+      onActivity: (subagent: LiveSubagent, report: string) => void
+      checkIntervalMs?: number
+      notificationIntervalMs?: number
+    },
+  ) {}
+
+  start(): void {
+    this.stop()
+    const intervalMs = this.options.checkIntervalMs ?? CHECK_INTERVAL_MS
+    this.timer = setInterval(() => {
+      this.tick()
+    }, intervalMs)
+  }
+
+  stop(): void {
+    if (this.timer !== undefined) {
+      clearInterval(this.timer)
+      this.timer = undefined
+    }
+  }
+
+  private tick(): void {
+    const now = Date.now()
+    const notificationMs =
+      this.options.notificationIntervalMs ?? NOTIFICATION_INTERVAL_MS
+    const runningList = this.options
+      .list()
+      .filter((w) => w.status === 'running')
+    for (const subagent of runningList) {
+      const last = this.lastSentAt.get(subagent.id) ?? subagent.startedAt
+      if (now - last < notificationMs) continue
+      this.options.onActivity(
+        subagent,
+        ActivityReporter.formatActivityReport(subagent),
+      )
+      this.lastSentAt.set(subagent.id, now)
+    }
+  }
+
+  static formatActivityReport(subagent: LiveSubagent): string {
+    return (
+      lastMessageText(subagent.session.messages, MAX_ACTIVITY_BYTES) ??
+      '(Just started, waiting for first message)'
+    )
+  }
+}

package/src/subagent/batcher.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { MessageBatcher } from './batcher.js'
+import type { LiveSubagent } from './manager.js'
+
+const makeSubagent = (
+  id: number,
+  title: string,
+  status: string,
+): LiveSubagent =>
+  ({
+    id,
+    title,
+    text: title,
+    status: status as never,
+    startedAt: Date.now() - 5000,
+    session: { messages: [] as never },
+    followUpCount: 0,
+    activeTools: [],
+  }) as unknown as LiveSubagent
+
+describe('MessageBatcher', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('flushes after batching window', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+    const subagent = makeSubagent(1, 'task-1', 'done')
+    subagent.contextUsage = {
+      tokens: 60000,
+      contextWindow: 200000,
+      percent: 30,
+    }
+
+    batcher.add(subagent, 'done', 'Task completed')
+    expect(batcher.pending.length).toBe(1)
+
+    vi.advanceTimersByTime(99)
+    expect(flushed).toHaveLength(0)
+
+    vi.advanceTimersByTime(1)
+    expect(flushed).toHaveLength(1)
+    const firstFlush = flushed[0]
+    expect(firstFlush?.[0]).toContain('done #1')
+    expect(firstFlush?.[0]).toContain('60k/200k')
+    expect(firstFlush?.[0]).toContain('<type>done</type>')
+    expect(firstFlush?.[0]).toContain('<message>Task completed</message>')
+    expect(batcher.pending).toEqual([])
+  })
+
+  it('combines multiple items in the same window', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent1 = makeSubagent(1, 'task-1', 'done')
+    const subagent2 = makeSubagent(2, 'task-2', 'failed')
+
+    batcher.add(subagent1, 'done', 'Task 1 completed')
+    vi.advanceTimersByTime(50)
+    batcher.add(subagent2, 'failed', 'Task 2 failed')
+    vi.advanceTimersByTime(100)
+
+    expect(flushed).toHaveLength(1)
+    const firstFlush = flushed[0]
+    expect(firstFlush?.length).toBe(2)
+    expect(firstFlush?.[0]).toContain('done #1')
+    expect(firstFlush?.[0]).toContain('Task 1 completed')
+    expect(firstFlush?.[1]).toContain('failed #2')
+    expect(firstFlush?.[1]).toContain('Task 2 failed')
+    expect(batcher.pending).toEqual([])
+  })
+
+  it('clears pending items after flushNow', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent1 = makeSubagent(1, 'task-1', 'done')
+    batcher.add(subagent1, 'done', 'Task 1 completed')
+    batcher.flushNow()
+    expect(batcher.pending).toEqual([])
+
+    const subagent2 = makeSubagent(2, 'task-2', 'done')
+    batcher.add(subagent2, 'done', 'Task 2 completed')
+    batcher.flushNow()
+
+    expect(flushed).toHaveLength(2)
+    expect(flushed[0]?.[0]).toContain('done #1')
+    expect(flushed[1]?.[0]).toContain('done #2')
+    expect(batcher.pending).toEqual([])
+  })
+
+  it('flushes immediately when requested via flushNow', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent = makeSubagent(1, 'task-1', 'done')
+    batcher.add(subagent, 'done', 'Task completed')
+    batcher.flushNow()
+
+    expect(flushed).toHaveLength(1)
+    const firstFlush = flushed[0]
+    expect(firstFlush?.[0]).toContain('done #1')
+    vi.advanceTimersByTime(100)
+    expect(flushed).toHaveLength(1)
+  })
+
+  it('clears pending items without flushing via clear', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent = makeSubagent(1, 'task-1', 'done')
+    batcher.add(subagent, 'done', 'Task completed')
+    batcher.clear()
+    vi.advanceTimersByTime(100)
+
+    expect(flushed).toHaveLength(0)
+    expect(batcher.pending).toEqual([])
+  })
+
+  it('adds items in order and flushes them together', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent1 = makeSubagent(1, 'task-1', 'done')
+    const subagent2 = makeSubagent(2, 'task-2', 'running')
+
+    batcher.add(subagent1, 'done', 'Subagent #1 work done.')
+    batcher.add(subagent2, 'activity', 'Subagent activity update')
+    vi.advanceTimersByTime(100)
+
+    expect(flushed).toHaveLength(1)
+    const firstFlush = flushed[0]
+    expect(firstFlush?.length).toBe(2)
+    expect(firstFlush?.[0]).toContain('done #1')
+    expect(firstFlush?.[0]).toContain('Subagent #1 work done.')
+    expect(firstFlush?.[1]).toContain('running #2')
+    expect(firstFlush?.[1]).toContain('Subagent activity update')
+  })
+
+  it('resets timer on each add', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent1 = makeSubagent(1, 'task-1', 'done')
+    const subagent2 = makeSubagent(2, 'task-2', 'running')
+
+    batcher.add(subagent1, 'done', 'First message')
+    vi.advanceTimersByTime(50)
+    expect(flushed).toHaveLength(0)
+
+    batcher.add(subagent2, 'activity', 'Second message')
+    vi.advanceTimersByTime(50)
+    expect(flushed).toHaveLength(0)
+
+    vi.advanceTimersByTime(50)
+    expect(flushed).toHaveLength(1)
+
+    const firstFlush = flushed[0]
+    expect(firstFlush?.length).toBe(2)
+    expect(firstFlush?.[0]).toContain('done #1')
+    expect(firstFlush?.[0]).toContain('First message')
+    expect(firstFlush?.[1]).toContain('running #2')
+    expect(firstFlush?.[1]).toContain('Second message')
+  })
+
+  it('clears old timer and starts new one when adding item', () => {
+    vi.useFakeTimers()
+    const flushed: string[][] = []
+    const batcher = new MessageBatcher((items) => flushed.push(items), 100)
+
+    const subagent = makeSubagent(1, 'task-1', 'done')
+
+    batcher.add(subagent, 'done', 'Message 1')
+    vi.advanceTimersByTime(80)
+    expect(flushed).toHaveLength(0)
+
+    batcher.add(subagent, 'activity', 'Message 2')
+    vi.advanceTimersByTime(80)
+    expect(flushed).toHaveLength(0)
+
+    vi.advanceTimersByTime(20)
+    expect(flushed).toHaveLength(1)
+
+    const firstFlush = flushed[0]
+    expect(firstFlush?.length).toBe(2)
+    expect(firstFlush?.[0]).toContain('Message 1')
+    expect(firstFlush?.[1]).toContain('Message 2')
+  })
+})

package/src/subagent/batcher.ts

@@ -0,0 +1,51 @@
+import { formatSubagentSummary, type LiveSubagent } from './manager.js'
+
+export class MessageBatcher {
+  private items: string[] = []
+  private timer: ReturnType<typeof setTimeout> | undefined
+
+  constructor(
+    private readonly flush: (items: string[]) => void,
+    private readonly windowMs = 3000,
+  ) {}
+
+  get pending(): readonly string[] {
+    return [...this.items]
+  }
+
+  add(subagent: LiveSubagent, type: string, message: string): void {
+    const tagName = type === 'done' ? 'subagent-done' : 'subagent-notify'
+    const item = [
+      `<${tagName}>`,
+      `<type>${type}</type>`,
+      `<job>${formatSubagentSummary(subagent)}</job>`,
+      `<message>${message}</message>`,
+      `</${tagName}>`,
+    ].join('\n')
+    this.items.push(item)
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    this.timer = setTimeout(() => {
+      this.flushNow()
+    }, this.windowMs)
+  }
+
+  flushNow(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    if (this.items.length === 0) return
+
+    const items = this.items
+    this.items = []
+    this.flush(items)
+  }
+
+  clear(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    this.items = []
+  }
+}

package/src/subagent/consts.ts

@@ -0,0 +1 @@
+export const FOLLOW_SYMBOL = '⟳'