@ilya-lesikov/pi-pi 0.6.0 → 0.8.0

package/extensions/orchestrator/event-handlers.ts

@@ -14,17 +14,20 @@ import {
   loadAllContextFiles,
   getPhaseArtifacts,
   getLatestSynthesizedPlan,
+  getArtifactManifest,
   loadBrainstormReviewOutputs,
   loadCodeReviewOutputs,
   loadPlanReviewOutputs,
 } from "./context.js";
-import { PRINCIPLES_BLOCK, TOOLS_BLOCK } from "./agents/tool-routing.js";
+import { PRINCIPLES_BLOCK, TOOLS_BLOCK, DELEGATION_BLOCK } from "./agents/tool-routing.js";
 import { constraintsBlock, phaseConstraint } from "./agents/constraints.js";
 import { registerCbmTools } from "./cbm.js";
 import { registerExaTools } from "./exa.js";
 import { registerAstSearchTool } from "./ast-search.js";
 import { SUBAGENT_SESSION_KEY } from "./index.js";
 import { registerCommandHandlers } from "./command-handlers.js";
+import { registerStateFileTools } from "./pp-state-tools.js";
+import { handleMainRateLimit, handleSubagentRateLimit, isRateLimitError, isSdkRetryableError } from "./rate-limit-fallback.js";
 import { setExtensionOnlyMode, unregisterAgentDefinitions } from "./agents/registry.js";
 import { resolveModel, getModelInfo, updateRegistryFromAvailableModels } from "./model-registry.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
@@ -33,9 +36,10 @@ import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
 import { reviewPassUnanimousApprove } from "./phases/verdict.js";
 import { validateExitCriteria } from "./phases/machine.js";
 import { openPlannotator, waitForPlannotatorResult, cancelPendingPlannotatorWait } from "./plannotator.js";
+import { advanceBanner } from "./messages.js";
 import { Orchestrator, type ActiveTask } from "./orchestrator.js";
 import { createCustomFooter, setFooterContext, setFooterTracker } from "./custom-footer.js";
-import { createUsageTracker, dumpUsageSummary, loadUsageSummary, type UsageTracker } from "./usage-tracker.js";
+import { createUsageTracker, dumpUsageSummary, loadUsageSummary, isSubscriptionRouted, type UsageTracker } from "./usage-tracker.js";
 import { askUser, isCancel } from "../../3p/pi-ask-user/index.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { findRootRepo, normalizeRepoPath, resolveRepoForFile, type RepoInfo } from "./repo-utils.js";
@@ -51,6 +55,34 @@ function isPathInside(basePath: string, targetPath: string): boolean {
   return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
 
+// Builds the spawn-time context block appended to a free agent's spawn prompt:
+// inlines USER_REQUEST + RESEARCH (always present by spawn time) and appends a
+// path-aware manifest of additional on-demand documents (artifacts + plan).
+function buildSpawnContextBlock(taskDir: string): string {
+  const parts: string[] = [];
+
+  const userRequestPath = join(taskDir, "USER_REQUEST.md");
+  if (existsSync(userRequestPath)) {
+    parts.push("=== USER REQUEST ===\n" + readFileSync(userRequestPath, "utf-8").trimEnd());
+  }
+  const researchPath = join(taskDir, "RESEARCH.md");
+  if (existsSync(researchPath)) {
+    parts.push("=== RESEARCH ===\n" + readFileSync(researchPath, "utf-8").trimEnd());
+  }
+
+  const manifest = getArtifactManifest(taskDir);
+  if (manifest.length > 0) {
+    const lines = manifest.map((m) => `- ${m.path}  — ${m.title}`);
+    parts.push(
+      "=== ADDITIONAL DOCUMENTS (read from disk if relevant) ===\n" +
+        lines.join("\n") +
+        "\nDo NOT re-read USER_REQUEST/RESEARCH from disk (already above).",
+    );
+  }
+
+  return parts.join("\n\n");
+}
+
 export async function detectDefaultBranch(orchestrator: Orchestrator, repos: RepoInfo[], repoPath: string): Promise<string> {
   const normalizedPath = normalizeRepoPath(repoPath);
   const repo = repos.find((r) => r.path === normalizedPath);
@@ -206,14 +238,21 @@ function tryCompleteReviewCycle(orchestrator: Orchestrator, spawnedReviewers?: n
     },
     "instruction",
   );
-  orchestrator.safeSendUserMessage(reviewReadyMessage(phase));
+  orchestrator.safeSendUserMessage(advanceBanner(reviewReadyMessage(phase, getEffectivePhaseMode(orchestrator.active.state))));
 }
 
-function reviewReadyMessage(phase: string): string {
+function reviewReadyMessage(phase: string, mode: TaskMode): string {
   if (phase === "brainstorm") {
     return "[PI-PI] Review cycle is ready for apply_feedback. The reviewers assessed your artifacts (USER_REQUEST.md, RESEARCH.md, and artifacts/), not a code diff. Read their outputs and update those artifacts as needed.";
   }
-  return "[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.";
+  // Only autonomous plan/implement auto-advance: those must re-call
+  // pp_phase_complete to finalize the pass and transition. Guided phases
+  // (including debug and the interactive review phase) stay user-driven, so
+  // they get neutral wording with no re-call/auto-advance directive.
+  if (mode === "autonomous") {
+    return "[PI-PI] Review cycle is ready for apply_feedback. Read the reviewer outputs, apply any required changes, then call pp_phase_complete again to finalize this review pass and advance the phase. Do NOT stop or wait for the user — the phase is NOT complete until you re-call pp_phase_complete.";
+  }
+  return "[PI-PI] Review cycle is ready for apply_feedback. Read the reviewer outputs and apply any required changes.";
 }
 
 export async function enterReviewCycle(
@@ -414,6 +453,7 @@ function registerOrchestratorTools(orchestrator: Orchestrator): void {
   registerPhaseCompleteTool(orchestrator);
   registerCommitTool(orchestrator);
   registerSpecifyReviewsTool(orchestrator);
+  registerStateFileTools(orchestrator);
 }
 
 function registerRepoTool(orchestrator: Orchestrator): void {
@@ -555,24 +595,24 @@ function registerRepoTool(orchestrator: Orchestrator): void {
   });
 }
 
-function openCodeReviewDirect(
-  pi: ExtensionAPI,
+async function openCodeReviewDirect(
+  orchestrator: Orchestrator,
   payload: Record<string, unknown>,
 ): Promise<{ approved: boolean; feedback?: string } | { error: string }> {
-  return new Promise((resolve) => {
-    pi.events.emit("plannotator:request", {
-      requestId: crypto.randomUUID(),
-      action: "code-review",
-      payload,
-      respond: (response: any) => {
-        if (response.status === "handled") {
-          resolve({ approved: !!response.result?.approved, feedback: response.result?.feedback });
-        } else {
-          resolve({ error: response.error || "Plannotator not available" });
-        }
-      },
-    });
-  });
+  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", payload);
+  if (!opened) {
+    return { error: "Plannotator not available" };
+  }
+  let result: { approved: boolean; feedback?: string; error?: string };
+  try {
+    result = await waitForPlannotatorResult(orchestrator, reviewId, null);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "Plannotator review failed" };
+  }
+  if (result.error) {
+    return { error: result.error };
+  }
+  return { approved: result.approved, feedback: result.feedback };
 }
 
 function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
@@ -664,7 +704,7 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
           continue;
         }
 
-        const result = await openCodeReviewDirect(pi, {
+        const result = await openCodeReviewDirect(orchestrator, {
           cwd: reviewCwd,
           diffType: "branch",
           defaultBranch: compareBase,
@@ -713,8 +753,14 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
 
       ctx.ui?.setWorkingMessage?.("Waiting for user input…");
       try {
-        const { showActiveTaskMenu } = await import("./pp-menu.js");
+        const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
         const text = await showActiveTaskMenu(orchestrator, ctx, `Plannotator review complete.\n\n${summary}`, "tool");
+        // Deliberate user ESC: stop the turn cleanly (mirror ask_user), no
+        // reminder text that would start a new LLM turn.
+        if (text === USER_CANCELLED) {
+          ctx.abort?.();
+          return { content: [{ type: "text" as const, text: "" }], details: {} };
+        }
         // A transition may have started while the menu was open. The controller
         // is the source of truth; abort the agent's pending turn so it doesn't
         // race the transition. (Interactive-UX abort — stays local, not routed.)
@@ -840,7 +886,10 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
         const count = orchestrator.spawnedAgentIds.size + orchestrator.pendingSubagentSpawns;
         return { content: [{ type: "text" as const, text: `${count} subagent(s) still running. Wait for them to complete before calling pp_phase_complete.` }], isError: true as const, details: {} };
       }
-      const effectiveMode = getEffectiveMode(orchestrator.active.state);
+      // Gate on the effective PHASE mode, not the task mode: brainstorm/debug/
+      // review are always user-driven even for an autonomous task, so they must
+      // fall through to the guided menu path below rather than auto-advancing.
+      const effectiveMode = getEffectivePhaseMode(orchestrator.active.state);
       if (effectiveMode === "autonomous") {
         const phase = orchestrator.active.state.phase;
         let justFinalizedReviewCycle = false;
@@ -908,8 +957,16 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
       }
       ctx.ui.setWorkingMessage?.("Waiting for user approval…");
       try {
-        const { showActiveTaskMenu } = await import("./pp-menu.js");
+        const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
         const text = await showActiveTaskMenu(orchestrator, ctx, params.summary, "tool");
+        // A deliberate user ESC on the menu means "stop cleanly, let me type" —
+        // mirror ask_user: abort the turn and return nothing so no new LLM turn
+        // starts. This takes precedence over the reminder path below, in ALL
+        // interactive cases (including while a transition is mid-flight).
+        if (text === USER_CANCELLED) {
+          ctx.abort?.();
+          return { content: [{ type: "text" as const, text: "" }], details: {} };
+        }
         // A transition or await may have started while the menu was open. The
         // controller is the source of truth; abort the pending turn so it can't
         // race. (Interactive-UX abort — stays local, not routed.)
@@ -923,6 +980,8 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
           return { content: [{ type: "text" as const, text: "" }], details: {} };
         }
         if (!text) {
+          // Non-ESC dismissal (explicit "Back") while a transition is running:
+          // keep the intentional artifact-update reminder (commit 10e7021).
           return { content: [{ type: "text" as const, text: "User dismissed the menu. Wait for the user's next message. When you resume work, update USER_REQUEST.md and RESEARCH.md with any new findings before calling pp_phase_complete." }], details: {} };
         }
         return { content: [{ type: "text" as const, text }], details: {} };
@@ -993,6 +1052,21 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
   registerMainTraceHooks(orchestrator);
 
+  // Personal-subscription Claude routing registers the sub provider with a
+  // literal OAuth token (a static snapshot). That token expires within a few
+  // hours, so a long-lived session would keep sending a stale token and the
+  // gateway would return 401. Refresh (and re-register on change) before each
+  // turn's LLM call. Cheap no-op when subscription routing is inactive or the
+  // token is unchanged. registerEventHandlers runs only on the root session.
+  pi.on("turn_start", async () => {
+    try {
+      const { refreshSubProvider } = await import("./flant-infra.js");
+      await refreshSubProvider(pi);
+    } catch (err: any) {
+      getLogger().debug({ s: "flant", err: err?.message }, "sub provider refresh failed");
+    }
+  });
+
   // TransitionController drivers. These are the reliable idle/completion signals:
   //   - agent_end: the main loop went idle. If a transition is pending, this is
   //     when the controller fires compaction.
@@ -1127,6 +1201,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (data.description) {
       orchestrator.agentDescriptions.set(data.id, data.description);
     }
+
     trackSubagentEvent(data, "created");
     startStaleAgentWatchdog();
     const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
@@ -1173,7 +1248,14 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
     const failedPlannerVariants = [...orchestrator.failedPlannerVariants];
     const effectiveMode = getEffectiveMode(orchestrator.active.state);
-    if (effectiveMode === "autonomous" && failedPlannerVariants.length > 0) {
+    // Do NOT auto-retry failed variants while a subscription-429 fallback decision
+    // is in flight: re-spawning now would use the still-sub-routed model and
+    // re-hit the limit. Once the user decides, the fallback nudge re-drives this.
+    if (
+      effectiveMode === "autonomous" &&
+      failedPlannerVariants.length > 0 &&
+      !orchestrator.subFallbackPendingDecision
+    ) {
       const alreadyRetried = orchestrator.active.state.plannerFailureAutoRetried === true;
       if (!alreadyRetried) {
         const failedSet = new Set(failedPlannerVariants);
@@ -1345,7 +1427,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
     const failedReviewerVariants = [...orchestrator.failedReviewerVariants];
     const effectiveMode = getEffectiveMode(orchestrator.active.state);
-    if (effectiveMode === "autonomous" && failedReviewerVariants.length > 0) {
+    // See the planner path: suppress auto-retry while a sub-429 fallback decision
+    // is pending so we don't re-spawn on the still-sub-routed model.
+    if (
+      effectiveMode === "autonomous" &&
+      failedReviewerVariants.length > 0 &&
+      !orchestrator.subFallbackPendingDecision
+    ) {
       const cycle = orchestrator.active.state.reviewCycle;
       const phase = orchestrator.active.state.phase;
       const outputs = loadPhaseReviewOutputs(orchestrator.active.dir, phase, cycle.pass);
@@ -1600,6 +1688,23 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.abortAllSubagents();
     }
 
+    // Subscription rate-limit (429) on a sub-routed subagent: offer the ONE
+    // global switch-to-non-sub dialogue (never per-subagent). subagents:failed
+    // carries the subagent's resolved model id.
+    const failedModelId = typeof data.modelId === "string" ? data.modelId : undefined;
+    const subRateLimited =
+      isRateLimitError(data.error) &&
+      isSubscriptionRouted(failedModelId) &&
+      !orchestrator.subFallbackActive;
+    if (subRateLimited) {
+      // Set the decision-pending flag SYNCHRONOUSLY (before the completion checks
+      // below) so the autonomous planner/reviewer auto-retry does NOT re-spawn
+      // the failed variant on the still-sub-routed model while the fallback
+      // dialogue is in flight.
+      orchestrator.subFallbackPendingDecision = true;
+      void handleSubagentRateLimit(orchestrator, orchestrator.lastCtx, failedModelId);
+    }
+
     orchestrator.transitionController.sendCustom(
       {
         customType: "pp-subagent-error",
@@ -1780,6 +1885,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (!isControllerInjected) {
       orchestrator.nudgeHalted = false;
       orchestrator.consecutiveNudges = 0;
+      // Genuine user re-engagement also clears the API-error retry halt, so a
+      // fresh request can auto-retry again from a clean counter.
+      orchestrator.errorNudgeHalted = false;
+      orchestrator.errorRetryCount = 0;
     }
     orchestrator.updateStatus(ctx);
 
@@ -1814,6 +1923,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       constraintsBlock(phase as Phase, effectiveMode),
       PRINCIPLES_BLOCK,
       TOOLS_BLOCK,
+      DELEGATION_BLOCK,
       projectContext,
       taskBlock,
     ]
@@ -1836,24 +1946,29 @@ 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 validTypes = ["explore", "librarian", "task", "advisor", "deep-debugger", "reviewer"];
       if (!requestedType) {
-        return { block: true, reason: "subagent_type is required. Use Explore for codebase research, Librarian for external docs, or Task for implementation subtasks." };
+        return { block: true, reason: "subagent_type is required. Valid types: explore (codebase research), librarian (external docs), task (implementation subtask), advisor (design/'why is this broken' judgment), deep-debugger (hard persistent failures), reviewer (code review — only when the user explicitly asks)." };
       }
-      const isExplore = requestedType === "explore";
-      const isLibrarian = requestedType === "librarian";
-
-      if (isExplore) {
-        input.subagent_type = "explore";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.explore.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.explore.thinking;
-      } else if (isLibrarian) {
-        input.subagent_type = "librarian";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.librarian.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.librarian.thinking;
-      } else {
-        input.subagent_type = "task";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.task.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.task.thinking;
+      if (!validTypes.includes(requestedType)) {
+        return { block: true, reason: `Unknown subagent_type "${requestedType}". Valid types: ${validTypes.join(", ")}.` };
+      }
+
+      const simple = orchestrator.config.agents.subagents.simple;
+      const role = requestedType as keyof typeof simple;
+      input.subagent_type = requestedType;
+      input.model = resolveModel(simple[role].model);
+      input.thinking = simple[role].thinking;
+
+      // Spawn-time context injection: append USER_REQUEST + RESEARCH content and a
+      // path-aware manifest of on-demand documents to the LLM-supplied spawn prompt.
+      // explore/librarian intentionally get nothing (fast, scoped retrieval).
+      if (["task", "advisor", "deep-debugger", "reviewer"].includes(requestedType)) {
+        const contextBlock = buildSpawnContextBlock(orchestrator.active.dir);
+        if (contextBlock) {
+          const existingPrompt = typeof input.prompt === "string" ? input.prompt : "";
+          input.prompt = existingPrompt ? `${existingPrompt}\n\n${contextBlock}` : contextBlock;
+        }
       }
     }
 
@@ -2105,6 +2220,39 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         contentBlocks: msg.content?.length ?? 0,
         contentSummary,
       }, "turn ended with error");
+      // Subscription rate-limit (429) on a sub-routed main turn: retrying the
+      // same sub model is futile against an account-level limit. Offer a
+      // user-gated switch to non-sub Claude instead of the generic backoff.
+      const activeModelId = (typeof msg.model === "string" && msg.model) || ctx.model?.id;
+      const activeProvider = (typeof msg.provider === "string" && msg.provider) || ctx.model?.provider;
+      if (
+        isRateLimitError(errorMsg) &&
+        isSubscriptionRouted(activeModelId, activeProvider) &&
+        !orchestrator.subFallbackActive
+      ) {
+        void handleMainRateLimit(orchestrator, ctx, activeModelId, activeProvider);
+        return;
+      }
+      // The SDK already auto-retries this class of error itself (abortable
+      // backoff bound to ESC, continuing the SAME turn). Running pi-pi's OWN
+      // independent retry on top would double-fire: its followUp races the SDK's
+      // continue() into "Agent is already processing", and it re-nudges a still-
+      // failing model. So for SDK-retryable errors we defer entirely to the SDK
+      // and do nothing here. pi-pi's own idle-gated retry remains only as the
+      // fallback for errors the SDK does NOT retry.
+      if (isSdkRetryableError(errorMsg)) {
+        getLogger().debug({ s: "turn", err: errorMsg }, "deferring to SDK auto-retry; pi-pi retry skipped");
+        return;
+      }
+      // Halt guard: once the consecutive-error cap is exceeded we stop auto-
+      // retrying until the user re-engages. errorRetryCount is NO LONGER reset on
+      // benign intervening turns (see below) — otherwise a retried turn that ends
+      // as a harmless text-only reply would reset the counter and the cap could
+      // never accumulate, letting transient errors nudge unbounded.
+      if (orchestrator.errorNudgeHalted) {
+        getLogger().debug({ s: "turn", err: errorMsg }, "error auto-retry halted; awaiting user re-engagement");
+        return;
+      }
       orchestrator.errorRetryCount = (orchestrator.errorRetryCount ?? 0) + 1;
       const maxRetries = 5;
       if (orchestrator.errorRetryCount <= maxRetries) {
@@ -2112,18 +2260,44 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         ctx.ui.notify(`API error (attempt ${orchestrator.errorRetryCount}/${maxRetries}): ${errorMsg}. Retrying in ${delay / 1000}s...`, "warning");
         const taskToken = orchestrator.activeTaskToken;
         if (orchestrator.pendingRetryTimer) clearTimeout(orchestrator.pendingRetryTimer);
+        // Arm a direct ESC interrupt for this retry window — no SDK/interactive
+        // binding covers pi-pi's own timer (the turn already ended in error).
+        orchestrator.armRetryEscInterrupt(ctx);
         orchestrator.pendingRetryTimer = setTimeout(() => {
           orchestrator.pendingRetryTimer = null;
-          if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
-          orchestrator.safeSendUserMessage(`[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`);
+          if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) {
+            orchestrator.disarmRetryEscInterrupt();
+            return;
+          }
+          // Defer until the main session is idle: sending a followUp while the SDK
+          // still has an active run throws an async, runtime-swallowed "Agent is
+          // already processing" error. sendUserMessageWhenIdle polls (reusing
+          // pendingRetryTimer so ESC/abort still cancels) and disarms the ESC hook
+          // once delivered.
+          orchestrator.sendUserMessageWhenIdle(
+            `[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`,
+            taskToken,
+          );
         }, delay);
       } else {
-        ctx.ui.notify(`API error persisted after ${maxRetries} retries: ${errorMsg}. Stopping auto-retry.`, "error");
-        orchestrator.errorRetryCount = 0;
+        ctx.ui.notify(`API error persisted after ${maxRetries} retries: ${errorMsg}. Stopping auto-retry — send any message to resume.`, "error");
+        // Halt (do NOT reset the counter) so no further error turn re-arms a retry
+        // until the user re-engages. cancelPendingRetry would reset the count and
+        // re-open the floodgate, so only clear the live timer/ESC hook here.
+        orchestrator.errorNudgeHalted = true;
+        if (orchestrator.pendingRetryTimer) {
+          clearTimeout(orchestrator.pendingRetryTimer);
+          orchestrator.pendingRetryTimer = null;
+        }
+        orchestrator.disarmRetryEscInterrupt();
       }
       return;
     }
-    orchestrator.errorRetryCount = 0;
+    // NOTE: errorRetryCount is intentionally NOT reset here. Resetting on every
+    // non-error turn let a benign nudge-induced turn zero the counter, defeating
+    // the maxRetries cap and allowing unbounded error nudges. The counter is
+    // reset only on genuine user re-engagement (before_agent_start) and on task
+    // reset / cancelPendingRetry.
 
     if ((globalThis as any)[SUBAGENT_SESSION_KEY]) {
       return;