squad-kit 0.2.0 → 0.2.2

package/dist/cli.js

@@ -2372,7 +2372,92 @@ function looksBinary(buf) {
   return false;
 }
 
+// src/planner/provider-errors.ts
+function detectModelNotFound(provider, model, status, rawBody) {
+  if (status !== 404) return void 0;
+  const body = rawBody.toLowerCase();
+  const hints = ["not_found_error", "model_not_found", "not_found", "model:"];
+  if (!hints.some((h) => body.includes(h))) return void 0;
+  return { provider, model, status, rawBody };
+}
+function modelNotFoundMessage(err) {
+  return [
+    `The ${err.provider} planner model "${err.model}" is no longer available.`,
+    "",
+    "Recovery options:",
+    `  1. Run \`squad upgrade\` to install a newer squad-kit (or install manually from npm).`,
+    `  2. Run \`squad config set planner --provider openai\` (or another \`--provider\`) to switch models via a different provider, then save a key when prompted.`,
+    `  3. Run \`squad config set planner\` to set \`planner.modelOverride.${err.provider}\` to a still-valid id (no raw YAML), then \`squad doctor\` to confirm.`,
+    "",
+    `Raw provider response: ${err.rawBody.slice(0, 200)}`
+  ].join("\n");
+}
+function detectRateLimit(provider, status, headers, rawBody) {
+  if (status !== 429) return void 0;
+  return {
+    provider,
+    status: 429,
+    retryAfterSec: parseRetryAfter(headers, rawBody),
+    rawBody
+  };
+}
+function parseRetryAfter(headers, body) {
+  const raw = headerGet(headers, "retry-after");
+  if (raw) {
+    const sec = Number(raw);
+    if (Number.isFinite(sec) && sec >= 0) return Math.ceil(sec);
+    const asDate = Date.parse(raw);
+    if (Number.isFinite(asDate)) {
+      return Math.max(0, Math.ceil((asDate - Date.now()) / 1e3));
+    }
+  }
+  const bodyMatch = /"retryDelay"\s*:\s*"(\d+)(?:\.\d+)?s"/i.exec(body);
+  if (bodyMatch) {
+    const sec = Number(bodyMatch[1]);
+    if (Number.isFinite(sec) && sec >= 0) return sec;
+  }
+  return void 0;
+}
+function headerGet(h, name) {
+  if (typeof h.get === "function") {
+    return h.get(name);
+  }
+  const key = name.toLowerCase();
+  const rec = h;
+  for (const k of Object.keys(rec)) {
+    if (k.toLowerCase() === key) return rec[k] ?? null;
+  }
+  return null;
+}
+function rateLimitMessage(err) {
+  const waitHint = err.retryAfterSec ?? 60;
+  const limitsUrl = {
+    anthropic: "https://console.anthropic.com/settings/limits",
+    openai: "https://platform.openai.com/settings/organization/limits",
+    google: "https://aistudio.google.com/app/plan_information"
+  };
+  const headline = err.retryAfterSec ? `${err.provider} rate limit hit \u2014 provider asked us to wait ${err.retryAfterSec}s before retrying.` : `${err.provider} rate limit hit.`;
+  const cap = err.maxRetrySec ?? 90;
+  const retried = err.retrySkippedReason === "retry_after_too_long" ? `squad-kit did not auto-retry: the provider's ${err.retryAfterSec}s wait is longer than our ${cap}s cap, so retrying would just burn another request inside the same throttle window.` : err.retryAlreadyAttempted ? "squad-kit already retried once automatically and was throttled again \u2014 your org is firmly over its per-minute quota." : "squad-kit aborted before retrying.";
+  return [
+    headline,
+    retried,
+    "",
+    "Recovery options:",
+    `  1. Wait ${waitHint}s and rerun \`squad new-plan --api\`. Per-minute limits reset quickly.`,
+    `  2. Switch to a smaller planner model: \`squad config set planner\` (pick a cheaper model id).`,
+    `  3. Tighten \`planner.budget\` in \`.squad/config.yaml\` (smaller \`maxContextBytes\` / \`maxFileReads\`) so each request carries fewer tokens.`,
+    `  4. Upgrade your ${err.provider} tier: ${limitsUrl[err.provider]}.`,
+    "",
+    "Full runbook: docs/migrating-from-0.1.md (see \xA78. If something goes wrong).",
+    "",
+    `Raw provider response: ${err.rawBody.slice(0, 200)}`
+  ].join("\n");
+}
+
 // src/planner/loop.ts
+var MAX_RATE_LIMIT_RETRY_SEC = 90;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function runPlanner(input6) {
   const maxIter = input6.maxIterations ?? 40;
   const turns = [{ role: "user", text: input6.userPrompt }];
@@ -2388,21 +2473,39 @@ async function runPlanner(input6) {
     if (input6.budget.overCost()) {
       return { planText: accumulatedText, budgetExhausted: true, timedOut: false, finishedNormally: false, iterations };
     }
-    const response = await input6.provider.send({
+    const request = {
       systemPrompt: input6.systemPrompt,
       model: input6.model,
       tools: [READ_FILE_TOOL],
       turns,
       apiKey: input6.apiKey,
       maxOutputTokens: 8192
-    });
+    };
+    let response = await input6.provider.send(request);
     if (response.usage) {
       input6.budget.recordUsage(response.usage);
       input6.onUsage?.(response.usage);
     }
+    let retriedRateLimit = false;
+    let retrySkippedReason;
+    if (response.stopReason === "error" && response.errorKind === "rate_limit") {
+      const asked = response.retryAfterSec;
+      if (asked !== void 0 && asked > MAX_RATE_LIMIT_RETRY_SEC) {
+        retrySkippedReason = "retry_after_too_long";
+      } else {
+        const waitSec = Math.min(asked ?? 10, MAX_RATE_LIMIT_RETRY_SEC);
+        input6.onRateLimit?.(waitSec);
+        await (input6.sleep ?? defaultSleep)(waitSec * 1e3);
+        response = await input6.provider.send(request);
+        if (response.usage) {
+          input6.budget.recordUsage(response.usage);
+          input6.onUsage?.(response.usage);
+        }
+        retriedRateLimit = true;
+      }
+    }
     if (response.stopReason === "error") {
-      const base = response.rawError ?? "planner: provider error";
-      throw new Error(`${base} Run \`squad doctor\` to verify models and credentials.`);
+      throw composePlannerError(input6.provider.name, response, retriedRateLimit, retrySkippedReason);
     }
     if (response.text) {
       accumulatedText += response.text;
@@ -2445,26 +2548,24 @@ async function runPlanner(input6) {
   }
   return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally: false, iterations };
 }
-
-// src/planner/provider-errors.ts
-function detectModelNotFound(provider, model, status, rawBody) {
-  if (status !== 404) return void 0;
-  const body = rawBody.toLowerCase();
-  const hints = ["not_found_error", "model_not_found", "not_found", "model:"];
-  if (!hints.some((h) => body.includes(h))) return void 0;
-  return { provider, model, status, rawBody };
-}
-function modelNotFoundMessage(err) {
-  return [
-    `The ${err.provider} planner model "${err.model}" is no longer available.`,
-    "",
-    "Recovery options:",
-    `  1. Run \`squad upgrade\` to install a newer squad-kit (or install manually from npm).`,
-    `  2. Run \`squad config set planner --provider openai\` (or another \`--provider\`) to switch models via a different provider, then save a key when prompted.`,
-    `  3. Run \`squad config set planner\` to set \`planner.modelOverride.${err.provider}\` to a still-valid id (no raw YAML), then \`squad doctor\` to confirm.`,
-    "",
-    `Raw provider response: ${err.rawBody.slice(0, 200)}`
-  ].join("\n");
+function composePlannerError(providerName, response, retriedRateLimit, retrySkippedReason) {
+  if (response.errorKind === "rate_limit") {
+    return new Error(
+      rateLimitMessage({
+        provider: providerName,
+        retryAfterSec: response.retryAfterSec,
+        rawBody: response.rawError ?? "",
+        retryAlreadyAttempted: retriedRateLimit,
+        retrySkippedReason,
+        maxRetrySec: MAX_RATE_LIMIT_RETRY_SEC
+      })
+    );
+  }
+  if (response.errorKind === "model_not_found") {
+    return new Error(response.rawError ?? "planner: model not found");
+  }
+  const base = response.rawError ?? "planner: provider error";
+  return new Error(`${base} Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`);
 }
 
 // src/planner/providers/anthropic.ts
@@ -2497,7 +2598,20 @@ async function callAnthropic(req) {
     const text = await res.text().catch(() => "");
     const nf = detectModelNotFound("anthropic", req.model, res.status, text);
     if (nf) {
-      return { stopReason: "error", rawError: modelNotFoundMessage(nf) };
+      return {
+        stopReason: "error",
+        rawError: modelNotFoundMessage(nf),
+        errorKind: "model_not_found"
+      };
+    }
+    const rl = detectRateLimit("anthropic", res.status, res.headers, text);
+    if (rl) {
+      return {
+        stopReason: "error",
+        rawError: `anthropic 429: ${text.slice(0, 500)}`,
+        errorKind: "rate_limit",
+        retryAfterSec: rl.retryAfterSec
+      };
     }
     return { stopReason: "error", rawError: `anthropic ${res.status}: ${text.slice(0, 500)}` };
   }
@@ -2567,7 +2681,20 @@ async function callOpenAI(req) {
     const text = await res.text().catch(() => "");
     const nf = detectModelNotFound("openai", req.model, res.status, text);
     if (nf) {
-      return { stopReason: "error", rawError: modelNotFoundMessage(nf) };
+      return {
+        stopReason: "error",
+        rawError: modelNotFoundMessage(nf),
+        errorKind: "model_not_found"
+      };
+    }
+    const rl = detectRateLimit("openai", res.status, res.headers, text);
+    if (rl) {
+      return {
+        stopReason: "error",
+        rawError: `openai 429: ${text.slice(0, 500)}`,
+        errorKind: "rate_limit",
+        retryAfterSec: rl.retryAfterSec
+      };
     }
     return { stopReason: "error", rawError: `openai ${res.status}: ${text.slice(0, 500)}` };
   }
@@ -2653,7 +2780,20 @@ async function callGoogle(req) {
     const text = await res.text().catch(() => "");
     const nf = detectModelNotFound("google", req.model, res.status, text);
     if (nf) {
-      return { stopReason: "error", rawError: modelNotFoundMessage(nf) };
+      return {
+        stopReason: "error",
+        rawError: modelNotFoundMessage(nf),
+        errorKind: "model_not_found"
+      };
+    }
+    const rl = detectRateLimit("google", res.status, res.headers, text);
+    if (rl) {
+      return {
+        stopReason: "error",
+        rawError: `google 429: ${text.slice(0, 500)}`,
+        errorKind: "rate_limit",
+        retryAfterSec: rl.retryAfterSec
+      };
     }
     return { stopReason: "error", rawError: `google ${res.status}: ${text.slice(0, 500)}` };
   }
@@ -3132,6 +3272,11 @@ async function emitViaApi(story, paths, config2, _opts) {
     onAssistantText: () => {
       sessionSpinner.current?.succeed("planner thinking complete (this chunk)");
       sessionSpinner.current = spinner("thinking\u2026");
+    },
+    onRateLimit: (waitSec) => {
+      sessionSpinner.current?.stop();
+      warning(`${planner.provider} rate limit hit \u2014 retrying in ${waitSec}s`);
+      sessionSpinner.current = spinner("waiting for rate limit to reset\u2026");
     }
   });
   sessionSpinner.current?.stop();
@@ -3690,6 +3835,28 @@ async function checkPlannerModel(_paths, ctx) {
     };
   }
 }
+async function checkPlannerTierAwareness(_paths, ctx) {
+  const id = "planner-tier";
+  const name = "planner tier vs. model";
+  if (!ctx.config || ctx.config.planner?.enabled !== true) {
+    return { id, name, status: "skip", detail: "planner disabled" };
+  }
+  const provider = ctx.config.planner.provider;
+  if (provider !== "anthropic") {
+    return { id, name, status: "skip", detail: `not applicable for ${provider}` };
+  }
+  const planModel = modelFor(provider, "plan", ctx.config.planner.modelOverride);
+  if (!/opus/i.test(planModel)) {
+    return { id, name, status: "ok", detail: `${planModel} is comfortably under Tier 1` };
+  }
+  return {
+    id,
+    name,
+    status: "warn",
+    detail: `${planModel} on Anthropic Tier 1 (10k input tokens/min) is throttle-prone for plans over ~3 file reads`,
+    fixHint: "Run `squad config set planner` and pick a Sonnet or Haiku id for planner.modelOverride.anthropic, or upgrade tier at https://console.anthropic.com/settings/limits. squad-kit will auto-retry a 429 once (waiting up to 90s), but repeated throttling means the plan model is simply too big for your quota."
+  };
+}
 async function checkTrackerConfig(_paths, ctx) {
   if (!ctx.config) {
     return { id: "tracker-config", name: "tracker configuration", status: "skip", detail: "config unavailable" };
@@ -3811,6 +3978,7 @@ async function runAllChecks(paths, ctx, fix) {
   await add("planner configuration", () => checkPlannerConfig(paths, ctx));
   await add("planner credential resolves", () => checkPlannerCredential(paths, ctx));
   await add("planner model resolves at provider", () => checkPlannerModel(paths, ctx));
+  await add("planner tier vs. model", () => checkPlannerTierAwareness(paths, ctx));
   await add("tracker configuration", () => checkTrackerConfig(paths, ctx));
   await add("tracker credential resolves", () => checkTrackerCredential(paths, ctx));
   await add("tracker connectivity", () => checkTrackerConnectivity(paths, ctx));
@@ -4704,7 +4872,7 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
 
 // src/cli.ts
 var program = new Command();
-program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.2.0");
+program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.2.2");
 program.command("init").description("Bootstrap .squad/ in the current directory").option("--agents <list>", "Comma-separated agent list: claude-code,cursor,copilot,gemini").option("--tracker <type>", "Tracker type: none|github|linear|jira|azure").option(
   "--tracker-workspace <hostOrOrg>",
   "Jira host or Azure org (non-interactive default; also written to config for jira/azure)"