@raidou/pi-pm-subagents 0.1.1

package/src/bash-readonly.ts

@@ -0,0 +1,205 @@
+import {
+  type BashOperations,
+  createBashToolDefinition,
+  createLocalBashOperations,
+  defineTool,
+  type ExtensionAPI,
+} from '@earendil-works/pi-coding-agent'
+import { parse as parseShell } from 'shell-quote'
+
+import { registerOptionalTools } from './utils/tools.js'
+
+export type BashSafetyIssue =
+  { allowed: true } | { allowed: false; subCommand: string }
+
+const FORWARD_PREFIX = ['rtk'] as const
+
+const DESTRUCTIVE_BASH_PATTERNS = [
+  /^\s*(rm|rmdir|mv|cp|mkdir|touch|chmod|chown|tee|truncate|dd|shred)\b/i,
+  /(^|[^<])>(?!>)/,
+  />>/,
+  /^\s*(npm|yarn|pnpm|bun)\s+(install|uninstall|add|remove|update|ci|link|publish)\b/i,
+  /^\s*pip\s+(install|uninstall)\b/i,
+  /^\s*apt(-get)?\s+(install|remove|purge|update|upgrade)\b/i,
+  /^\s*brew\s+(install|uninstall|upgrade)\b/i,
+  /^\s*git\s+(add|commit|push|pull|merge|rebase|reset|checkout|cherry-pick|revert|tag|init|clone)\b/i,
+  /^\s*git\s+stash\s+(push|pop|apply|drop|clear|save|create|branch|store|import|export)\b/i,
+  /^\s*sudo\b/i,
+  /^\s*(kill|pkill|killall|reboot|shutdown)\b/i,
+  /^\s*(vim?|nano|emacs|code|subl)\b/i,
+] as const
+
+const BASH_READONLY_PATTERNS = [
+  /^\s*(cat|head|tail|less|more|grep|find|ls|cd|pwd|echo|printf|wc|sort|uniq|diff|file|stat|du|df|tree|which|whereis|type|env|printenv|uname|whoami|id|date|uptime|ps|free)\b/,
+  /^\s*git\s+(status|log|diff|show|branch|remote|ls-)/i,
+  /^\s*git\s+stash\s+(list|show)\b/i,
+  /^\s*(npm|yarn|pnpm)\s+(list|ls|view|info|outdated|audit)\b/i,
+  /^\s*(npm|yarn|pnpm)\s+(run\s+)?(test|test:.*)\b/i,
+  /^\s*(node|python|python3)\s+--version/i,
+  /^\s*curl\s/,
+  /^\s*jq\b/,
+  /^\s*sed\s+-n/i,
+  /^\s*awk\b/,
+  /^\s*rg\b/,
+  /^\s*fd\b/,
+  /^\s*bat\b/,
+  /^\s*eza\b/,
+] as const
+
+const HARMLESS_SUB_COMMAND = /^\s*export\s+[\w]+\s*=\s*\S+\s*$/
+
+const SUB_COMMAND_OPS = new Set(['|', '||', '|&', '&&', ';'])
+
+const isFd = (token: unknown, n: number): token is string => token === `${n}`
+
+const REDIRECT_OPS = new Set(['>', '>>', '<', '<>', '>&', '<&', '>|', '&>>'])
+
+type SubCommand = { tokens: string[]; hasStdoutRedirect: boolean }
+
+function splitShellSubCommands(command: string): SubCommand[] {
+  let parsed: ReturnType<typeof parseShell>
+  try {
+    parsed = parseShell(command)
+  } catch {
+    return []
+  }
+
+  const subCommands: SubCommand[] = []
+  let current: string[] = []
+  let hasStdoutRedirect = false
+
+  for (let i = 0; i < parsed.length; i++) {
+    const token = parsed[i]
+    const nextToken = parsed[i + 1]
+    const prevToken = i > 0 ? parsed[i - 1] : null
+
+    if (typeof token === 'object' && 'op' in token) {
+      const op = token.op as string
+      if (SUB_COMMAND_OPS.has(op)) {
+        subCommands.push({ tokens: current, hasStdoutRedirect })
+        current = []
+        hasStdoutRedirect = false
+      } else if (op === '>&' && isFd(prevToken, 2) && isFd(nextToken, 1)) {
+        const tokenAfterNext = parsed[i + 2]
+        const hasPipeAfter =
+          typeof tokenAfterNext === 'object' &&
+          'op' in tokenAfterNext &&
+          tokenAfterNext.op === '|'
+        if (!hasPipeAfter) hasStdoutRedirect = true
+      } else if (
+        (op === '>' || op === '>>' || op === '>|') &&
+        !isFd(prevToken, 1) &&
+        !isFd(prevToken, 2)
+      ) {
+        hasStdoutRedirect = true
+      }
+    } else if (typeof token === 'string') {
+      const isRedirectTarget =
+        prevToken &&
+        typeof prevToken === 'object' &&
+        'op' in prevToken &&
+        REDIRECT_OPS.has(prevToken.op as string)
+
+      const isRedirectFd =
+        /^\d+$/.test(token) &&
+        nextToken &&
+        typeof nextToken === 'object' &&
+        'op' in nextToken &&
+        REDIRECT_OPS.has(nextToken.op)
+
+      if (!isRedirectTarget && !isRedirectFd) {
+        current.push(token)
+      }
+    }
+  }
+  if (current.length > 0 || subCommands.length > 0)
+    subCommands.push({ tokens: current, hasStdoutRedirect })
+
+  return subCommands
+}
+
+function checkSubCommandSafety(
+  subCommand: SubCommand,
+): { ok: true } | { ok: false; subCommand: string } {
+  const text = subCommand.tokens.join(' ').trim()
+
+  if (HARMLESS_SUB_COMMAND.test(text)) return { ok: true }
+
+  let normalizedCommand = text
+  for (const prefix of FORWARD_PREFIX) {
+    const pattern = new RegExp(`^\\s*${prefix}\\s+`, 'i')
+    const match = normalizedCommand.match(pattern)
+    if (match) {
+      normalizedCommand = normalizedCommand.slice(match[0].length).trim()
+      break
+    }
+  }
+
+  if (subCommand.hasStdoutRedirect)
+    return { ok: false, subCommand: normalizedCommand }
+
+  const destructive = DESTRUCTIVE_BASH_PATTERNS.some((p) =>
+    p.test(normalizedCommand),
+  )
+  const readonly = BASH_READONLY_PATTERNS.some((p) => p.test(normalizedCommand))
+
+  if (destructive) return { ok: false, subCommand: normalizedCommand }
+  if (!readonly) return { ok: false, subCommand: normalizedCommand }
+  return { ok: true }
+}
+
+export function checkBashSafety(command: string): BashSafetyIssue {
+  const subCommands = splitShellSubCommands(command)
+  if (subCommands.length === 0) {
+    return { allowed: false, subCommand: command }
+  }
+
+  for (const subCommand of subCommands) {
+    if (subCommand.tokens.length === 0) {
+      return { allowed: false, subCommand: '(empty)' }
+    }
+    const result = checkSubCommandSafety(subCommand)
+    if (!result.ok) {
+      return { allowed: false, subCommand: result.subCommand }
+    }
+  }
+
+  return { allowed: true }
+}
+
+export function isBashReadonlyCommand(command: string): boolean {
+  return checkBashSafety(command).allowed
+}
+
+export const BASH_READONLY_TOOL_NAME = 'bash_readonly'
+
+export function setupBashReadonlyTool(pi: ExtensionAPI): void {
+  const localOps = createLocalBashOperations()
+  const safeOps: BashOperations = {
+    exec: async (command, cwd, options) => {
+      const safety = checkBashSafety(command)
+      if (!safety.allowed) {
+        throw new Error(
+          `${BASH_READONLY_TOOL_NAME}: not allowed: "${safety.subCommand}"`,
+        )
+      }
+      return localOps.exec(command, cwd, options)
+    },
+  }
+  const def = createBashToolDefinition(process.cwd(), { operations: safeOps })
+  registerOptionalTools(
+    pi,
+    [
+      defineTool({
+        ...def,
+        name: BASH_READONLY_TOOL_NAME,
+        label: 'Read-Only Bash',
+        description:
+          'Execute a bash command. Only commands classified as read-only are allowed; write operations are rejected. Use the regular bash tool outside of read-only modes.',
+        promptSnippet: undefined,
+        promptGuidelines: undefined,
+      }),
+    ],
+    false,
+  )
+}

package/src/coordinator/coordinator.test.ts

@@ -0,0 +1,28 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { describe, expect, it } from 'vitest'
+
+import { loadMarkdown } from '../utils/markdown.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(__dirname, '../..')
+
+describe('coordinator mode prompt', () => {
+  it('has correct removeTools in coordinator.md', async () => {
+    const coordinatorPath = join(
+      repoRoot,
+      'pm-subagents-prompts',
+      'coordinator.md',
+    )
+    const result = await loadMarkdown(coordinatorPath)
+    expect(result).toBeDefined()
+    expect(result?.fm.removeTools).toEqual([
+      'find',
+      'grep',
+      'bash',
+      'web_search',
+      'web_fetch',
+    ])
+  })
+})

package/src/coordinator/coordinator.ts

@@ -0,0 +1,275 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent'
+
+import { getPmSubagentsConfig } from '../models-config/models-config.js'
+import { formatSubagentModelLabel } from '../models-config/subagent-model-utils.js'
+import { applyModeFor, assertModeIdle, exitModeFor } from '../pm-mode.js'
+import { loadRoles } from '../prompts/roles.js'
+import { ActivityReporter } from '../subagent/activity.js'
+import { MessageBatcher } from '../subagent/batcher.js'
+import { SubagentManagerDemo } from '../subagent/demo.js'
+import { FleetList } from '../subagent/fleet.js'
+import {
+  type LiveSubagent,
+  SubagentManager,
+  type SubagentStatus,
+} from '../subagent/manager.js'
+import { registerSubagentTools, SUBAGENT_TOOLS } from '../subagent/tools.js'
+import { openSubagentViewer } from '../subagent/viewer.js'
+import type { PmSubagentState } from '../types.js'
+import {
+  mergePromptDefinitions,
+  type PromptDefinition,
+} from '../utils/markdown.js'
+import { notifyAgentMessage } from '../utils/messages.ts'
+
+const COORDINATOR_MODE_WIDGET_KEY = 'pi-pm-subagents:coordinator-mode'
+
+/** job event for pi-notify */
+const JOB_START_EVENT = 'pi-notify:job:start'
+const JOB_END_EVENT = 'pi-notify:job:end'
+
+export type { LiveSubagent, SubagentStatus }
+
+interface CoordinatorRuntime {
+  manager: SubagentManager
+  activityReporter: ActivityReporter
+  demoSubagentManager: SubagentManagerDemo | undefined
+  fleet: FleetList
+  batcher: MessageBatcher
+}
+
+let runtime: CoordinatorRuntime | undefined
+
+function requiredRuntime(): CoordinatorRuntime {
+  if (!runtime) {
+    throw new Error('Coordinator mode is not initialized.')
+  }
+  return runtime
+}
+
+export async function enterCoordinatorMode(
+  pi: ExtensionAPI,
+  state: PmSubagentState,
+  prompt: string | undefined,
+  ctx: ExtensionContext,
+  def: PromptDefinition,
+): Promise<void> {
+  assertModeIdle(state, 'coordinator')
+  state.mode = 'coordinator'
+  await applyCoordinatorMode(pi, state, ctx, def)
+  if (prompt) notifyAgentMessage(pi, prompt)
+}
+
+export function renderCoordinatorModeWidget(
+  ctx: ExtensionContext,
+  state?: PmSubagentState,
+): void {
+  const config = getPmSubagentsConfig()
+  const scope = config.subagentModelScoped ?? []
+  const currentRef = state?.sessionSubagentModel ?? config.subagentModel
+  const label = formatSubagentModelLabel(scope, currentRef)
+  ctx.ui.setWidget(COORDINATOR_MODE_WIDGET_KEY, [
+    ctx.ui.theme.fg(
+      'accent',
+      `${ctx.ui.theme.bold('👥 COORDINATOR MODE')} - subagent: ${label}`,
+    ),
+  ])
+}
+
+export async function applyCoordinatorMode(
+  pi: ExtensionAPI,
+  state: PmSubagentState,
+  ctx: ExtensionContext,
+  def: PromptDefinition,
+): Promise<void> {
+  const { fleet, activityReporter } = requiredRuntime()
+  fleet.setContext(ctx)
+
+  await applyModeFor(pi, state, 'coordinator', ctx, {
+    promptDefinition: mergePromptDefinitions(def, {
+      fm: {
+        extraTools: Object.values(SUBAGENT_TOOLS),
+      },
+    }),
+    color: 'accent',
+  })
+
+  renderCoordinatorModeWidget(ctx, state)
+
+  fleet.update()
+  activityReporter.start()
+}
+
+export async function exitCoordinatorMode(
+  pi: ExtensionAPI,
+  state: PmSubagentState,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const { manager, fleet, batcher, activityReporter } = requiredRuntime()
+  batcher.clear()
+  activityReporter.stop()
+  state.mode = undefined
+  fleet.dispose()
+  manager.disposeAll()
+  ctx.ui.setWidget(COORDINATOR_MODE_WIDGET_KEY, undefined)
+  await exitModeFor(pi, state, ctx, 'coordinator')
+}
+
+export async function setupCoordinator(
+  pi: ExtensionAPI,
+  state: PmSubagentState,
+  {
+    demoEnabled,
+    coordinatorDefinition,
+  }: {
+    demoEnabled: boolean
+    coordinatorDefinition: PromptDefinition
+  },
+): Promise<void> {
+  const batcher = new MessageBatcher((messages: readonly string[]) => {
+    if (state.mode !== 'coordinator') return
+    notifyAgentMessage(pi, messages.join('\n\n'))
+  })
+  const manager = new SubagentManager({
+    onStatusChange: () => runtime?.fleet.update(),
+    onEachStart: (subagent) => {
+      pi.events.emit(JOB_START_EVENT, {
+        id: `pi-pm-subagents:session:${subagent.id}`,
+      })
+    },
+    onEachEnd: (subagent) => {
+      pi.events.emit(JOB_END_EVENT, {
+        id: `pi-pm-subagents:session:${subagent.id}`,
+      })
+    },
+  })
+  const activityReporter = new ActivityReporter({
+    list: () => manager.list(),
+    onActivity: (subagent, report) => {
+      batcher.add(subagent, 'activity', report)
+    },
+  })
+
+  const fleet = new FleetList({
+    list: () => runtime?.demoSubagentManager?.list() ?? manager.list(),
+    onOpen: async (ctx, id) => {
+      const activeManager = runtime?.demoSubagentManager ?? manager
+      return openSubagentViewer(ctx, activeManager, id)
+    },
+  })
+
+  await loadRoles(process.cwd(), {
+    skipPluginAgents: getPmSubagentsConfig().skipPluginAgents,
+  })
+
+  runtime = {
+    manager,
+    activityReporter,
+    demoSubagentManager: undefined,
+    fleet,
+    batcher,
+  }
+
+  registerSubagentTools(pi, state, manager, fleet, batcher)
+
+  const coordinatorPrompt = coordinatorDefinition.systemPrompt
+
+  pi.on('before_agent_start', async (event) => {
+    if (state.mode !== 'coordinator') return
+    return { systemPrompt: `${event.systemPrompt}\n\n${coordinatorPrompt}` }
+  })
+
+  const runCoordinatorCommand = async (args: string, ctx: ExtensionContext) => {
+    const request = args.trim()
+    if (state.mode === 'coordinator') {
+      await exitCoordinatorMode(pi, state, ctx)
+      ctx.ui.notify('Coordinator mode off.', 'info')
+      return
+    }
+    await enterCoordinatorMode(pi, state, undefined, ctx, coordinatorDefinition)
+    if (request) notifyAgentMessage(pi, request)
+  }
+
+  pi.registerCommand('coordinator', {
+    description:
+      'Coordinator mode. Usage: /coordinator [request] — toggles, or enters with a task',
+    handler: runCoordinatorCommand,
+  })
+
+  pi.registerCommand('pm', {
+    description:
+      'Coordinator mode. Usage: /pm [request] — toggles, or enters with a task',
+    handler: runCoordinatorCommand,
+  })
+
+  pi.registerCommand('plan', {
+    description: 'Delegate a planner subagent. Usage: /plan <request>',
+    handler: async (args, ctx) => {
+      if (state.mode !== 'coordinator') {
+        await enterCoordinatorMode(
+          pi,
+          state,
+          undefined,
+          ctx,
+          coordinatorDefinition,
+        )
+      }
+      let request = args.trim()
+      if (!request && ctx.hasUI) {
+        request = (await ctx.ui.editor('Enter the request to plan:', '')) ?? ''
+      }
+      if (!request.trim()) return
+      notifyAgentMessage(
+        pi,
+        [
+          `<planRequest>${request}</planRequest>`,
+          "Use role 'planner' to create a plan. then other subagents to implements",
+        ].join('\n'),
+      )
+    },
+  })
+
+  if (demoEnabled) {
+    pi.registerCommand('subagent-demo', {
+      description: 'Browse a subagent live demo (coordinator mode)',
+      handler: async (args, ctx) => {
+        const argList = args.split(/\s+/)
+        if (!ctx.hasUI) return
+        if (state.mode !== 'coordinator') {
+          ctx.ui.notify(
+            'Subagents browser is only available in coordinator mode.',
+            'info',
+          )
+          return
+        }
+
+        const runtime = requiredRuntime()
+        const { fleet } = runtime
+
+        if (argList[0] === 'add') {
+          runtime.demoSubagentManager ??= new SubagentManagerDemo()
+          runtime.demoSubagentManager.add(argList.slice(1).join(' '))
+          fleet.update()
+          ctx.ui.notify(
+            'Added a demo subagent. Use /subagent demo to exit demo mode.',
+            'info',
+          )
+        } else if (runtime.demoSubagentManager) {
+          runtime.demoSubagentManager = undefined
+          fleet.update()
+          ctx.ui.notify('Demo mode exited.', 'info')
+        } else {
+          runtime.demoSubagentManager = new SubagentManagerDemo()
+          fleet.update()
+          ctx.ui.notify(
+            'Demo mode active: fake subagents loaded. Use /subagent demo to exit.',
+            'info',
+          )
+        }
+      },
+    })
+  }
+}

package/src/custom-select.test.ts

@@ -0,0 +1,91 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import type { TUI } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { CustomSelectComponent } from './custom-select.js'
+
+const DOWN = '\x1b[B'
+
+const makeTui = (): TUI =>
+  ({
+    terminal: { rows: 30, columns: 80 },
+    requestRender: () => {},
+  }) as unknown as TUI
+
+const makeTheme = (): Theme =>
+  ({
+    fg: (_color: string, text: string) => text,
+    bold: (text: string) => text,
+  }) as unknown as Theme
+
+describe('CustomSelectComponent', () => {
+  it('renders without throwing on small lists', () => {
+    const picker = new CustomSelectComponent(
+      makeTui(),
+      makeTheme(),
+      {
+        items: [
+          { key: 'a', text: 'apple' },
+          { key: 'b', text: 'banana' },
+        ],
+        title: 'Fruit',
+      },
+      () => {},
+      () => {},
+    )
+    expect(picker.render(40)).toBeDefined()
+  })
+
+  it('renders without throwing on large lists and caps the viewport', () => {
+    const items = Array.from({ length: 100 }, (_, i) => ({
+      key: `k${i}`,
+      text: `option-${i}`,
+    }))
+    const picker = new CustomSelectComponent(
+      makeTui(),
+      makeTheme(),
+      { items, title: 'Pick', maxVisible: 10 },
+      () => {},
+      () => {},
+    )
+    const lines = picker.render(40)
+    expect(lines.length).toBeGreaterThan(0)
+  })
+
+  it('reports the selected key via onSelect', () => {
+    let picked: string | undefined
+    const picker = new CustomSelectComponent(
+      makeTui(),
+      makeTheme(),
+      {
+        items: [
+          { key: 'a', text: 'apple' },
+          { key: 'b', text: 'banana' },
+        ],
+        title: 'Fruit',
+      },
+      (key) => {
+        picked = key
+      },
+      () => {},
+    )
+    picker.handleInput(DOWN) // move down
+    picker.handleInput('\n') // confirm
+    expect(picked).toBe('b')
+  })
+
+  it('invokes onCancel on escape', () => {
+    let cancelled = false
+    const picker = new CustomSelectComponent(
+      makeTui(),
+      makeTheme(),
+      { items: [{ key: 'a', text: 'apple' }], title: 'Fruit' },
+      () => {},
+      () => {
+        cancelled = true
+      },
+    )
+    picker.handleInput('\x1b')
+    expect(cancelled).toBe(true)
+  })
+})