@ilya-lesikov/pi-pi 0.3.0 → 0.4.0

package/extensions/orchestrator/agents/brainstorm-reviewer.ts

@@ -51,7 +51,10 @@ export function createBrainstormReviewerAgent(
       "- SUGGESTIONS: (improvements, not required)",
       "- VERDICT: APPROVE or NEEDS_WORK (with reason)",
       "",
-      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
+    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple Explore agents in parallel for broad searches.",
       "",
       "# MANDATORY: Write your review to this exact file using the write tool:",
       `  ${outputPath}`,

package/extensions/orchestrator/agents/code-reviewer.ts

@@ -65,7 +65,10 @@ export function createCodeReviewerAgent(
       "- OPEN QUESTIONS: (low-confidence concerns, speculative follow-ups)",
       "- VERDICT: APPROVE or NEEDS_CHANGES",
       "",
-      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
+    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple Explore agents in parallel for broad searches.",
       "",
       // --- dynamic suffix ---
       "# MANDATORY: Write your review to this exact file using the write tool:",

package/extensions/orchestrator/agents/plan-reviewer.ts

@@ -51,7 +51,10 @@ export function createPlanReviewerAgent(
       "- SUGGESTIONS: (improvements, not required)",
       "- VERDICT: APPROVE or REJECT (with reason)",
       "",
-      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
+    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple Explore agents in parallel for broad searches.",
       "",
       // --- dynamic suffix ---
       "# MANDATORY OUTPUT",

package/extensions/orchestrator/agents/planner.ts

@@ -40,7 +40,10 @@ export function createPlannerAgent(
       "- No other top-level sections allowed",
       "- Describe outcomes, not code-level mechanics",
       "",
-      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
+    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple Explore agents in parallel for broad searches.",
       "",
       // --- dynamic suffix ---
       "# MANDATORY OUTPUT",

package/extensions/orchestrator/agents/task.ts

@@ -28,8 +28,10 @@ export function createTaskAgent(
       FAILURE_RECOVERY,
       "",
       "# Constraints",
-      "- Do NOT spawn task subagents (no recursion)",
-      '- You CAN spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs',
+    "- Do NOT spawn task subagents (no recursion)",
+    "- subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
+    '  Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '  Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
       "- Focus only on your subtask — do not modify unrelated code",
       "- Before modifying a function, use lsp findReferences to understand all callers",
       "- After editing files, run lsp diagnostics and fix errors before moving on",

package/extensions/orchestrator/command-handlers.ts

@@ -109,7 +109,7 @@ export function registerCommandHandlers(orchestrator: Orchestrator): void {
       const { showPpMenu } = await import("./pp-menu.js");
       const text = await showPpMenu(orchestrator, ctx, "command");
       if (text) {
-        pi.sendUserMessage(`[PI-PI] ${text}`);
+        pi.sendUserMessage(`[PI-PI] ${text}`, { deliverAs: "followUp" });
       }
     },
   });

package/extensions/orchestrator/event-handlers.ts

@@ -943,7 +943,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (event.toolName === "Agent" && orchestrator.active) {
       const input = event.input as Record<string, unknown>;
       const requestedType = ((input.subagent_type as string) || "").toLowerCase();
-      const isExplore = !requestedType || requestedType === "explore";
+      if (!requestedType) {
+        return { block: true, reason: "subagent_type is required. Use Explore for codebase research, Librarian for external docs, or Task for implementation subtasks." };
+      }
+      const isExplore = requestedType === "explore";
       const isLibrarian = requestedType === "librarian";
 
       if (isExplore) {
@@ -1183,7 +1186,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         orchestrator.pendingRetryTimer = setTimeout(() => {
           orchestrator.pendingRetryTimer = null;
           if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
-          pi.sendUserMessage(`[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`);
+          pi.sendUserMessage(`[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`, { deliverAs: "followUp" });
         }, delay);
       } else {
         ctx.ui.notify(`API error persisted after 3 retries: ${errorMsg}. Stopping auto-retry.`, "error");
@@ -1218,7 +1221,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
                 orchestrator.pendingSubagentSpawns = 0;
                 orchestrator.active.state.step = "synthesize";
                 saveTask(orchestrator.active.dir, orchestrator.active.state);
-                pi.sendUserMessage("[PI-PI] All planners completed. Read their outputs and synthesize the plan.");
+                pi.sendUserMessage("[PI-PI] All planners completed. Read their outputs and synthesize the plan.", { deliverAs: "followUp" });
               }
             }
           } else if (orchestrator.active.state.step === "await_reviewers" && orchestrator.active.state.reviewCycle) {
@@ -1249,7 +1252,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
                 { customType: "pp-review-ready", content: `[PI-PI] Reviewer outputs are ready.\n\n${rendered}`, display: false },
                 { deliverAs: "followUp" },
               );
-              pi.sendUserMessage("[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.");
+              pi.sendUserMessage("[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.", { deliverAs: "followUp" });
             }
           } else {
             clearInterval(orchestrator.awaitPollTimer!);

package/extensions/orchestrator/orchestrator.ts

@@ -344,7 +344,7 @@ export class Orchestrator {
     } else if (isWaitingForPlanners) {
       ctx.ui.notify("Entered plan phase. Waiting for planners to complete before synthesis.", "info");
     } else {
-      this.pi.sendUserMessage(`[PI-PI] Entered ${this.active.state.phase} phase. Begin working.`);
+      this.pi.sendUserMessage(`[PI-PI] Entered ${this.active.state.phase} phase. Begin working.`, { deliverAs: "followUp" });
     }
 
     if (this.active.state.phase === "plan" && this.active.state.step === "await_planners") {
@@ -484,7 +484,7 @@ export class Orchestrator {
         if (this.active?.state.phase === "plan" && this.active.state.step === "await_planners") {
           ctx.ui.notify("Entered plan phase. Waiting for planners to complete before synthesis.", "info");
         } else {
-          this.pi.sendUserMessage(`[PI-PI] Entered ${phase} phase. Begin working.`);
+          this.pi.sendUserMessage(`[PI-PI] Entered ${phase} phase. Begin working.`, { deliverAs: "followUp" });
         }
       },
       onError: (err) => {
@@ -503,7 +503,7 @@ export class Orchestrator {
         if (this.active?.state.phase === "plan" && this.active.state.step === "await_planners") {
           ctx.ui.notify("Entered plan phase. Waiting for planners to complete before synthesis.", "info");
         } else {
-          this.pi.sendUserMessage(`[PI-PI] Entered ${phase} phase. Begin working.`);
+          this.pi.sendUserMessage(`[PI-PI] Entered ${phase} phase. Begin working.`, { deliverAs: "followUp" });
         }
       },
     });

package/extensions/orchestrator/phases/brainstorm.ts

@@ -22,7 +22,11 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     "# Your job:",
     "1. Clarify the problem with the user if needed",
-    '2. Spawn explore subagents via Agent(subagent_type="Explore", ...) for codebase research',
+    "2. Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
+    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups.',
+    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
+    "   Explore is fast and cheap. Use it liberally for codebase questions. Spawn multiple in parallel.",
     "3. Use bash to run commands, check logs, reproduce issues",
     "4. Use tools to trace the bug:",
     "   - cbm_search/cbm_search_code: find relevant code by concept or text",
@@ -31,8 +35,6 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "   - lsp diagnostics: find type errors",
     "   - cbm_trace: trace call chains to/from suspect functions",
     "   - ast_search: find structural patterns (e.g. error handling, goroutines)",
-      "",
-      "IMPORTANT: Always specify subagent_type. Use Explore for codebase, Librarian for external docs.",
       "",
       "Produce two files:",
       `- ${taskDir}/USER_REQUEST.md — the fix request. MUST follow this exact structure:`,
@@ -76,8 +78,11 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "",
       "# How to work:",
       "- Discuss the topic with the user. Ask clarifying questions. Propose approaches. Analyze tradeoffs.",
-      '- Spawn subagents for research: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
-      "  IMPORTANT: Always specify subagent_type. Do NOT omit it.",
+    "- Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
+    '  Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '  Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    '  Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
+    "  Spawn multiple Explore agents in parallel for broad searches.",
       "- Use tools directly for quick lookups (cbm_search, lsp, ast_search, grep, etc.)",
       "- Present findings to the user and discuss them. Don't just dump raw results.",
       "- Do NOT modify project source code.",
@@ -120,18 +125,19 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     "# Steps:",
     "1. Clarify requirements with the user if anything is ambiguous",
-    '2. Spawn explore subagents via Agent(subagent_type="Explore", ...) for codebase research',
-    '3. Spawn librarian subagents via Agent(subagent_type="Librarian", ...) for external docs/library research',
-    "4. Use tools to understand code structure:",
+    "2. Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
+    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
+    "   Spawn multiple Explore agents in parallel for broad searches.",
+    "3. Use tools to understand code structure:",
     "   - cbm_search: natural-language search across all symbols",
     "   - cbm_search_code: graph-augmented grep (deduplicates into functions)",
     "   - lsp documentSymbol, goToDefinition, findReferences, goToImplementation, hover",
     "   - cbm_trace: trace call chains for dependency understanding",
     "   - ast_search: find structural patterns across the codebase",
-    "5. Ask the user follow-up questions as needed",
-    "6. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
-    "",
-    "IMPORTANT: Always specify subagent_type. Use Explore for codebase, Librarian for external docs.",
+    "4. Ask the user follow-up questions as needed",
+    "5. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
     "",
     "Produce two files:",
     `- ${taskDir}/USER_REQUEST.md — MUST follow this exact structure:`,

package/extensions/orchestrator/phases/implementation.ts

@@ -22,9 +22,11 @@ export function implementationSystemPrompt(taskDir: string): string {
     "   - cbm_trace: trace dependencies across the codebase",
     "   - ast_search: find structural patterns (e.g. error handling conventions)",
     "6. After completing changes, run cbm_changes to verify blast radius",
-    '7. For parallelizable, self-contained subtasks, delegate via Agent(subagent_type="Task", ...)',
-    '8. For codebase research, use Agent(subagent_type="Explore", ...)',
-    '9. For external docs research, use Agent(subagent_type="Librarian", ...)',
+    "7. Spawn subagents as needed (subagent_type is REQUIRED — calls without it are rejected):",
+    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    '   - Agent(subagent_type="Task", ...) — parallelizable, self-contained implementation subtasks.',
+    "   Spawn multiple Explore agents in parallel for broad searches.",
     "",
     "If a fix fails 3 times, STOP and re-plan the approach — do not keep pushing.",
     "",

package/extensions/orchestrator/phases/review-task.ts

@@ -10,6 +10,11 @@ export function reviewSystemPrompt(taskDir: string): string {
     "- read, lsp, grep, find for understanding the code",
     "- gh pr view for GitHub PR context if a PR URL is mentioned",
     "",
+    "Spawn subagents as needed (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple Explore agents in parallel for broad searches.",
+    "",
     "Write your findings:",
     `- ${taskDir}/USER_REQUEST.md — update with a clear problem statement of issues found`,
     `- ${taskDir}/RESEARCH.md — detailed technical analysis`,

package/extensions/orchestrator/pp-menu.ts

@@ -344,9 +344,9 @@ export async function resumeTask(
   if (step === "await_planners" || step === "await_reviewers") {
     ctx.ui.notify(`Resumed task. Awaiting subagents (${step}).`, "info");
   } else if (step === "apply_feedback") {
-    pi.sendUserMessage(`[PI-PI] Resumed ${orchestrator.active.state.phase} phase. Read reviewer outputs and apply feedback.`);
+    pi.sendUserMessage(`[PI-PI] Resumed ${orchestrator.active.state.phase} phase. Read reviewer outputs and apply feedback.`, { deliverAs: "followUp" });
   } else {
-    pi.sendUserMessage(`[PI-PI] Resumed ${orchestrator.active.state.phase} phase. Continue working.`);
+    pi.sendUserMessage(`[PI-PI] Resumed ${orchestrator.active.state.phase} phase. Continue working.`, { deliverAs: "followUp" });
   }
 
   return { ok: true };
@@ -591,6 +591,9 @@ function showUsage(ctx: any): void {
         getTotalInputTokens(): number; getTotalOutputTokens(): number;
         getTotalCacheReadTokens(): number; getTotalCacheWriteTokens(): number;
         getTotalCost(): number; getCacheHitRate(): number;
+        getMainInputTokens(): number; getMainOutputTokens(): number;
+        getMainCacheReadTokens(): number; getMainCacheWriteTokens(): number;
+        getMainCost(): number;
         getPerModelUsage(): Record<string, { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; turns: number }>;
         getSubagentList(): Array<{ description: string; agentType: string; modelId: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; cost: number; durationMs: number; toolUses: number }>;
       }
@@ -601,31 +604,21 @@ function showUsage(ctx: any): void {
     return;
   }
 
-  const mainInput = tracker.getTotalInputTokens();
-  const mainOutput = tracker.getTotalOutputTokens();
-  const mainCacheRead = tracker.getTotalCacheReadTokens();
-  const mainCacheWrite = tracker.getTotalCacheWriteTokens();
-  const mainCost = tracker.getTotalCost();
-  const models = tracker.getPerModelUsage();
-  const subagents = tracker.getSubagentList();
-
-  let saInput = 0, saOutput = 0, saCacheRead = 0, saCacheWrite = 0, saCost = 0;
-  for (const sa of subagents) {
-    saInput += sa.inputTokens;
-    saOutput += sa.outputTokens;
-    saCacheRead += sa.cacheReadTokens;
-    saCacheWrite += sa.cacheWriteTokens;
-    saCost += sa.cost;
-  }
-
-  const totalInput = mainInput + saInput;
-  const totalOutput = mainOutput + saOutput;
-  const totalCacheRead = mainCacheRead + saCacheRead;
-  const totalCost = mainCost + saCost;
+  const totalInput = tracker.getTotalInputTokens();
+  const totalOutput = tracker.getTotalOutputTokens();
+  const totalCacheRead = tracker.getTotalCacheReadTokens();
+  const totalCost = tracker.getTotalCost();
   const totalCacheRate = (totalCacheRead + totalInput) > 0
     ? totalCacheRead / (totalCacheRead + totalInput)
     : 0;
 
+  const mainInput = tracker.getMainInputTokens();
+  const mainOutput = tracker.getMainOutputTokens();
+  const mainCacheRead = tracker.getMainCacheReadTokens();
+  const mainCost = tracker.getMainCost();
+  const models = tracker.getPerModelUsage();
+  const subagents = tracker.getSubagentList();
+
   const byModel = new Map<string, { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }>();
   const mainModelEntries = Object.entries(models);
   const mainTotalTokens = mainModelEntries.reduce((s, [, u]) => s + u.inputTokens + u.outputTokens, 0);

package/extensions/orchestrator/usage-tracker.ts

@@ -19,6 +19,11 @@ export interface UsageTracker {
   getTotalCacheReadTokens(): number;
   getTotalCacheWriteTokens(): number;
   getTotalCost(): number;
+  getMainInputTokens(): number;
+  getMainOutputTokens(): number;
+  getMainCacheReadTokens(): number;
+  getMainCacheWriteTokens(): number;
+  getMainCost(): number;
   getCacheHitRate(): number;
   getPerModelUsage(): Record<string, ModelUsage>;
   getSubagentTotals(): { inputTokens: number; outputTokens: number; cost: number };
@@ -203,11 +208,11 @@ export function createUsageTracker(): UsageTracker {
     },
 
     getTotalInputTokens(): number {
-      return state.totalInputTokens;
+      return state.totalInputTokens + state.subagentInputTokens;
     },
 
     getTotalOutputTokens(): number {
-      return state.totalOutputTokens;
+      return state.totalOutputTokens + state.subagentOutputTokens;
     },
 
     getTotalCacheReadTokens(): number {
@@ -219,13 +224,35 @@ export function createUsageTracker(): UsageTracker {
     },
 
     getTotalCost(): number {
+      return state.totalCost + state.subagentCost;
+    },
+
+    getMainInputTokens(): number {
+      return state.totalInputTokens;
+    },
+
+    getMainOutputTokens(): number {
+      return state.totalOutputTokens;
+    },
+
+    getMainCacheReadTokens(): number {
+      return state.totalCacheReadTokens;
+    },
+
+    getMainCacheWriteTokens(): number {
+      return state.totalCacheWriteTokens;
+    },
+
+    getMainCost(): number {
       return state.totalCost;
     },
 
     getCacheHitRate(): number {
-      const denominator = state.totalCacheReadTokens + state.totalInputTokens;
+      const totalInput = state.totalInputTokens + state.subagentInputTokens;
+      const totalCacheRead = state.totalCacheReadTokens;
+      const denominator = totalCacheRead + totalInput;
       if (denominator <= 0) return 0;
-      return state.totalCacheReadTokens / denominator;
+      return totalCacheRead / denominator;
     },
 
     getPerModelUsage(): Record<string, ModelUsage> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilya-lesikov/pi-pi",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pi-Pi Coding Agent: based on Pi Coding Agent, but twice as good",
   "keywords": [
     "pi-package",