@raidou/pi-pm-subagents 0.1.1

package/src/subagent/tools.ts

@@ -0,0 +1,314 @@
+import {
+  type AgentToolResult,
+  defineTool,
+  type ExtensionAPI,
+} from '@earendil-works/pi-coding-agent'
+import { orderBy } from 'lodash-es'
+import { Type } from 'typebox'
+
+import { resolveSubagentModelForSpawn } from '../models-config/subagent-model-utils.js'
+import { baseToolsOf } from '../pm-mode.js'
+import { resolveRole, rolesDescription } from '../prompts/roles.js'
+import type { PmSubagentState } from '../types.js'
+import { askHowToProceed } from '../ui/review-pager.js'
+import { composeTools, registerOptionalTools } from '../utils/tools.js'
+import type { MessageBatcher } from './batcher.js'
+import type { FleetList } from './fleet.js'
+import type { SubagentManager } from './manager.js'
+import type { LiveSubagent } from './manager.js'
+import {
+  formatSubagentSummary,
+  MAX_CONCURRENCY_SUBAGENT,
+  MAX_REUSE_FOLLOWUPS,
+} from './manager.js'
+
+function toolResultFromError(error: unknown): AgentToolResult<unknown> {
+  const message = error instanceof Error ? error.message : String(error)
+  return { content: [{ type: 'text', text: message }], details: {} }
+}
+
+const stopSubagentOnAbort = (
+  signal: AbortSignal | undefined,
+  id: number,
+  manager: SubagentManager,
+): void => {
+  if (!signal) return
+  const stop = (): void => {
+    void manager.abort(id)
+  }
+  if (signal.aborted) stop()
+  else signal.addEventListener('abort', stop, { once: true })
+}
+
+export const SUBAGENT_TOOLS = {
+  delegate: 'subagent_delegate',
+  followup: 'subagent_followup',
+  kill: 'subagent_kill',
+  list: 'subagent_list',
+} as const
+
+const LIST_COOL_DOWN_MS = 1 * 60 * 1000
+
+export function registerSubagentTools(
+  pi: ExtensionAPI,
+  state: PmSubagentState,
+  manager: SubagentManager,
+  fleet: FleetList,
+  batcher: MessageBatcher,
+): void {
+  let lastListAt = Date.now()
+
+  pi.on('session_start', () => {
+    const tools = [
+      defineTool({
+        name: SUBAGENT_TOOLS.list,
+        label: 'List Subagents',
+        description: `List all background subagents, don't poll this tool to wait subagents complete, just wait silently`,
+        parameters: Type.Object({}),
+        async execute() {
+          if (Date.now() - lastListAt < LIST_COOL_DOWN_MS)
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: "Please don't poll for this tool, just wait silently",
+                },
+              ],
+              details: {},
+            }
+
+          lastListAt = Date.now()
+
+          const allSubagents = manager.list()
+          if (allSubagents.length === 0) {
+            return {
+              content: [{ type: 'text', text: 'No subagents.' }],
+              details: {},
+            }
+          }
+
+          const sorted = orderBy(allSubagents, (it) => it.id, 'desc')
+          const lines = [`Subagents (${allSubagents.length}):`]
+          for (const subagent of sorted) {
+            lines.push(formatSubagentSummary(subagent))
+          }
+
+          const hasRunning = sorted.some(
+            (subagent) => subagent.status === 'running',
+          )
+          if (hasRunning)
+            lines.push(
+              '',
+              `DO NOT POLL THIS TOOL TO WAIT FOR SUBAGENTS COMPLETION, JUST WAIT SILENTLY, YOU WILL BE NOTIFIED WHEN SUBAGENTS FINISH.`,
+            )
+          return {
+            content: [
+              {
+                type: 'text',
+                text: lines.join('\n'),
+              },
+            ],
+            details: {},
+          }
+        },
+      }),
+
+      defineTool({
+        name: SUBAGENT_TOOLS.delegate,
+        label: 'Delegate Subagent',
+        description: `Delegate task to background with full tool access. The tool returns immediately with a subagent id; I'll send you last message when subagent finishes. Max concurrency ${MAX_CONCURRENCY_SUBAGENT} running subagents\nAvailable roles:\n${rolesDescription(baseToolsOf(pi, state))}`,
+        parameters: Type.Object({
+          title: Type.String(),
+          prompt: Type.String({
+            description: 'Prompt of the subagent should do',
+          }),
+          role: Type.String({
+            description: `Role of subagent`,
+          }),
+        }),
+        async execute(
+          _toolCallId,
+          params,
+          signal,
+          _onUpdate,
+          ctx,
+        ): Promise<AgentToolResult<unknown>> {
+          const role = resolveRole(params.role)
+          const reviewOnEnd = role.fm.reviewOnEnd ?? false
+
+          const tools = composeTools(baseToolsOf(pi, state), {
+            tools: role.fm.tools,
+            extraTools: role.fm.extraTools,
+            removeTools: role.fm.removeTools,
+          })
+
+          const model = resolveSubagentModelForSpawn(
+            ctx,
+            role.fm.model,
+            state.sessionSubagentModel,
+          )
+
+          let subagent: LiveSubagent
+          try {
+            subagent = await manager.createNewSubagent(
+              params.title,
+              params.prompt,
+              {
+                cwd: ctx.cwd,
+                model,
+                thinkingLevel: role.fm.thinkingLevel ?? 'low',
+                tools,
+                systemPrompt: role.systemPrompt,
+                role: params.role,
+                onComplete: async (subagent, lastMessage) => {
+                  if (state.mode !== 'coordinator') return
+                  if (subagent.status === 'killed') return
+                  if (!lastMessage) return
+                  if (subagent.status === 'failed') {
+                    batcher.add(subagent, 'done', lastMessage)
+                    return
+                  }
+                  if (!reviewOnEnd || !ctx.hasUI) {
+                    batcher.add(subagent, 'done', lastMessage)
+                    return
+                  }
+
+                  await askHowToProceed(ctx, {
+                    title: '📋 Planner Review',
+                    plan: lastMessage,
+                    choices: [
+                      {
+                        id: 'send-to-coordinator',
+                        label: 'Send plan to coordinator',
+                        action: () => {
+                          batcher.add(subagent, 'done', lastMessage)
+                        },
+                      },
+                      {
+                        id: 'update-the-plan',
+                        label: 'Update the plan',
+                        action: async () => {
+                          const updatePrompt = await ctx.ui.editor(
+                            'Update the plan:',
+                            '',
+                          )
+                          if (updatePrompt?.trim()) {
+                            await manager.followup(
+                              subagent.id,
+                              `${subagent.title} (revised)`,
+                              `Update the plan based on:\n\n${updatePrompt.trim()}`,
+                            )
+                          }
+                        },
+                      },
+                      {
+                        id: 'discard',
+                        label: 'Discard',
+                        action: () => {},
+                      },
+                    ],
+                  })
+                },
+              },
+            )
+            fleet.update()
+          } catch (error) {
+            return toolResultFromError(error)
+          }
+
+          stopSubagentOnAbort(signal, subagent.id, manager)
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Subagent id #${subagent.id} running at background. I'll send you last message when it finishes.`,
+              },
+            ],
+            details: { subagentId: subagent.id, status: subagent.status },
+          }
+        },
+      }),
+
+      defineTool({
+        name: SUBAGENT_TOOLS.followup,
+        label: 'Follow Up Subagent',
+        description: `Continue working with an existing subagent. Max reuse ${MAX_REUSE_FOLLOWUPS} times.`,
+        parameters: Type.Object({
+          id: Type.Number(),
+          title: Type.String(),
+          prompt: Type.String({
+            description: 'Prompt of the subagent should do',
+          }),
+        }),
+        async execute(
+          _toolCallId,
+          params,
+          signal,
+        ): Promise<AgentToolResult<unknown>> {
+          let subagent: LiveSubagent
+          try {
+            subagent = await manager.followup(
+              params.id,
+              params.title,
+              params.prompt,
+            )
+          } catch (error) {
+            return toolResultFromError(error)
+          }
+
+          stopSubagentOnAbort(signal, subagent.id, manager)
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Subagent #${subagent.id} continued. I'll send you last message when it finishes.`,
+              },
+            ],
+            details: { subagentId: subagent.id, status: subagent.status },
+          }
+        },
+      }),
+
+      defineTool({
+        name: SUBAGENT_TOOLS.kill,
+        label: 'Kill Subagent',
+        description: 'Kill a running subagent by id.',
+        parameters: Type.Object({
+          id: Type.Number({ description: 'Subagent id to stop.' }),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+          const subagent = manager.get(params.id)
+          if (!subagent) {
+            return {
+              content: [
+                { type: 'text', text: `Subagent #${params.id} not found.` },
+              ],
+              details: {},
+            }
+          }
+          try {
+            const stopped = await manager.abort(params.id)
+            const message = stopped
+              ? `Subagent #${params.id} killed.`
+              : `Subagent #${params.id} is not running (status: ${subagent.status}).`
+            return {
+              content: [{ type: 'text', text: message }],
+              details: { subagentId: params.id, status: subagent.status },
+            }
+          } catch (error) {
+            const message =
+              error instanceof Error ? error.message : String(error)
+            return {
+              content: [{ type: 'text', text: message }],
+              details: { subagentId: params.id, status: subagent.status },
+            }
+          }
+        },
+      }),
+    ]
+
+    registerOptionalTools(pi, tools, true)
+  })
+}

package/src/subagent/viewer.ts

@@ -0,0 +1,305 @@
+import type { UserMessage } from '@earendil-works/pi-ai'
+import type {
+  ExtensionContext,
+  Theme,
+  ThemeColor,
+} from '@earendil-works/pi-coding-agent'
+import type { Component, OverlayHandle, TUI } from '@earendil-works/pi-tui'
+import {
+  isKeyRelease,
+  Key,
+  matchesKey,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from '@earendil-works/pi-tui'
+
+import { BorderView } from '../ui/border-view.js'
+import { ScrollView } from '../ui/scroll-view.js'
+import { rightAlign, strInline } from '../utils/format.js'
+import { truncateText } from '../utils/truncate.js'
+import type {
+  LiveSubagent,
+  SubagentManager,
+  SubagentStatus,
+} from './manager.js'
+
+const STATUS_COLOR = {
+  running: 'accent',
+  done: 'success',
+  failed: 'error',
+  killed: 'dim',
+} satisfies Record<SubagentStatus, ThemeColor>
+
+let openedViewerHandle: OverlayHandle | undefined
+
+const TOOL_RESULT_PREVIEW = 500
+const VIEWPORT_HEIGHT_PCT = 80
+const VIEWER_CHROME_LINES = 7
+const OVERLAY_WIDTH_PCT = '90%'
+
+export type ViewerResult = undefined | 'steer'
+
+export class SubagentViewer implements Component {
+  #stopArmed = false
+  readonly #scroll: ScrollView
+  readonly #unsubscribe: () => void
+
+  constructor(
+    private tui: TUI,
+    private theme: Theme,
+    private subagent: LiveSubagent,
+    private manager: SubagentManager,
+    private done: (result: ViewerResult) => void,
+  ) {
+    this.#scroll = new ScrollView(tui, theme, {
+      child: {
+        render: (width) => this.renderContent(width),
+        invalidate: () => {},
+      },
+      viewportHeight: () =>
+        Math.max(
+          3,
+          Math.floor((tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100) -
+            VIEWER_CHROME_LINES,
+        ),
+      autoFollow: true,
+    })
+    this.#unsubscribe = subagent.session.subscribe(() => {
+      tui.requestRender()
+    })
+  }
+
+  handleInput(data: string): void {
+    if (isKeyRelease(data)) return
+
+    if (matchesKey(data, Key.escape) || data === 'q') {
+      this.done(undefined)
+      return
+    }
+
+    if (data === 'x' && this.subagent.status === 'running') {
+      if (this.#stopArmed) {
+        this.#stopArmed = false
+        void this.manager.abort(this.subagent.id).then(() => {
+          this.tui.requestRender()
+        })
+      } else {
+        this.#stopArmed = true
+      }
+      this.tui.requestRender()
+      return
+    }
+    if (this.#stopArmed) this.#stopArmed = false
+
+    if (matchesKey(data, Key.enter) && this.subagent.status === 'running') {
+      this.done('steer')
+      return
+    }
+
+    this.#scroll.handleInput(data)
+  }
+
+  render(width: number): string[] {
+    if (width < 4) return []
+    const separator = this.theme.fg('dim', '─'.repeat(width))
+    const lines = [this.headerLine(width)]
+    const tools = this.toolsLine(width)
+    if (tools) lines.push(tools)
+    lines.push(
+      separator,
+      ...this.#scroll.render(width),
+      separator,
+      this.footerLine(width),
+    )
+    return lines
+  }
+
+  invalidate(): void {
+    this.#scroll.invalidate()
+  }
+
+  dispose(): void {
+    this.#unsubscribe()
+  }
+
+  private headerLine(width: number): string {
+    const th = this.theme
+    const status = this.subagent.status
+    const color = STATUS_COLOR[status]
+    const id = `#${this.subagent.id}`
+    const role = `[${this.subagent.role}]`
+    const titleMaxWidth = width - visibleWidth(`${status + id} ${role}`) - 1
+    return rightAlign(
+      `${th.fg('muted', `#${this.subagent.id}`)} ${th.fg('muted', role)} ${truncateText(strInline(this.subagent.title), titleMaxWidth)}`,
+      th.fg(color, status),
+      width,
+    )
+  }
+
+  private toolsLine(width: number): string {
+    const th = this.theme
+    const tools = this.subagent.activeTools
+    if (tools.length === 0) return ''
+    const sep = th.fg('dim', ' · ')
+    return rightAlign(
+      '',
+      `Tools: ${tools.map((name) => th.fg('muted', name)).join(sep)}`,
+      width,
+    )
+  }
+
+  private footerLine(width: number): string {
+    const th = this.theme
+    const running = this.subagent.status === 'running'
+    const sep = th.fg('dim', ' · ')
+    const keys: [string, string][] = []
+    if (running) {
+      keys.push(this.#stopArmed ? ['x', 'again to STOP'] : ['x', 'stop'], [
+        'enter',
+        'steer',
+      ])
+    }
+    keys.push(
+      ['j/k ↑/↓', 'line'],
+      ['u/d ␣', 'PageUp/Dn page'],
+      ['g/G', 'Home/End jump'],
+      ['q/esc', 'close'],
+    )
+    return truncateText(
+      keys
+        .map(
+          ([key, desc]) =>
+            `${th.fg('syntaxKeyword', key)} ${th.fg('success', desc)}`,
+        )
+        .join(sep),
+      width,
+    )
+  }
+
+  private renderContent(width: number): string[] {
+    if (width <= 0) return []
+    const th = this.theme
+    const messages = this.subagent.session.messages
+    if (messages.length === 0)
+      return [th.fg('dim', '(waiting for first message…)')]
+
+    const separatorLine = th.fg('dim', '─'.repeat(width))
+    const lines: string[] = []
+    let separator = false
+    for (const message of messages) {
+      if (message.role === 'user') {
+        const text = userText(message)
+        if (!text.trim()) continue
+        if (separator) lines.push(separatorLine)
+        lines.push(th.fg('accent', th.bold('[user]')))
+        lines.push(...wrapTextWithAnsi(text.trim(), width))
+      } else if (message.role === 'assistant') {
+        const text: string[] = []
+        const tools: { name: string; params: string }[] = []
+        for (const block of message.content) {
+          if (block.type === 'text' && block.text) text.push(block.text)
+          else if (block.type === 'toolCall')
+            tools.push({
+              name: block.name,
+              params: JSON.stringify(block.arguments),
+            })
+        }
+        if (text.length === 0 && tools.length === 0) continue
+        if (separator) lines.push(separatorLine)
+        lines.push(th.bold('[assistant]'))
+        if (text.length > 0)
+          lines.push(...wrapTextWithAnsi(text.join('\n').trim(), width))
+        for (const { name, params } of tools) {
+          lines.push(
+            truncateText(
+              `${th.fg('muted', `🔧 ${name}`)} ${th.fg('dim', params)}`,
+              width,
+            ),
+          )
+        }
+      } else if (message.role === 'toolResult') {
+        const raw = message.content
+          .filter(
+            (block): block is { type: 'text'; text: string } =>
+              block.type === 'text',
+          )
+          .map((block) => block.text)
+          .join('\n')
+          .trim()
+        if (!raw) continue
+        const preview =
+          raw.length > TOOL_RESULT_PREVIEW
+            ? `${raw.slice(0, TOOL_RESULT_PREVIEW)}…`
+            : raw
+        if (separator) lines.push(separatorLine)
+        lines.push(th.fg('dim', '[result]'))
+        lines.push(
+          ...wrapTextWithAnsi(preview, width).map((line) => th.fg('dim', line)),
+        )
+      }
+      separator = true
+    }
+    return lines.map((line) => truncateText(line, width))
+  }
+}
+
+function userText(message: UserMessage): string {
+  return typeof message.content === 'string'
+    ? message.content
+    : message.content
+        .filter(
+          (block): block is { type: 'text'; text: string } =>
+            block.type === 'text',
+        )
+        .map((block) => block.text)
+        .join('\n')
+}
+
+export async function openSubagentViewer(
+  ctx: ExtensionContext,
+  manager: SubagentManager,
+  id: number,
+): Promise<void> {
+  const subagent = manager.get(id)
+  if (!subagent) {
+    ctx.ui.notify(`Subagent #${id} not found.`, 'warning')
+    return
+  }
+  openedViewerHandle?.hide()
+  ctx.ui.setWorkingVisible(false)
+  let result: ViewerResult
+  try {
+    result = await ctx.ui.custom<ViewerResult>(
+      (tui, theme, _keybindings, done) =>
+        new BorderView(theme, {
+          child: new SubagentViewer(tui, theme, subagent, manager, done),
+        }),
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: 'center',
+          width: OVERLAY_WIDTH_PCT,
+          maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
+        },
+        onHandle: (handle) => {
+          openedViewerHandle = handle
+        },
+      },
+    )
+  } finally {
+    openedViewerHandle = undefined
+    ctx.ui.setWorkingVisible(true)
+  }
+
+  if (result !== 'steer') return
+  const message = await ctx.ui.editor(`Steer subagent #${id}:`, '')
+  const trimmed = message?.trim()
+  if (trimmed) {
+    const ok = await manager.steer(id, trimmed)
+    ctx.ui.notify(
+      ok ? `Steered subagent #${id}.` : `Subagent #${id} is no longer running.`,
+      ok ? 'info' : 'warning',
+    )
+  }
+  return openSubagentViewer(ctx, manager, id)
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+export type PmMode = 'coordinator'
+
+export interface ModeToolsDiff {
+  added: string[]
+  removed: string[]
+}
+
+export interface PmSubagentState {
+  mode: PmMode | undefined
+  modeDiffTools?: ModeToolsDiff
+  /** Current model captured before entering a read-only mode, restored on exit. */
+  previousModel?: string
+  /** Session-scoped subagent model. Source of truth for spawn. */
+  sessionSubagentModel?: string
+}

package/src/ui/border-view.ts

@@ -0,0 +1,50 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import type { Component } from '@earendil-works/pi-tui'
+
+import { truncateText } from '../utils/truncate.js'
+
+export interface BorderViewOptions {
+  readonly child: Component
+}
+
+/**
+ * A border wrapper for pi-tui components. Adds a border around the child
+ * component while preserving all its functionality (render, handleInput, invalidate).
+ */
+export class BorderView implements Component {
+  readonly #child: Component
+  readonly #theme: Theme
+
+  constructor(theme: Theme, options: BorderViewOptions) {
+    this.#child = options.child
+    this.#theme = theme
+  }
+
+  render(width: number): string[] {
+    if (width < 4) return this.#child.render(width)
+
+    const contentWidth = Math.max(1, width - 2)
+    const content = this.#child.render(contentWidth)
+    const th = this.#theme
+
+    const topBorder = th.fg('dim', `┌${'─'.repeat(contentWidth)}┐`)
+    const bottomBorder = th.fg('dim', `└${'─'.repeat(contentWidth)}┘`)
+    const leftBorder = th.fg('dim', '│')
+    const rightBorder = th.fg('dim', '│')
+
+    const borderedContent = content.map(
+      (line) =>
+        `${leftBorder}${truncateText(line, contentWidth, undefined, true)}${rightBorder}`,
+    )
+
+    return [topBorder, ...borderedContent, bottomBorder]
+  }
+
+  handleInput(data: string): void {
+    this.#child.handleInput?.(data)
+  }
+
+  invalidate(): void {
+    this.#child.invalidate()
+  }
+}