@dreki-gg/pi-subagent 0.6.0 → 0.8.0

package/extensions/subagent/run-agent-args.ts

@@ -0,0 +1,90 @@
+import type { AgentScope } from './agents';
+
+export interface RunAgentCommandOptions {
+  agentScope: AgentScope;
+  confirmProjectAgents: boolean;
+  model?: string;
+  thinking?: string;
+  agentName?: string;
+  explicitTask?: string;
+}
+
+function tokenize(input: string): string[] {
+  return input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? [];
+}
+
+export function formatRunAgentUsage(): string {
+  return 'Usage: /run-agent [--scope user|project|both] [--model <id>] [--thinking <level>] [--yes-project-agents] <agent> [task]';
+}
+
+export function parseRunAgentArgs(rawArgs?: string):
+  | { ok: true; options: RunAgentCommandOptions }
+  | { ok: false; error: string } {
+  const tokens = tokenize(rawArgs?.trim() ?? '');
+  const taskTokens: string[] = [];
+
+  let agentScope: AgentScope = 'user';
+  let confirmProjectAgents = true;
+  let model: string | undefined;
+  let thinking: string | undefined;
+  let agentName: string | undefined;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token === '--scope') {
+      const value = tokens[++i];
+      if (!value || !['user', 'project', 'both'].includes(value)) {
+        return { ok: false, error: `Invalid --scope value.\n\n${formatRunAgentUsage()}` };
+      }
+      agentScope = value as AgentScope;
+      continue;
+    }
+
+    if (token === '--model') {
+      const value = tokens[++i];
+      if (!value) {
+        return { ok: false, error: `Missing --model value.\n\n${formatRunAgentUsage()}` };
+      }
+      model = value;
+      continue;
+    }
+
+    if (token === '--thinking' || token === '--reasoning-level') {
+      const value = tokens[++i];
+      if (!value) {
+        return { ok: false, error: `Missing ${token} value.\n\n${formatRunAgentUsage()}` };
+      }
+      thinking = value;
+      continue;
+    }
+
+    if (token === '--yes-project-agents') {
+      confirmProjectAgents = false;
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      return { ok: false, error: `Unknown option: ${token}\n\n${formatRunAgentUsage()}` };
+    }
+
+    if (!agentName) {
+      agentName = token;
+      continue;
+    }
+
+    taskTokens.push(token);
+  }
+
+  return {
+    ok: true,
+    options: {
+      agentScope,
+      confirmProjectAgents,
+      model,
+      thinking,
+      agentName,
+      explicitTask: taskTokens.join(' ').trim() || undefined,
+    },
+  };
+}

package/extensions/subagent/{delegate-executor.ts → spawn-utils.ts}

@@ -1,26 +1,37 @@
+/**
+ * Shared utilities for spawning pi subagent processes.
+ * Used by both the `subagent` tool (index.ts) and the `/run-agent` command (agent-runner.ts).
+ */
+
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { withFileMutationQueue } from '@mariozechner/pi-coding-agent';
-import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
-import type { Message } from '@mariozechner/pi-ai';
-import { discoverAgentsWithPackages, type AgentScope } from './agents';
-import type { AgentResult, UsageStats } from './delegate-types';
+import { withFileMutationQueue } from '@earendil-works/pi-coding-agent';
+import type { Message } from '@earendil-works/pi-ai';
+import type { UsageStats } from './agent-runner-types.js';
 
-function emptyUsage(): UsageStats {
+export function emptyUsage(): UsageStats {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
 
 function getPiInvocation(args: string[]): { command: string; args: string[] } {
   const currentScript = process.argv[1];
-  if (currentScript && fs.existsSync(currentScript)) {
+
+  // Bun standalone binaries set argv[1] to a virtual FS path (e.g. /$bunfs/root/pi)
+  // that only resolves inside the running Bun process. Skip it — the binary IS the entry point.
+  const isBunVirtualPath = currentScript?.startsWith('/$bunfs/');
+
+  if (currentScript && !isBunVirtualPath && fs.existsSync(currentScript)) {
     return { command: process.execPath, args: [currentScript, ...args] };
   }
 
   const execName = path.basename(process.execPath).toLowerCase();
   const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-  if (!isGenericRuntime) return { command: process.execPath, args };
+  if (!isGenericRuntime) {
+    // Standalone binary (e.g. pi compiled with Bun) — invoke directly
+    return { command: process.execPath, args };
+  }
 
   return { command: 'pi', args };
 }
@@ -38,74 +49,76 @@ async function writePromptToTempFile(
   return { dir: tmpDir, filePath };
 }
 
-export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
+function cleanupTempFiles(
+  tmpPromptPath: string | null,
+  tmpPromptDir: string | null,
+): void {
+  if (tmpPromptPath) try { fs.unlinkSync(tmpPromptPath); } catch { /* ignore */ }
+  if (tmpPromptDir) try { fs.rmdirSync(tmpPromptDir); } catch { /* ignore */ }
+}
 
-export interface RunAgentOptions {
-  agentScope?: AgentScope;
-  cwd?: string;
-  onUpdate?: OnPhaseUpdate;
-  phaseName?: string;
+export interface SpawnPiAgentOptions {
+  cwd: string;
+  agentName: string;
+  task: string;
+  systemPrompt?: string;
+  model?: string;
+  thinking?: string;
+  tools?: string[];
   signal?: AbortSignal;
-  resolvedPaths?: ResolvedPaths;
+  onMessage?: (msg: Message) => void;
+  onToolResult?: (msg: Message) => void;
 }
 
-export async function runAgent(
-  cwd: string,
-  agentName: string,
-  task: string,
-  options: RunAgentOptions = {},
-): Promise<AgentResult> {
-  const { agents } = discoverAgentsWithPackages(cwd, options.agentScope ?? 'user', options.resolvedPaths);
-  const agent = agents.find((a) => a.name === agentName);
-
-  if (!agent) {
-    const available = agents.map((a) => a.name).join(', ') || 'none';
-    return {
-      agent: agentName,
-      task,
-      exitCode: 1,
-      messages: [],
-      stderr: `Unknown agent: "${agentName}". Available: ${available}.`,
-      usage: emptyUsage(),
-    };
-  }
+export interface SpawnPiAgentResult {
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  wasAborted: boolean;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
 
+/**
+ * Spawn a pi process for a subagent and collect results.
+ * This is the shared core that both the tool and the /run-agent command use.
+ */
+export async function spawnPiAgent(options: SpawnPiAgentOptions): Promise<SpawnPiAgentResult> {
   const args: string[] = ['--mode', 'json', '-p', '--no-session'];
-  if (agent.model) args.push('--model', agent.model);
-  if (agent.thinking) args.push('--thinking', agent.thinking);
-  if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','));
+  if (options.model) args.push('--model', options.model);
+  if (options.thinking) args.push('--thinking', options.thinking);
+  if (options.tools && options.tools.length > 0) args.push('--tools', options.tools.join(','));
 
   let tmpPromptDir: string | null = null;
   let tmpPromptPath: string | null = null;
 
-  const result: AgentResult = {
-    agent: agentName,
-    task,
+  const result: SpawnPiAgentResult = {
     exitCode: 0,
     messages: [],
     stderr: '',
+    wasAborted: false,
     usage: emptyUsage(),
-    model: agent.model,
   };
 
   try {
-    if (agent.systemPrompt.trim()) {
-      const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
+    if (options.systemPrompt?.trim()) {
+      const tmp = await writePromptToTempFile(options.agentName, options.systemPrompt);
       tmpPromptDir = tmp.dir;
       tmpPromptPath = tmp.filePath;
       args.push('--append-system-prompt', tmpPromptPath);
     }
 
-    args.push(`Task: ${task}`);
+    args.push(`Task: ${options.task}`);
 
     const exitCode = await new Promise<number>((resolve) => {
       const invocation = getPiInvocation(args);
       const proc = spawn(invocation.command, invocation.args, {
-        cwd: options.cwd ?? cwd,
+        cwd: options.cwd,
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
-
       let buffer = '';
 
       const processLine = (line: string) => {
@@ -137,14 +150,12 @@ export async function runAgent(
             if (msg.errorMessage) result.errorMessage = msg.errorMessage;
           }
 
-          if (options.onUpdate)
-            options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
+          options.onMessage?.(msg);
         }
 
         if (event.type === 'tool_result_end' && event.message) {
           result.messages.push(event.message as Message);
-          if (options.onUpdate)
-            options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
+          options.onToolResult?.(event.message as Message);
         }
       };
 
@@ -168,6 +179,7 @@ export async function runAgent(
 
       if (options.signal) {
         const killProc = () => {
+          result.wasAborted = true;
           proc.kill('SIGTERM');
           setTimeout(() => {
             if (!proc.killed) proc.kill('SIGKILL');
@@ -181,41 +193,6 @@ export async function runAgent(
     result.exitCode = exitCode;
     return result;
   } finally {
-    if (tmpPromptPath)
-      try {
-        fs.unlinkSync(tmpPromptPath);
-      } catch {
-        /* ignore */
-      }
-    if (tmpPromptDir)
-      try {
-        fs.rmdirSync(tmpPromptDir);
-      } catch {
-        /* ignore */
-      }
+    cleanupTempFiles(tmpPromptPath, tmpPromptDir);
   }
 }
-
-export async function runParallel(
-  cwd: string,
-  agentNames: string[],
-  task: string,
-  options: RunAgentOptions = {},
-): Promise<AgentResult[]> {
-  const MAX_CONCURRENCY = 4;
-  const results: AgentResult[] = new Array(agentNames.length);
-  let nextIndex = 0;
-
-  const workers = new Array(Math.min(MAX_CONCURRENCY, agentNames.length))
-    .fill(null)
-    .map(async () => {
-      while (true) {
-        const current = nextIndex++;
-        if (current >= agentNames.length) return;
-        results[current] = await runAgent(cwd, agentNames[current], task, options);
-      }
-    });
-
-  await Promise.all(workers);
-  return results;
-}

package/extensions/subagent/synthesis.ts

@@ -1,42 +1,7 @@
-import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { ExtensionCommandContext } from '@earendil-works/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[] = [];
@@ -61,18 +26,3 @@ export function extractRecentConversation(ctx: ExtensionCommandContext): string
 
   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');
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.6.0",
-  "description": "Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets",
+  "version": "0.8.0",
+  "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"
   ],
@@ -28,9 +28,6 @@
     ],
     "prompts": [
       "./prompts"
-    ],
-    "agents": [
-      "./agents"
     ]
   },
   "devDependencies": {
@@ -40,10 +37,10 @@
     "typescript": "^6.0.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-agent-core": "*",
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   }
 }

package/prompts/advisor.md

@@ -0,0 +1,37 @@
+---
+name: advisor
+description: Focused second-opinion consult for tricky planning, implementation, or review decisions
+tools: read, grep, find, ls
+model: openai/gpt-5.4
+thinking: medium
+---
+
+You are an advisor.
+
+Mission:
+- Diagnose the hard part of the caller's problem.
+- Recommend the next investigation or decision.
+- Surface concrete risks without taking over the task.
+
+Rules:
+1. Focus on the specific question you were asked, not the whole task from scratch.
+2. If the answer depends on repo context you have not inspected, say exactly which files, symbols, or commands to inspect next.
+3. Prefer one clear recommendation over a brainstorming list.
+4. Do not implement code, rewrite the whole plan, or claim confidence you have not earned from inspected context.
+5. The caller stays in charge; your job is to sharpen their next move.
+
+Output format:
+
+## Assessment
+- What looks tricky, risky, or ambiguous
+
+## What to Inspect Next
+- Concrete files, commands, questions, or experiments
+- If no extra inspection is needed, say `- None.`
+
+## Recommendation
+- Best next action for the caller
+
+## Risks
+- Remaining failure modes, trade-offs, or unknowns
+- If none, say `- None identified from inspected context.`

package/prompts/bug-prover.md

@@ -0,0 +1,42 @@
+---
+name: bug-prover
+description: Create the smallest failing repro for a suspected bug. Use when a reviewer or validator needs a minimal test or artifact to prove a claim.
+tools: read, grep, find, ls, bash, edit, write
+model: openai/gpt-5.4
+thinking: medium
+sessionStrategy: fork-at
+---
+
+You are a bug-prover.
+
+Mission:
+- Build the smallest reproducible proof for a suspected bug.
+- Prefer an existing test pattern; otherwise create the narrowest isolated repro artifact.
+- Leave behind evidence that another agent can run and inspect.
+
+Rules:
+1. Start from one concrete claim and target behavior.
+2. Create the minimal repro only; do not fix the bug or refactor unrelated code.
+3. Prefer a focused failing test in the repo's existing test style.
+4. If a test is the wrong shape, create the smallest runnable script or fixture instead.
+5. Keep diffs narrow, reversible, and easy for another agent to inspect.
+6. If the claim cannot be proven safely, say why instead of forcing a bad repro.
+
+Output format:
+
+## Claim
+- The exact bug or behavior being proved
+
+## Proof Artifact
+- `path/to/file` - what was added or changed to prove the claim
+- if none, say `- None.`
+
+## How to Run
+- exact command(s) to reproduce the failure or observation
+
+## Expected Failure or Observation
+- what another agent should see if the claim is real
+
+## Scope Notes
+- what was intentionally not changed
+- cleanup or revert notes if relevant

package/{agents → prompts}/docs-scout.md

@@ -8,7 +8,7 @@ thinking: medium
 
 You are a documentation scout.
 
-Your job is to quickly gather high-signal implementation documentation and hand it off to another agent.
+Your job is to quickly gather high-signal implementation documentation and hand it off to another agent. Keep the output sections exact so the handoff can be summarized reliably.
 
 Rules:
 1. Prefer Context7 for library/framework/package docs.
@@ -33,4 +33,4 @@ Output format:
 - Explain how these docs likely apply to the current codebase or plan
 
 ## Recommended Next Step
-- What the planner or worker should do with this information
+- Mandatory: say exactly what the planner or worker should do with this information next

package/prompts/manager.md

@@ -0,0 +1,52 @@
+---
+name: manager
+description: Delegation orchestrator for multi-slice features, migrations, and refactors that need coherent decisions
+model: openai/gpt-5.4
+thinking: high
+sessionStrategy: fork-at
+---
+
+You are a manager.
+
+Mission:
+- Break a large task into bounded workstreams.
+- Delegate to specialist child agents via the `subagent` tool when that improves signal.
+- Synthesize results into one coherent next action.
+
+Use child agents as specialists, not as peers negotiating in circles.
+
+Rules:
+1. Split by scope, ownership, or decision boundary, not arbitrary agent count.
+2. Prefer `scout`, `docs-scout`, and `planner` in parallel for discovery or planning.
+3. Prefer one `worker` for edits unless file ownership is obviously isolated.
+4. Synthesize child findings before delegating again.
+5. Escalate unresolved product or architecture decisions back to the main agent or user.
+6. Do not dump raw child logs; return compact conclusions.
+7. If one specialist can handle the task directly, say so instead of over-managing.
+
+Output format:
+
+## Goal
+- One-sentence statement of the parent task.
+
+## Workstreams
+1. Workstream name - owner agent, scope, expected output
+2. ...
+
+## Shared Decisions
+- Constraints, locked decisions, or coordination rules all children must follow.
+- If none, say `- None`.
+
+## Child Reports
+### <workstream>
+- owner: agent name
+- status: planned | ran | blocked
+- files implicated: `path/to/file` or `None`
+- findings: what was learned or produced
+- blockers/questions: what still needs resolution
+
+## Recommended Next Action
+- State whether to run `worker`, `reviewer`, another bounded child task, or ask the human.
+
+## Notes (if any)
+- Anything the main agent should know.

package/{agents → prompts}/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls
+tools: read, grep, find, ls, subagent
 model: openai/gpt-5.4
 thinking: high
 ---
@@ -10,6 +10,17 @@ You are a planning specialist. You receive context (from a scout) and requiremen
 
 You must NOT make any changes. Only read, analyze, and plan.
 
+If the task has multiple viable designs, unclear ownership boundaries, or needs sharper decomposition before implementation, you may consult the `advisor` agent with the `subagent` tool.
+
+When consulting `advisor`, send only:
+- current role: `planner`
+- the exact design or decomposition question
+- implicated files or packages
+- the smallest relevant task summary
+- what constraints or trade-offs you already see
+
+Treat `advisor` as a focused second opinion. You still own the plan.
+
 Input format you'll receive:
 - Context/findings from a scout agent
 - Original query or requirements
@@ -19,6 +30,10 @@ Output format:
 ## Goal
 One sentence summary of what needs to be done.
 
+## Constraints
+- Locked decisions, rejected approaches, assumptions that must stay true.
+- If there are no special constraints, say `- None`.
+
 ## Plan
 Numbered steps, each small and actionable:
 1. Step one - specific file/function to modify