@gaberrb/polypus 0.4.7 → 0.4.8

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 
 // src/cli/commands/add-agent.ts
 import pc from "picocolors";
@@ -111,6 +111,8 @@ var en = {
   "cli.opt.maxSteps": "maximum agent steps",
   "cli.opt.json": "headless mode: emit a single JSON object (steps, tool calls, files changed, usage) instead of the TUI \u2014 use with --mode bypass",
   "cli.opt.verify": "after the agent finishes, run project checks (typecheck/build/test) and iterate until they pass",
+  "cli.opt.budget": "stop the run when the estimated session cost reaches this USD amount (OpenRouter pricing)",
+  "cli.cmd.usage": "Show token/cost analytics aggregated per day",
   "cli.arg.swarmTask": "high-level task to split across agents",
   "cli.opt.agents": "comma-separated agent names (default: all configured)",
   "cli.opt.maxSubtasks": "maximum number of parallel subtasks",
@@ -147,6 +149,13 @@ var en = {
   "verify.passed": "verification passed",
   "verify.failed": "{n} check(s) failed \u2014 handing the output back to the agent (attempt {attempt})",
   "verify.giveUp": "{n} check(s) still failing after the retry budget \u2014 stopping",
+  "budget.session": "session spend: {spent} / budget {budget}",
+  "budget.hit": "\u25A0 stopped: estimated cost reached the budget of {budget}",
+  // usage analytics
+  "usage.header": "Usage (tokens / estimated cost) per day:",
+  "usage.empty": "No usage recorded yet. Run a task to start tracking.",
+  "usage.total": "total",
+  "usage.runs": "runs",
   // repl
   "repl.welcome": "Polypus interactive session.",
   "repl.welcomeHint": " Type /help for commands, /exit to quit.",
@@ -351,6 +360,8 @@ var ptBR = {
   "cli.opt.maxSteps": "n\xFAmero m\xE1ximo de passos do agente",
   "cli.opt.json": "modo headless: emite um \xFAnico objeto JSON (passos, tool calls, arquivos alterados, uso) em vez da TUI \u2014 use com --mode bypass",
   "cli.opt.verify": "ap\xF3s o agente terminar, roda as checagens do projeto (typecheck/build/test) e itera at\xE9 passar",
+  "cli.opt.budget": "interrompe a execu\xE7\xE3o quando o custo estimado da sess\xE3o atingir este valor em USD (pre\xE7os do OpenRouter)",
+  "cli.cmd.usage": "Mostra analytics de tokens/custo agregados por dia",
   "cli.arg.swarmTask": "tarefa de alto n\xEDvel para dividir entre os agentes",
   "cli.opt.agents": "nomes de agentes separados por v\xEDrgula (padr\xE3o: todos)",
   "cli.opt.maxSubtasks": "n\xFAmero m\xE1ximo de subtarefas paralelas",
@@ -385,6 +396,13 @@ var ptBR = {
   "verify.passed": "verifica\xE7\xE3o passou",
   "verify.failed": "{n} checagem(ns) falharam \u2014 devolvendo a sa\xEDda ao agente (tentativa {attempt})",
   "verify.giveUp": "{n} checagem(ns) ainda falhando ap\xF3s o limite de tentativas \u2014 parando",
+  "budget.session": "gasto da sess\xE3o: {spent} / or\xE7amento {budget}",
+  "budget.hit": "\u25A0 interrompido: o custo estimado atingiu o or\xE7amento de {budget}",
+  // usage analytics
+  "usage.header": "Uso (tokens / custo estimado) por dia:",
+  "usage.empty": "Nenhum uso registrado ainda. Rode uma tarefa para come\xE7ar a medir.",
+  "usage.total": "total",
+  "usage.runs": "execu\xE7\xF5es",
   "repl.welcome": "Sess\xE3o interativa do Polypus.",
   "repl.welcomeHint": " Digite /help para comandos, /exit para sair.",
   "repl.modeChanged": "modo \u2192 {mode}",
@@ -2096,9 +2114,9 @@ async function runAgent(opts) {
   let failStreak = 0;
   const maxToolRetries = opts.maxToolRetries ?? 3;
   const autoCorrect = opts.autoCorrect ?? true;
-  const usage = { promptTokens: 0, completionTokens: 0 };
+  const usage2 = { promptTokens: 0, completionTokens: 0 };
   for (let step = 1; step <= maxSteps; step++) {
-    if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step - 1, messages, usage };
+    if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step - 1, messages, usage: usage2 };
     events?.onStep?.(step);
     let response;
     try {
@@ -2109,12 +2127,12 @@ async function runAgent(opts) {
         signal: opts.signal
       });
     } catch (err) {
-      if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step, messages, usage };
+      if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step, messages, usage: usage2 };
       throw err;
     }
-    usage.promptTokens += response.usage?.promptTokens ?? 0;
-    usage.completionTokens += response.usage?.completionTokens ?? 0;
-    events?.onUsage?.(usage);
+    usage2.promptTokens += response.usage?.promptTokens ?? 0;
+    usage2.completionTokens += response.usage?.completionTokens ?? 0;
+    events?.onUsage?.(usage2);
     const { toolCalls, text: text2 } = driver.parse(response);
     messages.push(driver.assistantMessage(response, toolCalls));
     if (text2) events?.onAssistantText?.(text2);
@@ -2128,7 +2146,7 @@ async function runAgent(opts) {
           messages.push({ role: "user", content: guidance });
           continue;
         }
-        return { finished: false, reason: "stalled", steps: step, messages, usage };
+        return { finished: false, reason: "stalled", steps: step, messages, usage: usage2 };
       }
       const stalled = text2.trim().length === 0 || looksLikeStall(text2);
       if (stalled) {
@@ -2138,17 +2156,17 @@ async function runAgent(opts) {
           messages.push(driver.repromptMessage());
           continue;
         }
-        return { finished: false, reason: "stalled", steps: step, messages, usage };
+        return { finished: false, reason: "stalled", steps: step, messages, usage: usage2 };
       }
-      return { finished: false, reason: "reply", steps: step, messages, usage };
+      return { finished: false, reason: "reply", steps: step, messages, usage: usage2 };
     }
     consecutiveNoTool = 0;
     for (const call of toolCalls) {
-      if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step, messages, usage };
+      if (opts.signal?.aborted) return { finished: false, reason: "cancelled", steps: step, messages, usage: usage2 };
       events?.onToolCall?.(call);
       if (call.name === "finish") {
         const summary = String(call.arguments.summary ?? "").trim();
-        return { finished: true, reason: "finished", summary, steps: step, messages, usage };
+        return { finished: true, reason: "finished", summary, steps: step, messages, usage: usage2 };
       }
       const tool = getTool(call.name);
       const result = tool ? await tool.run(call.arguments, ctx) : { ok: false, output: `Unknown tool "${call.name}". Available: ${toolSpecs().map((t2) => t2.name).join(", ")}` };
@@ -2186,12 +2204,12 @@ ${guidance}`;
         failStreak = sig === lastFailSig ? failStreak + 1 : 1;
         lastFailSig = sig;
         if (failStreak >= maxToolRetries) {
-          return { finished: false, reason: "stalled", steps: step, messages, usage };
+          return { finished: false, reason: "stalled", steps: step, messages, usage: usage2 };
         }
       }
     }
   }
-  return { finished: false, reason: "maxsteps", steps: maxSteps, messages, usage };
+  return { finished: false, reason: "maxsteps", steps: maxSteps, messages, usage: usage2 };
 }
 
 // src/core/context/mentions.ts
@@ -2296,6 +2314,153 @@ function clamp2(s) {
   return s.length > MAX_OUTPUT3 ? s.slice(-MAX_OUTPUT3) : s;
 }
 
+// src/core/agent/usage.ts
+import { appendFile, mkdir as mkdir3, readFile as readFile10 } from "fs/promises";
+import { join as join4 } from "path";
+
+// src/core/providers/openrouter.ts
+var MODELS_URL = "https://openrouter.ai/api/v1/models";
+async function listOpenRouterModels(apiKey, timeoutMs = 8e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(MODELS_URL, {
+      signal: controller.signal,
+      headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {}
+    });
+    if (!res.ok) throw new Error(`OpenRouter ${res.status}: ${await res.text().catch(() => "")}`);
+    const data = await res.json();
+    return (data.data ?? []).map(normalize).filter((m) => m.id.length > 0);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function normalize(m) {
+  const promptPrice = toPerMillion(m.pricing?.prompt);
+  const completionPrice = toPerMillion(m.pricing?.completion);
+  return {
+    id: m.id ?? "",
+    name: m.name ?? m.id ?? "",
+    promptPrice,
+    completionPrice,
+    contextLength: m.context_length ?? 0,
+    supportsTools: (m.supported_parameters ?? []).includes("tools"),
+    free: promptPrice === 0 && completionPrice === 0
+  };
+}
+function toPerMillion(price) {
+  const n = Number(price ?? "0");
+  return Number.isFinite(n) ? n * 1e6 : 0;
+}
+function filterModels(models2, f) {
+  const term = f.search?.trim().toLowerCase();
+  let out = models2.filter((m) => {
+    if (term && !m.id.toLowerCase().includes(term) && !m.name.toLowerCase().includes(term)) {
+      return false;
+    }
+    if (f.tools === "tools" && !m.supportsTools) return false;
+    if (f.tools === "no-tools" && m.supportsTools) return false;
+    if (f.freeOnly && !m.free) return false;
+    if (f.maxPrice !== void 0 && (m.promptPrice < 0 || m.promptPrice > f.maxPrice)) return false;
+    return true;
+  });
+  const key = (m) => m.promptPrice < 0 ? Number.POSITIVE_INFINITY : m.promptPrice;
+  const sort = f.sort ?? "price";
+  out = out.sort((a, b) => {
+    switch (sort) {
+      case "price-desc":
+        return key(b) - key(a);
+      case "context":
+        return b.contextLength - a.contextLength;
+      case "name":
+        return a.id.localeCompare(b.id);
+      default:
+        return key(a) - key(b);
+    }
+  });
+  return out;
+}
+function fmtPrice(perMillion) {
+  if (perMillion < 0) return "var";
+  if (perMillion === 0) return "free";
+  if (perMillion < 1) return `$${perMillion.toFixed(2)}`;
+  if (perMillion < 100) return `$${perMillion.toFixed(perMillion % 1 ? 1 : 0)}`;
+  return `$${Math.round(perMillion)}`;
+}
+function fmtContext(n) {
+  if (n >= 1e6) return `${Math.round(n / 1e5) / 10}M`;
+  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
+  return String(n);
+}
+
+// src/core/agent/usage.ts
+var catalogCache;
+async function resolveModelPricing(agent) {
+  if (agent.provider !== "openrouter") return void 0;
+  try {
+    catalogCache ??= listOpenRouterModels(resolveSecret(agent.apiKey));
+    const models2 = await catalogCache;
+    const m = models2.find((x) => x.id === agent.model);
+    if (!m || m.promptPrice < 0 || m.completionPrice < 0) return void 0;
+    return { promptPrice: m.promptPrice, completionPrice: m.completionPrice };
+  } catch {
+    return void 0;
+  }
+}
+function estimateCost(usage2, pricing) {
+  return usage2.promptTokens / 1e6 * pricing.promptPrice + usage2.completionTokens / 1e6 * pricing.completionPrice;
+}
+function fmtUsd(n) {
+  if (n <= 0) return "US$0.00";
+  if (n < 0.01) return `US$${n.toFixed(4)}`;
+  return `US$${n.toFixed(2)}`;
+}
+function usagePath() {
+  return join4(configDir(), "usage.jsonl");
+}
+async function recordUsage(entry) {
+  try {
+    await mkdir3(configDir(), { recursive: true });
+    await appendFile(usagePath(), JSON.stringify(entry) + "\n", "utf8");
+  } catch {
+  }
+}
+async function aggregateUsage() {
+  let text2 = "";
+  try {
+    text2 = await readFile10(usagePath(), "utf8");
+  } catch {
+    return { days: [], total: emptyBucket("total") };
+  }
+  const byDay = /* @__PURE__ */ new Map();
+  const total = emptyBucket("total");
+  for (const line of text2.split("\n")) {
+    if (!line.trim()) continue;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const date = (e.ts ?? "").slice(0, 10) || "unknown";
+    const bucket = byDay.get(date) ?? emptyBucket(date);
+    accumulate(bucket, e);
+    byDay.set(date, bucket);
+    accumulate(total, e);
+  }
+  const days = [...byDay.values()].sort((a, b) => a.date.localeCompare(b.date));
+  return { days, total };
+}
+function emptyBucket(date) {
+  return { date, promptTokens: 0, completionTokens: 0, costUsd: 0, runs: 0 };
+}
+function accumulate(bucket, e) {
+  bucket.promptTokens += e.promptTokens ?? 0;
+  bucket.completionTokens += e.completionTokens ?? 0;
+  bucket.costUsd += e.costUsd ?? 0;
+  bucket.runs += 1;
+}
+
 // src/cli/commands/json-output.ts
 var OUTPUT_PREVIEW = 500;
 function createJsonCollector() {
@@ -2381,81 +2546,6 @@ async function listOllamaModels(host = ollamaHost(), timeoutMs = 2e3) {
   }
 }
 
-// src/core/providers/openrouter.ts
-var MODELS_URL = "https://openrouter.ai/api/v1/models";
-async function listOpenRouterModels(apiKey, timeoutMs = 8e3) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetch(MODELS_URL, {
-      signal: controller.signal,
-      headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {}
-    });
-    if (!res.ok) throw new Error(`OpenRouter ${res.status}: ${await res.text().catch(() => "")}`);
-    const data = await res.json();
-    return (data.data ?? []).map(normalize).filter((m) => m.id.length > 0);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function normalize(m) {
-  const promptPrice = toPerMillion(m.pricing?.prompt);
-  const completionPrice = toPerMillion(m.pricing?.completion);
-  return {
-    id: m.id ?? "",
-    name: m.name ?? m.id ?? "",
-    promptPrice,
-    completionPrice,
-    contextLength: m.context_length ?? 0,
-    supportsTools: (m.supported_parameters ?? []).includes("tools"),
-    free: promptPrice === 0 && completionPrice === 0
-  };
-}
-function toPerMillion(price) {
-  const n = Number(price ?? "0");
-  return Number.isFinite(n) ? n * 1e6 : 0;
-}
-function filterModels(models2, f) {
-  const term = f.search?.trim().toLowerCase();
-  let out = models2.filter((m) => {
-    if (term && !m.id.toLowerCase().includes(term) && !m.name.toLowerCase().includes(term)) {
-      return false;
-    }
-    if (f.tools === "tools" && !m.supportsTools) return false;
-    if (f.tools === "no-tools" && m.supportsTools) return false;
-    if (f.freeOnly && !m.free) return false;
-    if (f.maxPrice !== void 0 && (m.promptPrice < 0 || m.promptPrice > f.maxPrice)) return false;
-    return true;
-  });
-  const key = (m) => m.promptPrice < 0 ? Number.POSITIVE_INFINITY : m.promptPrice;
-  const sort = f.sort ?? "price";
-  out = out.sort((a, b) => {
-    switch (sort) {
-      case "price-desc":
-        return key(b) - key(a);
-      case "context":
-        return b.contextLength - a.contextLength;
-      case "name":
-        return a.id.localeCompare(b.id);
-      default:
-        return key(a) - key(b);
-    }
-  });
-  return out;
-}
-function fmtPrice(perMillion) {
-  if (perMillion < 0) return "var";
-  if (perMillion === 0) return "free";
-  if (perMillion < 1) return `$${perMillion.toFixed(2)}`;
-  if (perMillion < 100) return `$${perMillion.toFixed(perMillion % 1 ? 1 : 0)}`;
-  return `$${Math.round(perMillion)}`;
-}
-function fmtContext(n) {
-  if (n >= 1e6) return `${Math.round(n / 1e5) / 10}M`;
-  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
-  return String(n);
-}
-
 // src/ui/wizard.ts
 function bail(value) {
   if (p.isCancel(value)) {
@@ -3136,7 +3226,7 @@ import pc7 from "picocolors";
 // src/core/git/worktree.ts
 import { mkdtemp } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { simpleGit } from "simple-git";
 async function ensureRepo(workspace) {
   const git = simpleGit(workspace);
@@ -3157,7 +3247,7 @@ async function identityArgs(git) {
 }
 async function createWorktree(git, label) {
   const branch = `polypus/${label}-${Date.now().toString(36)}`;
-  const path = await mkdtemp(join4(tmpdir(), "polypus-wt-"));
+  const path = await mkdtemp(join5(tmpdir(), "polypus-wt-"));
   await git.raw(["worktree", "add", "-b", branch, path, "HEAD"]);
   return { path, branch };
 }
@@ -3597,7 +3687,9 @@ async function run(task, opts) {
     deny: config.permissions.deny,
     allowedCommands: config.permissions.allowedCommands,
     maxSteps: opts.maxSteps ? Number(opts.maxSteps) : void 0,
-    history: []
+    history: [],
+    budget: opts.budget ? Number(opts.budget) : void 0,
+    costUsd: 0
   };
   const runTask = async (taskText) => {
     const active = resolveAgent(config, session.agentName);
@@ -3621,6 +3713,9 @@ async function run(task, opts) {
       );
     }
     await executeTask(task, resolved2, workspace, session, opts.json ?? false, opts.verify ?? false);
+    if (session.budget !== void 0 && !opts.json) {
+      console.log(pc8.dim(t("budget.session", { spent: fmtUsd(session.costUsd), budget: fmtUsd(session.budget) })));
+    }
     return;
   }
   const resolved = createProvider(agentConfig);
@@ -3657,6 +3752,21 @@ async function executeTask(task, resolved, workspace, session, json = false, ver
   const controller = new AbortController();
   const cancel2 = listenForCancel(controller);
   const collector = json ? createJsonCollector() : void 0;
+  const pricing = await resolveModelPricing(resolved.config);
+  let budgetHit = false;
+  const baseEvents = collector ? collector.events : renderEvents(spinner3);
+  const events = {
+    ...baseEvents,
+    onUsage(u) {
+      baseEvents.onUsage?.(u);
+      if (session.budget !== void 0 && pricing && !controller.signal.aborted) {
+        if (session.costUsd + estimateCost(u, pricing) >= session.budget) {
+          budgetHit = true;
+          controller.abort();
+        }
+      }
+    }
+  };
   const permissions = new PermissionEngine({
     mode: session.mode,
     policy: { workspace, allow: session.allow, deny: session.deny },
@@ -3679,7 +3789,7 @@ async function executeTask(task, resolved, workspace, session, json = false, ver
     history: session.history,
     maxSteps: session.maxSteps,
     signal: controller.signal,
-    events: collector ? collector.events : renderEvents(spinner3)
+    events
   });
   if (!json) spinner3.start(t("ui.thinking"));
   let result;
@@ -3693,10 +3803,24 @@ async function executeTask(task, resolved, workspace, session, json = false, ver
     spinner3.stop();
     cancel2.dispose();
   }
+  const runCost = pricing ? estimateCost(result.usage, pricing) : 0;
+  session.costUsd += runCost;
+  await recordUsage({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    agent: resolved.config.name,
+    provider: resolved.config.provider,
+    model: resolved.config.model,
+    promptTokens: result.usage.promptTokens,
+    completionTokens: result.usage.completionTokens,
+    costUsd: runCost
+  });
   if (collector) {
     process.stdout.write(JSON.stringify(collector.build(result)) + "\n");
     return;
   }
+  if (budgetHit) {
+    console.log(pc8.yellow("\n" + t("budget.hit", { budget: fmtUsd(session.budget ?? 0) })));
+  }
   if (result.reason === "finished") {
     console.log(pc8.green("\n" + t("run.done", { steps: result.steps })) + (result.summary ? ` ${result.summary}` : ""));
   } else if (result.reason === "cancelled") {
@@ -3706,15 +3830,13 @@ async function executeTask(task, resolved, workspace, session, json = false, ver
   }
   if (result.usage.promptTokens || result.usage.completionTokens) {
     const total = result.usage.promptTokens + result.usage.completionTokens;
-    console.log(
-      pc8.dim(
-        "\u21B3 " + t("ui.tokens", {
-          total: fmtTokens(total),
-          in: fmtTokens(result.usage.promptTokens),
-          out: fmtTokens(result.usage.completionTokens)
-        })
-      )
-    );
+    const tokensLine = t("ui.tokens", {
+      total: fmtTokens(total),
+      in: fmtTokens(result.usage.promptTokens),
+      out: fmtTokens(result.usage.completionTokens)
+    });
+    const cost = pricing ? ` \xB7 ~${fmtUsd(runCost)}` : "";
+    console.log(pc8.dim("\u21B3 " + tokensLine + cost));
   }
 }
 function fmtTokens(n) {
@@ -3816,8 +3938,8 @@ function renderEvents(spinner3) {
     onStep() {
       spinner3.start(t("ui.thinking"));
     },
-    onUsage(usage) {
-      const total = usage.promptTokens + usage.completionTokens;
+    onUsage(usage2) {
+      const total = usage2.promptTokens + usage2.completionTokens;
       if (total > 0) spinner3.setSuffix(t("ui.tokensShort", { total: fmtTokens(total) }));
     },
     onAssistantText(text2) {
@@ -3855,8 +3977,8 @@ async function setup() {
 import pc9 from "picocolors";
 
 // src/core/scaffold/init.ts
-import { mkdir as mkdir3, writeFile as writeFile4, access } from "fs/promises";
-import { dirname as dirname3, join as join5 } from "path";
+import { mkdir as mkdir4, writeFile as writeFile4, access } from "fs/promises";
+import { dirname as dirname3, join as join6 } from "path";
 
 // src/core/scaffold/templates.ts
 function polyTemplates(locale) {
@@ -4099,12 +4221,12 @@ async function scaffoldPoly(workspace, opts) {
   const skipped = [];
   for (const [rel, content] of Object.entries(templates)) {
     const display = `.poly/${rel}`;
-    const abs = join5(workspace, ".poly", ...rel.split("/"));
+    const abs = join6(workspace, ".poly", ...rel.split("/"));
     if (!opts.force && await exists(abs)) {
       skipped.push(display);
       continue;
     }
-    await mkdir3(dirname3(abs), { recursive: true });
+    await mkdir4(dirname3(abs), { recursive: true });
     await writeFile4(abs, content, "utf8");
     created.push(display);
   }
@@ -4198,11 +4320,32 @@ async function resolveOpenRouterKey() {
   }
 }
 
+// src/cli/commands/usage.ts
+import pc11 from "picocolors";
+async function usage() {
+  const { days, total } = await aggregateUsage();
+  if (days.length === 0) {
+    console.log(pc11.yellow(t("usage.empty")));
+    return;
+  }
+  console.log(pc11.bold(t("usage.header")));
+  for (const d of days) console.log("  " + formatRow(d));
+  console.log(pc11.dim("  " + "\u2500".repeat(40)));
+  console.log("  " + pc11.bold(formatRow({ ...total, date: t("usage.total") })));
+}
+function formatRow(b) {
+  const tokens2 = fmtTokens2(b.promptTokens + b.completionTokens);
+  return `${b.date.padEnd(12)} ${tokens2.padStart(7)} tok   ${fmtUsd(b.costUsd).padStart(10)}   (${b.runs} ${t("usage.runs")})`;
+}
+function fmtTokens2(n) {
+  return n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n);
+}
+
 // src/cli/commands/prd.ts
-import { writeFile as writeFile5, readFile as readFile10 } from "fs/promises";
+import { writeFile as writeFile5, readFile as readFile11 } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify as promisify3 } from "util";
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 
 // src/core/agent/prd.ts
 var SYSTEM = [
@@ -4331,14 +4474,14 @@ async function prd(issueRef, opts) {
   const markdown = await withRetry(() => generatePrd(issue, provider, guide));
   if (opts.out) {
     await writeFile5(opts.out, markdown + "\n", "utf8");
-    console.error(pc11.green(t("prd.wrote", { path: opts.out })));
+    console.error(pc12.green(t("prd.wrote", { path: opts.out })));
   } else {
     process.stdout.write(markdown + "\n");
   }
 }
 async function loadIssue(issueRef, input) {
   if (input) {
-    const raw = input === "-" ? await readStdin() : await readFile10(input, "utf8");
+    const raw = input === "-" ? await readStdin() : await readFile11(input, "utf8");
     return normalize2(JSON.parse(stripBom(raw)));
   }
   const num = numericRef(issueRef);
@@ -4357,10 +4500,10 @@ function normalize2(raw) {
 }
 
 // src/cli/commands/review.ts
-import { writeFile as writeFile6, readFile as readFile11 } from "fs/promises";
+import { writeFile as writeFile6, readFile as readFile12 } from "fs/promises";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify4 } from "util";
-import pc12 from "picocolors";
+import pc13 from "picocolors";
 
 // src/core/agent/review.ts
 var MAX_DIFF_CHARS = Number(process.env.POLYPUS_MAX_DIFF_CHARS) || 6e4;
@@ -4427,13 +4570,13 @@ async function review(prRef, opts) {
   const markdown = await withRetry(() => reviewDiff(diff, meta, provider, guide));
   if (opts.out) {
     await writeFile6(opts.out, markdown + "\n", "utf8");
-    console.error(pc12.green(t("review.wrote", { path: opts.out })));
+    console.error(pc13.green(t("review.wrote", { path: opts.out })));
   } else {
     process.stdout.write(markdown + "\n");
   }
 }
 async function loadDiff(num, input) {
-  if (input) return input === "-" ? readStdin() : readFile11(input, "utf8");
+  if (input) return input === "-" ? readStdin() : readFile12(input, "utf8");
   const { stdout: stdout2 } = await exec4("gh", ["pr", "diff", num]);
   return stdout2;
 }
@@ -4445,7 +4588,7 @@ async function loadMeta(num, input) {
 }
 
 // src/cli/index.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/core/config/dotenv.ts
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
@@ -4478,7 +4621,7 @@ async function launchInteractive() {
   const config = await loadConfig();
   if (config.agents.length === 0) {
     console.log(banner());
-    console.log("  " + pc13.yellow(t("welcome.firstRun")) + "\n");
+    console.log("  " + pc14.yellow(t("welcome.firstRun")) + "\n");
     await setup();
   }
   await run(void 0, {});
@@ -4505,20 +4648,21 @@ function buildProgram() {
   program.command("add-agent").argument("<name>", t("cli.arg.addAgentName")).requiredOption("--provider <provider>", t("cli.opt.provider")).requiredOption("--model <model>", t("cli.opt.model")).option("--api-key <key>", t("cli.opt.apiKey")).option("--base-url <url>", t("cli.opt.baseUrl")).option("--tool-mode <mode>", t("cli.opt.toolMode"), "auto").option("--set-default", t("cli.opt.setDefault")).description(t("cli.cmd.addAgent")).action((name, opts) => addAgent(name, opts));
   program.command("remove-agent").argument("<name>", t("cli.arg.removeAgentName")).description(t("cli.cmd.removeAgent")).action((name) => removeAgent(name));
   program.command("list-agents").alias("agents").description(t("cli.cmd.listAgents")).action(() => listAgents());
-  program.command("run").argument("[task]", t("cli.arg.runTask")).option("--agent <name>", t("cli.opt.agent")).option("--mode <mode>", t("cli.opt.mode")).option("--max-steps <n>", t("cli.opt.maxSteps")).option("--json", t("cli.opt.json")).option("--verify", t("cli.opt.verify")).description(t("cli.cmd.run")).action((task, opts) => run(task, opts));
+  program.command("run").argument("[task]", t("cli.arg.runTask")).option("--agent <name>", t("cli.opt.agent")).option("--mode <mode>", t("cli.opt.mode")).option("--max-steps <n>", t("cli.opt.maxSteps")).option("--json", t("cli.opt.json")).option("--verify", t("cli.opt.verify")).option("--budget <usd>", t("cli.opt.budget")).description(t("cli.cmd.run")).action((task, opts) => run(task, opts));
   program.command("swarm").argument("<task>", t("cli.arg.swarmTask")).option("--agents <names>", t("cli.opt.agents")).option("--max-subtasks <n>", t("cli.opt.maxSubtasks")).description(t("cli.cmd.swarm")).action((task, opts) => swarm(task, opts));
   program.command("models").option("--search <text>", t("cli.opt.search")).option("--tools", t("cli.opt.toolsOnly")).option("--free", t("cli.opt.free")).option("--max-price <usd>", t("cli.opt.maxPrice")).option("--sort <order>", t("cli.opt.sort")).option("--limit <n>", t("cli.opt.limit")).description(t("cli.cmd.models")).action((opts) => models(opts));
+  program.command("usage").description(t("cli.cmd.usage")).action(() => usage());
   program.command("prd").argument("<issue>", t("cli.arg.prdIssue")).option("--out <file>", t("cli.opt.out")).option("--model <model>", t("cli.opt.model")).option("--input <file>", t("cli.opt.input")).description(t("cli.cmd.prd")).action((issue, opts) => prd(issue, opts));
   program.command("review").argument("<pr>", t("cli.arg.reviewPr")).option("--out <file>", t("cli.opt.out")).option("--model <model>", t("cli.opt.model")).option("--input <file>", t("cli.opt.input")).description(t("cli.cmd.review")).action((pr, opts) => review(pr, opts));
   return program;
 }
 async function main() {
   try {
-    loadDotenv([join6(configDir(), ".env"), join6(process.cwd(), ".env")]);
+    loadDotenv([join7(configDir(), ".env"), join7(process.cwd(), ".env")]);
     await resolveLocale();
     await buildProgram().parseAsync(process.argv);
   } catch (err) {
-    console.error(pc13.red(`\u2717 ${err.message}`));
+    console.error(pc14.red(`\u2717 ${err.message}`));
     process.exitCode = 1;
   }
 }