@dreki-gg/pi-subagent 0.2.0 → 0.3.0

package/extensions/subagent/delegate-types.ts

@@ -0,0 +1,62 @@
+import type { Message } from '@mariozechner/pi-ai';
+
+export interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+export interface AgentResult {
+  agent: string;
+  task: string;
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+export type WorkflowId =
+  | 'scout-only'
+  | 'scout-and-plan'
+  | 'implement'
+  | 'implement-and-review'
+  | 'quick-fix'
+  | 'review';
+
+export interface WorkflowDefinition {
+  id: WorkflowId;
+  label: string;
+  description: string;
+  phases: PhaseDefinition[];
+}
+
+export type PhaseKind = 'parallel' | 'single';
+
+export interface PhaseDefinition {
+  kind: PhaseKind;
+  name: string;
+  agents: string[];
+  requiresConfirmation?: boolean;
+  taskTemplate: string;
+}
+
+export interface PhaseResult {
+  name: string;
+  kind: PhaseKind;
+  agents: AgentResult[];
+  skipped?: boolean;
+}
+
+export interface DelegateState {
+  synthesis: string;
+  workflow: WorkflowDefinition;
+  phases: PhaseResult[];
+  totalUsage: UsageStats;
+}

package/extensions/subagent/delegate-ui.ts

@@ -0,0 +1,132 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type {
+  AgentResult,
+  DelegateState,
+  PhaseResult,
+  UsageStats,
+  WorkflowDefinition,
+} from './delegate-types';
+import { WORKFLOWS, suggestWorkflow } from './workflows';
+
+function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1000000).toFixed(1)}M`;
+}
+
+function formatUsage(usage: UsageStats): string {
+  const parts: string[] = [];
+  if (usage.turns) parts.push(`${usage.turns} turns`);
+  if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+  if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+  if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+  if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  return parts.join(' ');
+}
+
+function getFinalText(result: AgentResult): string {
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const msg = result.messages[i];
+    if (msg.role === 'assistant') {
+      for (const part of msg.content) {
+        if (part.type === 'text') return part.text;
+      }
+    }
+  }
+  return '(no output)';
+}
+
+export async function confirmSynthesis(
+  ctx: ExtensionCommandContext,
+  synthesis: string,
+): Promise<boolean> {
+  return ctx.ui.confirm('Delegate — Task Synthesis', `${synthesis}\n\nProceed with this task?`);
+}
+
+export async function pickWorkflow(
+  ctx: ExtensionCommandContext,
+  synthesis: string,
+): Promise<WorkflowDefinition | null> {
+  const suggested = suggestWorkflow(synthesis);
+  const options = WORKFLOWS.map((wf) => {
+    const marker = wf.id === suggested ? ' ← suggested' : '';
+    return `${wf.label}${marker} — ${wf.description}`;
+  });
+
+  const choice = await ctx.ui.select('Delegate — Choose Workflow', options);
+  if (choice === undefined || choice === null) return null;
+
+  const selectedIndex = options.indexOf(choice as string);
+  if (selectedIndex < 0) return null;
+
+  return WORKFLOWS[selectedIndex];
+}
+
+export async function confirmPlan(
+  ctx: ExtensionCommandContext,
+  planText: string,
+): Promise<boolean> {
+  return ctx.ui.confirm('Delegate — Review Plan', `${planText}\n\nContinue with implementation?`);
+}
+
+export function formatPhaseHeader(
+  phaseName: string,
+  status: 'running' | 'done' | 'failed' | 'skipped',
+): string {
+  const icons = { running: '⏳', done: '✓', failed: '✗', skipped: '⊘' };
+  return `${icons[status]} ${phaseName}`;
+}
+
+export function formatAgentResult(result: AgentResult): string {
+  const icon = result.exitCode === 0 ? '✓' : '✗';
+  const output = getFinalText(result);
+  const preview = output.length > 200 ? `${output.slice(0, 200)}...` : output;
+  const usage = formatUsage(result.usage);
+  const model = result.model ? ` [${result.model}]` : '';
+
+  return `${icon} ${result.agent}${model}\n${preview}\n${usage}`;
+}
+
+export function formatPhaseSummary(phase: PhaseResult): string {
+  if (phase.skipped) return `⊘ ${phase.name} — skipped`;
+
+  const header = `── ${phase.name} (${phase.kind}) ──`;
+  const agentSummaries = phase.agents.map(formatAgentResult).join('\n\n');
+  return `${header}\n${agentSummaries}`;
+}
+
+export function formatFullSummary(state: DelegateState): string {
+  const sections = [
+    `── Synthesis ──\n${state.synthesis}`,
+    `── Workflow: ${state.workflow.label} ──`,
+    ...state.phases.map(formatPhaseSummary),
+    `── Usage ──\nTotal: ${formatUsage(state.totalUsage)}`,
+  ];
+
+  return sections.join('\n\n');
+}
+
+export function aggregateUsage(results: AgentResult[]): UsageStats {
+  const total: UsageStats = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+  };
+  for (const r of results) {
+    total.input += r.usage.input;
+    total.output += r.usage.output;
+    total.cacheRead += r.usage.cacheRead;
+    total.cacheWrite += r.usage.cacheWrite;
+    total.cost += r.usage.cost;
+    total.turns += r.usage.turns;
+  }
+  return total;
+}
+
+export { getFinalText };

package/extensions/subagent/index.ts

@@ -13,20 +13,43 @@
  */
 
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import * as fs from 'node:fs';
+import { copyFile, mkdir, readdir, unlink } from 'node:fs/promises';
 import * as os from 'node:os';
+import { join } from 'node:path';
 import * as path from 'node:path';
 import type { AgentToolResult } from '@mariozechner/pi-agent-core';
 import type { Message } from '@mariozechner/pi-ai';
 import { StringEnum } from '@mariozechner/pi-ai';
 import {
   type ExtensionAPI,
+  type ExtensionCommandContext,
+  getAgentDir,
   getMarkdownTheme,
   withFileMutationQueue,
 } from '@mariozechner/pi-coding-agent';
 import { Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
 import { Type } from '@sinclair/typebox';
-import { type AgentConfig, type AgentScope, discoverAgents } from './agents.js';
+import { type AgentConfig, type AgentScope, bundledAgentsDir, discoverAgents } from './agents.js';
+import { runAgent, runParallel } from './delegate-executor.js';
+import { buildSynthesisPrompt, extractRecentConversation } from './synthesis.js';
+import type {
+  AgentResult,
+  DelegateState,
+  PhaseDefinition,
+  PhaseResult,
+  UsageStats as DelegateUsageStats,
+} from './delegate-types.js';
+import {
+  aggregateUsage,
+  confirmPlan,
+  confirmSynthesis,
+  formatFullSummary,
+  formatPhaseHeader,
+  getFinalText,
+  pickWorkflow,
+} from './delegate-ui.js';
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
@@ -1083,4 +1106,274 @@ export default function (pi: ExtensionAPI) {
       return new Text(text?.type === 'text' ? text.text : '(no output)', 0, 0);
     },
   });
+
+  // ── Delegate commands ──────────────────────────────────────────────────────
+
+  function emptyDelegateUsage(): DelegateUsageStats {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+  }
+
+  function combineParallelOutputs(results: AgentResult[]): string {
+    return results
+      .map((r) => {
+        const output = getFinalText(r);
+        return `## ${r.agent}\n${output}`;
+      })
+      .join('\n\n');
+  }
+
+  async function executePhase(
+    cwd: string,
+    phase: PhaseDefinition,
+    synthesis: string,
+    previousOutput: string,
+    ctx: ExtensionCommandContext,
+  ): Promise<{ results: AgentResult[]; output: string; aborted: boolean }> {
+    const task = phase.taskTemplate
+      .replace(/\{synthesis\}/g, synthesis)
+      .replace(/\{previous\}/g, previousOutput);
+
+    ctx.ui.notify(
+      `${formatPhaseHeader(phase.name, 'running')} ${phase.kind === 'parallel' ? `(${phase.agents.length} agents)` : phase.agents[0]}`,
+      'info',
+    );
+
+    let results: AgentResult[];
+    if (phase.kind === 'parallel') {
+      results = await runParallel(
+        cwd,
+        phase.agents,
+        task,
+        (_phaseName, _agentName, _result) => {
+          // Streaming updates happen per-message
+        },
+        phase.name,
+      );
+    } else {
+      const result = await runAgent(cwd, phase.agents[0], task, undefined, phase.name);
+      results = [result];
+    }
+
+    const hasError = results.some((r) => r.exitCode !== 0 || r.stopReason === 'error');
+    if (hasError) {
+      const failedAgents = results
+        .filter((r) => r.exitCode !== 0 || r.stopReason === 'error')
+        .map((r) => `${r.agent}: ${r.errorMessage || r.stderr || '(unknown error)'}`)
+        .join('\n');
+
+      ctx.ui.notify(`${formatPhaseHeader(phase.name, 'failed')}\n${failedAgents}`, 'error');
+      return { results, output: combineParallelOutputs(results), aborted: true };
+    }
+
+    const output = combineParallelOutputs(results);
+    ctx.ui.notify(formatPhaseHeader(phase.name, 'done'), 'info');
+
+    if (phase.requiresConfirmation) {
+      const planText = output;
+      const proceed = await confirmPlan(ctx, planText);
+      if (!proceed) {
+        ctx.ui.notify('Delegate aborted by user after plan review.', 'warning');
+        return { results, output, aborted: true };
+      }
+    }
+
+    return { results, output, aborted: false };
+  }
+
+  async function listMdFiles(dir: string): Promise<Set<string>> {
+    if (!existsSync(dir)) return new Set();
+    try {
+      const entries = await readdir(dir);
+      return new Set(entries.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')));
+    } catch {
+      return new Set();
+    }
+  }
+
+  pi.registerCommand('delegate-agents', {
+    description: 'List, customize, or reset delegate agents',
+    handler: async (args, ctx) => {
+      const userDir = join(getAgentDir(), 'agents');
+      const parts = args?.trim().split(/\s+/) || [];
+      const action = parts[0] || 'list';
+
+      if (action === 'list') {
+        const bundled = await listMdFiles(bundledAgentsDir);
+        const user = await listMdFiles(userDir);
+        const allNames = new Set([...bundled, ...user]);
+
+        const lines: string[] = ['## Delegate Agents\n'];
+        for (const name of [...allNames].sort()) {
+          const isBundled = bundled.has(name);
+          const isUser = user.has(name);
+          if (isUser && isBundled) {
+            lines.push(`- **${name}** — user override (bundled version available, \`/delegate-agents reset ${name}\` to restore)`);
+          } else if (isUser) {
+            lines.push(`- **${name}** — user-only`);
+          } else {
+            lines.push(`- **${name}** — bundled`);
+          }
+        }
+        pi.sendMessage({ customType: 'delegate-agents-list', content: lines.join('\n'), display: true });
+        return;
+      }
+
+      if (action === 'reset') {
+        const name = parts[1];
+        if (!name) {
+          ctx.ui.notify('Usage: /delegate-agents reset <name|--all>', 'warning');
+          return;
+        }
+
+        if (name === '--all') {
+          const user = await listMdFiles(userDir);
+          const bundled = await listMdFiles(bundledAgentsDir);
+          let count = 0;
+          for (const n of user) {
+            if (bundled.has(n)) {
+              await unlink(join(userDir, `${n}.md`));
+              count++;
+            }
+          }
+          ctx.ui.notify(count > 0 ? `Reset ${count} agent(s) to bundled versions.` : 'No user overrides to reset.', 'info');
+          return;
+        }
+
+        const userFile = join(userDir, `${name}.md`);
+        const bundledFile = join(bundledAgentsDir, `${name}.md`);
+
+        if (!existsSync(userFile)) {
+          ctx.ui.notify(`No user override for "${name}" — already using bundled version.`, 'info');
+          return;
+        }
+        if (!existsSync(bundledFile)) {
+          ctx.ui.notify(`"${name}" is user-only (no bundled version). Delete manually if needed.`, 'warning');
+          return;
+        }
+
+        await unlink(userFile);
+        ctx.ui.notify(`Reset "${name}" — now using bundled version.`, 'info');
+        return;
+      }
+
+      if (action === 'edit') {
+        const name = parts[1];
+        if (!name) {
+          ctx.ui.notify('Usage: /delegate-agents edit <name>', 'warning');
+          return;
+        }
+
+        const bundledFile = join(bundledAgentsDir, `${name}.md`);
+        const userFile = join(userDir, `${name}.md`);
+
+        if (existsSync(userFile)) {
+          ctx.ui.notify(`User override already exists: ${userFile}`, 'info');
+          return;
+        }
+        if (!existsSync(bundledFile)) {
+          ctx.ui.notify(`No bundled agent named "${name}".`, 'warning');
+          return;
+        }
+
+        await mkdir(userDir, { recursive: true });
+        await copyFile(bundledFile, userFile);
+        ctx.ui.notify(`Copied "${name}" to ${userFile} — edit it there to customize.`, 'info');
+        return;
+      }
+
+      ctx.ui.notify('Unknown action. Usage: /delegate-agents [list|reset <name|--all>|edit <name>]', 'warning');
+    },
+  });
+
+  pi.registerCommand('delegate', {
+    description: 'Orchestrate subagent workflows — scouts, planners, workers, reviewers',
+    handler: async (args, ctx) => {
+      const explicitTask = args?.trim() || undefined;
+
+      // Step 1: Synthesize
+      const conversation = extractRecentConversation(ctx);
+      if (!conversation.trim() && !explicitTask) {
+        ctx.ui.notify(
+          'No conversation context and no task specified. Usage: /delegate [task]',
+          'warning',
+        );
+        return;
+      }
+
+      const prompt = buildSynthesisPrompt(conversation, explicitTask);
+      ctx.ui.notify('⏳ Synthesizing task from conversation...', 'info');
+
+      const synthResult = await runAgent(ctx.cwd, 'planner', prompt);
+      const synthesis = getFinalText(synthResult);
+
+      if (!synthesis.trim()) {
+        ctx.ui.notify('Failed to synthesize task from conversation.', 'error');
+        return;
+      }
+
+      // Step 2: Confirm synthesis
+      const synthOk = await confirmSynthesis(ctx, synthesis);
+      if (!synthOk) {
+        ctx.ui.notify('Delegate cancelled.', 'info');
+        return;
+      }
+
+      // Step 3: Pick workflow
+      const workflow = await pickWorkflow(ctx, synthesis);
+      if (!workflow) {
+        ctx.ui.notify('Delegate cancelled — no workflow selected.', 'info');
+        return;
+      }
+
+      // Step 4: Execute phases
+      const state: DelegateState = {
+        synthesis,
+        workflow,
+        phases: [],
+        totalUsage: emptyDelegateUsage(),
+      };
+
+      let previousOutput = '';
+
+      ctx.ui.notify(`Starting workflow: ${workflow.label}`, 'info');
+
+      for (const phaseDef of workflow.phases) {
+        const phaseResult = await executePhase(ctx.cwd, phaseDef, synthesis, previousOutput, ctx);
+
+        const phase: PhaseResult = {
+          name: phaseDef.name,
+          kind: phaseDef.kind,
+          agents: phaseResult.results,
+        };
+
+        state.phases.push(phase);
+        const phaseUsage = aggregateUsage(phaseResult.results);
+        state.totalUsage.input += phaseUsage.input;
+        state.totalUsage.output += phaseUsage.output;
+        state.totalUsage.cacheRead += phaseUsage.cacheRead;
+        state.totalUsage.cacheWrite += phaseUsage.cacheWrite;
+        state.totalUsage.cost += phaseUsage.cost;
+        state.totalUsage.turns += phaseUsage.turns;
+
+        if (phaseResult.aborted) break;
+
+        previousOutput = phaseResult.output;
+      }
+
+      // Step 5: Show full summary
+      const summary = formatFullSummary(state);
+      ctx.ui.notify(`Delegate complete — ${workflow.label}`, 'info');
+
+      pi.sendMessage({
+        customType: 'delegate-summary',
+        content: summary,
+        display: true,
+        details: {
+          workflow: workflow.id,
+          phaseCount: state.phases.length,
+          totalUsage: state.totalUsage,
+        },
+      });
+    },
+  });
 }

package/extensions/subagent/synthesis.ts

@@ -0,0 +1,78 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+
+const MAX_MESSAGES = 40;
+
+const SYNTHESIS_INSTRUCTION = `Synthesize the current conversation into a clear task specification for a team of subagents that will execute it.
+
+Your synthesis MUST capture:
+
+1. **Goal** — What are we building, changing, or investigating?
+2. **Decisions made** — Every locked choice, preference, or constraint the user confirmed.
+3. **Constraints** — What was explicitly rejected and why.
+4. **Architecture** — The agreed structure, file layout, data flow, or integration shape.
+5. **Open questions** — Anything flagged but not resolved yet.
+6. **Intent** — The user's real motivation and the nuance behind the decisions.
+
+Be specific and actionable. Do NOT summarize vaguely. Include concrete names, paths, tools, APIs, and patterns that were discussed.
+
+The output should be usable by agents who have NOT seen this conversation.
+
+Format:
+
+## Goal
+<one paragraph>
+
+## Decisions
+<bulleted list of every locked decision>
+
+## Constraints
+<bulleted list of what was rejected and why>
+
+## Architecture
+<concrete structure, files, data flow>
+
+## Open Questions
+<anything unresolved>
+
+## Intent
+<the user's real motivation>`;
+
+export function extractRecentConversation(ctx: ExtensionCommandContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  const messages: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.type !== 'message') continue;
+    const msg = entry.message;
+    if (!msg) continue;
+
+    if (msg.role === 'user' || msg.role === 'assistant') {
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      const textParts = content
+        .filter((part: { type: string }) => part.type === 'text')
+        .map((part: { type: string; text?: string }) => (part as { text: string }).text)
+        .join('\n');
+
+      if (textParts.trim()) {
+        messages.push(`[${msg.role}]\n${textParts.trim()}`);
+      }
+    }
+  }
+
+  return messages.slice(-MAX_MESSAGES).join('\n\n---\n\n');
+}
+
+export function buildSynthesisPrompt(conversation: string, explicitTask?: string): string {
+  const parts = [SYNTHESIS_INSTRUCTION];
+
+  if (explicitTask) {
+    parts.push(`\nThe user explicitly specified the task as:\n${explicitTask}`);
+    parts.push(
+      '\nUse this as the primary goal, but enrich it with relevant context from the conversation.',
+    );
+  }
+
+  parts.push(`\n\n## Conversation\n\n${conversation}`);
+
+  return parts.join('\n');
+}