@ilya-lesikov/pi-pi 0.7.0 → 0.8.0

package/extensions/orchestrator/rate-limit-fallback.ts

@@ -0,0 +1,243 @@
+import type { Orchestrator } from "./orchestrator.js";
+import { getLogger } from "./log.js";
+import { isSubscriptionRouted } from "./usage-tracker.js";
+import { setSubscriptionFallbackActive, toNonSubSpec } from "./model-registry.js";
+import { loadFlantSettings, probeSubscriptionCleared } from "./flant-infra.js";
+import { askUser, isCancel } from "../../3p/pi-ask-user/index.js";
+
+// Recognise a rate-limit / 429 error from a turn's or subagent's error message.
+export function isRateLimitError(message?: string): boolean {
+  if (typeof message !== "string") return false;
+  return /\b429\b|rate.?limit|too many requests|exceed your account/i.test(message);
+}
+
+// Mirror of the SDK's AgentSession._isRetryableError classifier
+// (agent-session.js: overloaded/rate-limit/5xx/network/stream-ended/timeout/...).
+// When true, the SDK auto-retries the SAME turn itself (abortable backoff bound
+// to ESC, visible countdown). pi-pi must NOT ALSO schedule its own post-error
+// retry for these: a second, independent retry races the SDK's continue() and
+// reproduces "Agent is already processing", and re-nudges a futile sub-429. This
+// list is kept in sync with the SDK regex; if they drift, pi-pi at worst falls
+// back to its own idle-gated retry (still safe, just not unified).
+export function isSdkRetryableError(message?: string): boolean {
+  if (typeof message !== "string" || !message) return false;
+  return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i.test(
+    message,
+  );
+}
+
+const SWITCH_DIALOG_CONTEXT =
+  "Switching between the personal subscription and regular flant Claude changes the provider/endpoint, " +
+  "so the prompt cache is LOST and the full conversation context is re-sent on the next call. " +
+  "Regular (non-subscription) flant Claude is billed PER TOKEN (paid).";
+
+// Handle a subscription-routed 429 on the MAIN turn. Stops futile retries on the
+// still-limited sub model, then (once, session-sticky) asks the user whether to
+// fall back to non-sub Claude. On confirm: activates the session-scoped override,
+// switches the active model, arms the switch-back probe, and nudges to continue.
+export async function handleMainRateLimit(
+  orchestrator: Orchestrator,
+  ctx: any,
+  modelId: string | undefined,
+  provider: string | undefined,
+): Promise<void> {
+  const log = getLogger();
+  if (!isSubscriptionRouted(modelId, provider)) return;
+
+  // Stop the futile same-model retry (SDK backoff + pi-pi's own timer): retrying
+  // the sub model against an account-level limit cannot succeed.
+  ctx?.abort?.();
+  orchestrator.cancelPendingRetry();
+
+  if (orchestrator.subFallbackActive) return; // sticky — already on non-sub
+  await offerFallback(orchestrator, ctx, modelId ?? orchestrator.subFallbackModelId ?? "", "main");
+}
+
+// Handle a subscription-routed 429 reported via subagents:failed. Uses ONE
+// global dialogue (never per-subagent) — the same offerFallback path as the
+// main turn, guarded so only one dialogue is open at a time.
+export async function handleSubagentRateLimit(
+  orchestrator: Orchestrator,
+  ctx: any,
+  modelId: string | undefined,
+): Promise<void> {
+  if (!isSubscriptionRouted(modelId)) return;
+  if (orchestrator.subFallbackActive) return; // sticky
+  await offerFallback(orchestrator, ctx, modelId ?? "", "subagent");
+}
+
+async function offerFallback(
+  orchestrator: Orchestrator,
+  ctx: any,
+  subModelId: string,
+  origin: "main" | "subagent",
+): Promise<void> {
+  const log = getLogger();
+  if (orchestrator.subFallbackDialogPending) return;
+  if (!ctx?.hasUI) {
+    // No UI to ask — leave sub routing in place; the error is surfaced elsewhere.
+    log.debug({ s: "ratelimit" }, "no UI available to offer subscription fallback");
+    return;
+  }
+  orchestrator.subFallbackDialogPending = true;
+  const taskToken = orchestrator.activeTaskToken;
+  try {
+    const result = await askUser(ctx, {
+      question: "Personal Claude subscription is rate-limited. Switch to regular (paid) flant Claude?",
+      context: SWITCH_DIALOG_CONTEXT,
+      options: [
+        { title: "Switch to non-sub Claude", description: "Continue on regular flant Claude (paid per token) until you switch back." },
+        { title: "Stay on subscription", description: "Do not switch. Work stays paused until the limit clears." },
+      ],
+      allowFreeform: false,
+      allowComment: false,
+      allowMultiple: false,
+    });
+    if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
+    const chose = result && !isCancel(result) && result.kind === "selection" ? result.selections[0] : undefined;
+    if (chose !== "Switch to non-sub Claude") {
+      ctx.ui?.notify?.("Staying on subscription. Auto-continuation paused until you resume or the limit clears.", "info");
+      return;
+    }
+    await activateFallback(orchestrator, ctx, subModelId, origin);
+  } finally {
+    orchestrator.subFallbackDialogPending = false;
+    orchestrator.subFallbackPendingDecision = false;
+  }
+}
+
+async function activateFallback(
+  orchestrator: Orchestrator,
+  ctx: any,
+  subModelId: string,
+  origin: "main" | "subagent",
+): Promise<void> {
+  const log = getLogger();
+  orchestrator.subFallbackActive = true;
+  orchestrator.subFallbackModelId = subModelId || orchestrator.subFallbackModelId;
+  // Activate the session-scoped override so EVERY future model resolution
+  // (phase switches, new subagents, planner/reviewer specs) rewrites sub→non-sub.
+  // This is what actually re-routes future subagent spawns, regardless of origin.
+  setSubscriptionFallbackActive(true);
+
+  // Switch the CURRENT main model to the non-sub equivalent ONLY when the 429 was
+  // on the main turn. For a SUBAGENT 429 the failing model is the subagent's, not
+  // the main session's — switching the main model here would change the active
+  // orchestrator model the user never touched (e.g. debug's GPT -> Claude). The
+  // session override above already re-routes the retried/next subagent.
+  if (origin === "main" && subModelId) {
+    const nonSub = toNonSubSpec(subModelId);
+    const ok = await orchestrator.switchModel(ctx, nonSub, currentThinking(orchestrator));
+    if (!ok) log.warn({ s: "ratelimit", nonSub }, "failed to switch main model to non-sub");
+  }
+
+  ctx.ui?.notify?.("Switched to regular flant Claude (paid per token). Will periodically check if the subscription limit has cleared.", "info");
+
+  armSwitchBackProbe(orchestrator);
+
+  // Nudge to continue — retries were cancelled, so the turn is stopped. Idle-gated
+  // (same guard as the post-error nudge) so it never races the SDK into an
+  // "Agent is already processing" error.
+  const phase = orchestrator.active?.state.phase ?? "current";
+  orchestrator.sendUserMessageWhenIdle(
+    `[PI-PI] Switched to regular (non-subscription) flant Claude after a rate limit. Continue working on the current phase (${phase}).`,
+    orchestrator.activeTaskToken,
+  );
+}
+
+function currentThinking(orchestrator: Orchestrator): string {
+  const phase = orchestrator.active?.state.phase;
+  const orchestrators = orchestrator.config?.agents?.orchestrators as Record<string, { thinking?: string }> | undefined;
+  const key = phase === "debug" || phase === "brainstorm" || phase === "review" || phase === "quick" ? phase : "implement";
+  return orchestrators?.[key]?.thinking ?? "high";
+}
+
+// Arm the fixed-interval switch-back probe. On each interval an out-of-band probe
+// checks whether the sub limit cleared; a 429/failure silently re-arms, a success
+// opens the switch-back dialogue. Only one timer runs at a time.
+export function armSwitchBackProbe(orchestrator: Orchestrator): void {
+  if (orchestrator.subSwitchBackTimer) clearTimeout(orchestrator.subSwitchBackTimer);
+  const minutes = Math.max(1, loadFlantSettings().switchBackIntervalMinutes || 30);
+  const taskToken = orchestrator.activeTaskToken;
+  orchestrator.subSwitchBackTimer = setTimeout(() => {
+    orchestrator.subSwitchBackTimer = null;
+    void runSwitchBackProbe(orchestrator, taskToken);
+  }, minutes * 60 * 1000);
+}
+
+async function runSwitchBackProbe(orchestrator: Orchestrator, taskToken: number): Promise<void> {
+  const log = getLogger();
+  if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active || !orchestrator.subFallbackActive) {
+    return;
+  }
+  const modelId = orchestrator.subFallbackModelId;
+  if (!modelId) {
+    armSwitchBackProbe(orchestrator);
+    return;
+  }
+  const outcome = await probeSubscriptionCleared(modelId);
+  if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active || !orchestrator.subFallbackActive) {
+    return;
+  }
+  if (outcome !== "ok") {
+    // Still limited (or transient error) — stay on non-sub, silently re-arm.
+    log.debug({ s: "ratelimit", outcome }, "switch-back probe: not cleared, re-arming");
+    armSwitchBackProbe(orchestrator);
+    return;
+  }
+  await offerSwitchBack(orchestrator, modelId);
+}
+
+async function offerSwitchBack(orchestrator: Orchestrator, subModelId: string): Promise<void> {
+  const log = getLogger();
+  const ctx = orchestrator.lastCtx;
+  if (orchestrator.subFallbackDialogPending || !ctx?.hasUI) {
+    armSwitchBackProbe(orchestrator);
+    return;
+  }
+  orchestrator.subFallbackDialogPending = true;
+  const taskToken = orchestrator.activeTaskToken;
+  try {
+    const result = await askUser(ctx, {
+      question: "Your Claude subscription limit appears to have cleared. Switch back to the subscription?",
+      context: SWITCH_DIALOG_CONTEXT,
+      options: [
+        { title: "Switch back to subscription", description: "Resume on the personal Claude subscription (flat-rate)." },
+        { title: "Stay on non-sub Claude", description: "Keep using regular flant Claude; check again later." },
+      ],
+      allowFreeform: false,
+      allowComment: false,
+      allowMultiple: false,
+    });
+    if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
+    const chose = result && !isCancel(result) && result.kind === "selection" ? result.selections[0] : undefined;
+    if (chose !== "Switch back to subscription") {
+      // Stay on non-sub; re-arm so we check again after the interval.
+      armSwitchBackProbe(orchestrator);
+      return;
+    }
+    await switchBackToSub(orchestrator, ctx, subModelId);
+  } finally {
+    orchestrator.subFallbackDialogPending = false;
+  }
+}
+
+async function switchBackToSub(orchestrator: Orchestrator, ctx: any, subModelId: string): Promise<void> {
+  const log = getLogger();
+  // Clear the override FIRST so switchModel resolves the sub spec unrewritten.
+  orchestrator.subFallbackActive = false;
+  setSubscriptionFallbackActive(false);
+  if (orchestrator.subSwitchBackTimer) {
+    clearTimeout(orchestrator.subSwitchBackTimer);
+    orchestrator.subSwitchBackTimer = null;
+  }
+  const ok = await orchestrator.switchModel(ctx, subModelId, currentThinking(orchestrator));
+  if (!ok) log.warn({ s: "ratelimit", subModelId }, "failed to switch back to sub model");
+  orchestrator.subFallbackModelId = null;
+  ctx.ui?.notify?.("Switched back to the personal Claude subscription.", "info");
+  const phase = orchestrator.active?.state.phase ?? "current";
+  orchestrator.sendUserMessageWhenIdle(
+    `[PI-PI] Switched back to the personal Claude subscription. Continue working on the current phase (${phase}).`,
+    orchestrator.activeTaskToken,
+  );
+}

package/extensions/orchestrator/test-helpers.ts

@@ -215,9 +215,12 @@ export function expectReviewAuto(menu: AskUserHarness, preset = "regular"): void
   menu.expect({ question: "Review preset", options: { include: [m.preset(preset), "Back"] }, choose: m.preset(preset) });
 }
 
-export function expectReviewOnMyOwn(menu: AskUserHarness): void {
+export function expectReviewOnMyOwn(menu: AskUserHarness, editorGate?: "Done" | "Skip markers"): void {
   menu.expect({ question: m.anyTaskMenu, options: { include: ["Review"] }, choose: "Review" });
   menu.expect({ question: "Review", options: { include: ["Review on my own"] }, choose: "Review on my own" });
+  if (editorGate) {
+    menu.expect({ question: "Editor review", options: { include: [editorGate] }, choose: editorGate });
+  }
 }
 
 export function expectPpStartImplementAutonomous(menu: AskUserHarness): void {

package/extensions/orchestrator/usage-tracker.ts

@@ -12,7 +12,11 @@ import { SUB_MODEL_PREFIX, SUB_PROVIDER } from "./flant-infra.js";
  */
 export function isSubscriptionRouted(modelId?: string, provider?: string): boolean {
   if (provider === SUB_PROVIDER) return true;
-  return typeof modelId === "string" && modelId.startsWith(SUB_MODEL_PREFIX);
+  if (typeof modelId !== "string") return false;
+  // Accept a bare `sub/<m>` id OR a full provider-prefixed spec
+  // `pp-flant-anthropic-sub/sub/<m>` passed as a single id (the form callers
+  // store/pass without a separate provider field).
+  return modelId.startsWith(SUB_MODEL_PREFIX) || modelId.startsWith(`${SUB_PROVIDER}/`);
 }
 
 export interface ModelUsage {

package/extensions/orchestrator/validate-artifacts.test.ts

@@ -41,6 +41,26 @@ Ship minimal fix.
     expect(result.ok).toBe(true);
   });
 
+  it("accepts a Pattern constraints section", () => {
+    const content = `# Plan
+
+## Scope
+Add a new annotation.
+
+## Checklist
+- [ ] Add annotation — Done when: tests pass
+
+## Pattern constraints
+- Mirror deletePolicies: one typed slice, kebab-case values.
+
+## Blockers
+- none
+`;
+
+    const result = validatePlan(content);
+    expect(result.ok).toBe(true);
+  });
+
   it("accepts multiline Done when continuation", () => {
     const content = `# Plan
 

package/extensions/orchestrator/validate-artifacts.ts

@@ -5,7 +5,7 @@ const USER_REQUEST_ALLOWED_SECTIONS = ["Problem", "Constraints"] as const;
 const RESEARCH_REQUIRED_SECTIONS = ["Affected Code", "Architecture Context", "Constraints & Edge Cases"] as const;
 const RESEARCH_ALLOWED_SECTIONS = ["Affected Code", "Architecture Context", "Constraints & Edge Cases", "Open Questions"] as const;
 const PLAN_REQUIRED_SECTIONS = ["Scope", "Checklist"] as const;
-const PLAN_ALLOWED_SECTIONS = ["Scope", "Checklist", "Blockers"] as const;
+const PLAN_ALLOWED_SECTIONS = ["Scope", "Checklist", "Pattern constraints", "Blockers"] as const;
 const PLACEHOLDER_PATTERNS = /^(?:[-*.…—]|tbd|todo|n\/a|na|none|\.{2,})$/i;
 
 function splitLines(content: string): string[] {
@@ -186,7 +186,7 @@ export function validatePlan(content: string): ValidationResult {
   const errors: string[] = [];
   const h1 = getH1(content);
   const firstHeading = getFirstHeading(content);
-  const expectedSections = formatSectionList(PLAN_REQUIRED_SECTIONS, ["Blockers"]);
+  const expectedSections = formatSectionList(PLAN_REQUIRED_SECTIONS, ["Pattern constraints", "Blockers"]);
 
   if (!firstHeading) {
     errors.push("Missing required heading: # Plan. Expected first heading: # Plan");

package/package.json

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