@gaberrb/polypus 0.4.16 → 0.4.18

package/README.md

@@ -196,6 +196,17 @@ agent is also instructed to talk back to you in the configured language.
 All file access is restricted to the workspace and the configured **allow-list**
 globs; the **deny-list** (e.g. `.git/**`, `**/.env`) always wins.
 
+### Timeout Configuration
+
+You can control the maximum duration of a swarm session using the environment variable `POLYPUS_SWARM_OVERALL_TIMEOUT_MS` (default: 1 hour). This prevents the session from hanging indefinitely if an agent stalls:
+
+```bash
+export POLYPUS_SWARM_OVERALL_TIMEOUT_MS=1800000  # 30 minutes
+polypus swarm "your task"
+```
+
+Similarly, `POLYPUS_SWARM_IDLE_TIMEOUT_MS` controls the idle timeout for individual workers (default: 5 minutes).
+
 ## Swarm (parallel agents)
 
 ```bash
@@ -207,6 +218,48 @@ worktree (in `bypass` mode, since the worktree is throwaway), and the branches
 are merged back sequentially. Conflicting branches are kept for manual
 inspection rather than force-merged.
 
+## Autonomous agent — the tool self-improving 🤖
+
+Polypus can run **itself** in CI to implement its own issues. Label an issue
+`polypus-go` and the `agent.yml` workflow implements it headlessly, gates on the
+local CI, patch-bumps the version + CHANGELOG, and opens a release-ready PR; when
+you merge it, `auto-release.yml` cuts the GitHub Release and `release.yml`
+publishes the new version to npm. The only human step is the **merge**.
+
+```
+issue + label `polypus-go`
+  → agent.yml: implement (cheap model) → secret scan → CI gate → bump + CHANGELOG → open PR
+  → you merge the PR
+  → auto-release.yml → release.yml → npm publish
+```
+
+**Setup (one-time):**
+
+```bash
+# 1) the trigger label
+gh label create polypus-go --color 5be4b1
+
+# 2) the model key
+gh secret set OPENROUTER_API_KEY --body "sk-or-v1-..."
+
+# 3) a PAT (repo scope) so the agent can open the PR AND the release can publish
+#    (a Release made with the default GITHUB_TOKEN does NOT trigger release.yml)
+gh secret set POLYPUS_PR_TOKEN --body "github_pat_..."
+
+# 4) optional: cheap model + per-run budget
+gh variable set POLYPUS_AGENT_MODEL --body "deepseek/deepseek-chat-v3-0324"
+gh variable set POLYPUS_BUDGET_USD  --body "0.50"
+```
+
+Guard-rails: own-repo only, secret scan on the diff, mandatory CI gate, a spend
+budget, and your merge as the final gate. Without `POLYPUS_PR_TOKEN` nothing
+breaks — the agent still implements and pushes a branch, and comments the branch
+link on the issue instead of failing.
+
+📖 **Full guide with a diagram, examples and the `POLYPUS_PR_TOKEN` walkthrough:**
+[the autonomous-agent page](https://gaberrb.github.io/polypus/agent.html)
+(`docs/agent.html`).
+
 ## Configuration
 
 Stored at `~/.polypus/config.json` (override the directory with `POLYPUS_HOME`).

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import pc15 from "picocolors";
+import pc16 from "picocolors";
 
 // src/cli/commands/add-agent.ts
 import pc from "picocolors";
@@ -113,6 +113,8 @@ var en = {
   "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.cmd.estimate": "Estimate the effort/cost to implement a task (no changes made)",
+  "cli.arg.estimateTask": "task to estimate",
   "cli.cmd.sessions": "List saved sessions that can be resumed",
   "cli.opt.continue": "resume the most recent saved session",
   "cli.opt.resume": "resume a specific saved session by id",
@@ -161,6 +163,12 @@ var en = {
   "usage.empty": "No usage recorded yet. Run a task to start tracking.",
   "usage.total": "total",
   "usage.runs": "runs",
+  // estimate
+  "estimate.header": "Effort estimate:",
+  "estimate.complexity": "complexity",
+  "estimate.steps": "steps",
+  "estimate.tokens": "tokens",
+  "estimate.cost": "estimated cost",
   // sessions
   "sessions.header": "Saved sessions (most recent first):",
   "sessions.empty": "No saved sessions yet.",
@@ -229,6 +237,7 @@ var en = {
   "swarm.conflictsHeader": "\u26A0 {n} branch(es) had merge conflicts (kept for inspection):",
   "swarm.statusDone": "done",
   "swarm.statusIncomplete": "incomplete",
+  "swarm.timeout": "\u26A0 Session timeout reached. Operation aborted.",
   // init
   "init.created": "\u2713 .poly scaffolded:",
   "init.skipped": "Kept (already existed):",
@@ -377,6 +386,8 @@ var ptBR = {
   "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.cmd.estimate": "Estima o esfor\xE7o/custo para implementar uma tarefa (sem alterar nada)",
+  "cli.arg.estimateTask": "tarefa a estimar",
   "cli.cmd.sessions": "Lista as sess\xF5es salvas que podem ser retomadas",
   "cli.opt.continue": "retoma a sess\xE3o salva mais recente",
   "cli.opt.resume": "retoma uma sess\xE3o salva espec\xEDfica pelo id",
@@ -423,6 +434,12 @@ var ptBR = {
   "usage.empty": "Nenhum uso registrado ainda. Rode uma tarefa para come\xE7ar a medir.",
   "usage.total": "total",
   "usage.runs": "execu\xE7\xF5es",
+  // estimate
+  "estimate.header": "Estimativa de esfor\xE7o:",
+  "estimate.complexity": "complexidade",
+  "estimate.steps": "passos",
+  "estimate.tokens": "tokens",
+  "estimate.cost": "custo estimado",
   // sessions
   "sessions.header": "Sess\xF5es salvas (mais recentes primeiro):",
   "sessions.empty": "Nenhuma sess\xE3o salva ainda.",
@@ -489,6 +506,7 @@ var ptBR = {
   "swarm.conflictsHeader": "\u26A0 {n} branch(es) tiveram conflitos de merge (mantidos para inspe\xE7\xE3o):",
   "swarm.statusDone": "ok",
   "swarm.statusIncomplete": "incompleta",
+  "swarm.timeout": "\u26A0 O tempo m\xE1ximo da sess\xE3o foi atingido. A opera\xE7\xE3o foi interrompida.",
   // init
   "init.created": "\u2713 .poly criado:",
   "init.skipped": "Mantidos (j\xE1 existiam):",
@@ -3868,6 +3886,10 @@ function idleTimeoutMs() {
   const raw = Number(process.env.POLYPUS_SWARM_IDLE_TIMEOUT_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_IDLE_TIMEOUT_MS;
 }
+function overallTimeoutMs() {
+  const raw = Number(process.env.POLYPUS_SWARM_OVERALL_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 36e5;
+}
 
 // src/ui/swarm-view.ts
 var RESET2 = "\x1B[0m";
@@ -4092,6 +4114,10 @@ async function runSwarmSession(task, config, opts = {}) {
   const view = new SwarmView(resolved[0].config.name);
   view.start();
   let result;
+  const sessionTimeout = setTimeout(() => {
+    controller.abort();
+    console.log(pc7.red(t("swarm.timeout")));
+  }, overallTimeoutMs());
   try {
     result = await runSwarm({
       task,
@@ -4115,6 +4141,7 @@ async function runSwarmSession(task, config, opts = {}) {
       }
     });
   } finally {
+    clearTimeout(sessionTimeout);
     view.stop();
     cancel2.dispose();
   }
@@ -4895,14 +4922,98 @@ async function sessions() {
   console.log(pc12.dim("\n" + t("sessions.hint")));
 }
 
+// src/cli/commands/estimate.ts
+import pc13 from "picocolors";
+
+// src/core/agent/estimate.ts
+var SYSTEM = [
+  "You estimate the effort for an autonomous coding agent (a ReAct loop that reads/edits files",
+  "and runs commands over several steps) to implement a software task in an existing repo.",
+  "Account for the loop re-sending growing context each step. Be realistic, not optimistic.",
+  "Return ONLY a JSON object, no prose, with exactly these keys:",
+  '{"complexity":"low|medium|high","estimatedSteps":<int>,"estimatedTokens":<int total across all steps>,',
+  '"rationale":"<one sentence>","risks":"<one sentence>"}'
+].join(" ");
+function extractJsonObject(text2) {
+  const start = text2.indexOf("{");
+  if (start === -1) return void 0;
+  let depth = 0;
+  for (let i = start; i < text2.length; i++) {
+    if (text2[i] === "{") depth++;
+    else if (text2[i] === "}" && --depth === 0) {
+      try {
+        return JSON.parse(text2.slice(start, i + 1));
+      } catch {
+        return void 0;
+      }
+    }
+  }
+  return void 0;
+}
+function clampInt(value, min, max, fallback) {
+  const n = Math.round(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+async function estimateTask(task, agent, pricing) {
+  const res = await agent.provider.chat({
+    messages: [
+      { role: "system", content: SYSTEM },
+      { role: "user", content: `Task:
+${task}` }
+    ],
+    params: { temperature: 0 }
+  });
+  const parsed = extractJsonObject(res.content) ?? {};
+  const complexity = ["low", "medium", "high"].includes(parsed.complexity) ? parsed.complexity : "medium";
+  const estimatedSteps = clampInt(parsed.estimatedSteps, 1, 300, 30);
+  const estimatedTokens = clampInt(parsed.estimatedTokens, 1e3, 2e7, 8e4);
+  const rationale = typeof parsed.rationale === "string" ? parsed.rationale : "";
+  const risks = typeof parsed.risks === "string" ? parsed.risks : "";
+  let costUsd;
+  let costLabel = "unknown (no pricing for this model)";
+  if (pricing) {
+    costUsd = estimateCost(
+      { promptTokens: Math.round(estimatedTokens * 0.8), completionTokens: Math.round(estimatedTokens * 0.2) },
+      pricing
+    );
+    costLabel = fmtUsd(costUsd);
+  }
+  return { complexity, estimatedSteps, estimatedTokens, rationale, risks, costUsd, costLabel };
+}
+
+// src/cli/commands/estimate.ts
+async function estimate(task, opts) {
+  const config = await loadConfig();
+  const agentConfig = resolveAgent(config, opts.agent);
+  const resolved = createProvider(agentConfig);
+  const pricing = await resolveModelPricing(resolved.config);
+  const est = await estimateTask(task, resolved, pricing);
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ estimate: est }) + "\n");
+    return;
+  }
+  console.log(pc13.bold(t("estimate.header")));
+  console.log(`  ${t("estimate.complexity")}: ${pc13.cyan(est.complexity)}`);
+  console.log(`  ${t("estimate.steps")}: ~${est.estimatedSteps}`);
+  console.log(`  ${t("estimate.tokens")}: ~${fmtTokens3(est.estimatedTokens)}`);
+  console.log(`  ${t("estimate.cost")}: ${pc13.green(est.costLabel)}`);
+  if (est.rationale) console.log(pc13.dim(`  ${est.rationale}`));
+  if (est.risks) console.log(pc13.dim(`  \u26A0 ${est.risks}`));
+}
+function fmtTokens3(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  return n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n);
+}
+
 // src/cli/commands/prd.ts
 import { writeFile as writeFile6, readFile as readFile14 } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify as promisify5 } from "util";
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 
 // src/core/agent/prd.ts
-var SYSTEM = [
+var SYSTEM2 = [
   "You are a product analyst. You turn a GitHub issue into a concise, structured PRD",
   "(Product Requirements Document) in Markdown.",
   "Rules:",
@@ -4932,7 +5043,7 @@ ${comments}` : "",
   ].join("\n");
 }
 async function generatePrd(issue, provider, projectContext) {
-  const messages = [{ role: "system", content: SYSTEM }];
+  const messages = [{ role: "system", content: SYSTEM2 }];
   if (projectContext) {
     messages.push({
       role: "system",
@@ -5028,7 +5139,7 @@ async function prd(issueRef, opts) {
   const markdown = await withRetry(() => generatePrd(issue, provider, guide));
   if (opts.out) {
     await writeFile6(opts.out, markdown + "\n", "utf8");
-    console.error(pc13.green(t("prd.wrote", { path: opts.out })));
+    console.error(pc14.green(t("prd.wrote", { path: opts.out })));
   } else {
     process.stdout.write(markdown + "\n");
   }
@@ -5057,11 +5168,11 @@ function normalize2(raw) {
 import { writeFile as writeFile7, readFile as readFile15 } from "fs/promises";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify6 } from "util";
-import pc14 from "picocolors";
+import pc15 from "picocolors";
 
 // src/core/agent/review.ts
 var MAX_DIFF_CHARS = Number(process.env.POLYPUS_MAX_DIFF_CHARS) || 6e4;
-var SYSTEM2 = [
+var SYSTEM3 = [
   "You are a senior code reviewer. Review the pull request diff below and report",
   "concrete findings in Markdown.",
   "Rules:",
@@ -5095,7 +5206,7 @@ function buildReviewPrompt(diff, meta) {
 }
 async function reviewDiff(diff, meta, provider, projectGuide) {
   if (!diff.trim()) return "_Sem altera\xE7\xF5es no diff para revisar._";
-  const messages = [{ role: "system", content: SYSTEM2 }];
+  const messages = [{ role: "system", content: SYSTEM3 }];
   if (projectGuide) {
     messages.push({
       role: "system",
@@ -5124,7 +5235,7 @@ async function review(prRef, opts) {
   const markdown = await withRetry(() => reviewDiff(diff, meta, provider, guide));
   if (opts.out) {
     await writeFile7(opts.out, markdown + "\n", "utf8");
-    console.error(pc14.green(t("review.wrote", { path: opts.out })));
+    console.error(pc15.green(t("review.wrote", { path: opts.out })));
   } else {
     process.stdout.write(markdown + "\n");
   }
@@ -5175,7 +5286,7 @@ async function launchInteractive() {
   const config = await loadConfig();
   if (config.agents.length === 0) {
     console.log(banner());
-    console.log("  " + pc15.yellow(t("welcome.firstRun")) + "\n");
+    console.log("  " + pc16.yellow(t("welcome.firstRun")) + "\n");
     await setup();
   }
   await run(void 0, {});
@@ -5206,6 +5317,7 @@ function buildProgram() {
   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("estimate").argument("<task>", t("cli.arg.estimateTask")).option("--agent <name>", t("cli.opt.agent")).option("--json", t("cli.opt.json")).description(t("cli.cmd.estimate")).action((task, opts) => estimate(task, opts));
   program.command("sessions").description(t("cli.cmd.sessions")).action(() => sessions());
   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));
@@ -5217,7 +5329,7 @@ async function main() {
     await resolveLocale();
     await buildProgram().parseAsync(process.argv);
   } catch (err) {
-    console.error(pc15.red(`\u2717 ${err.message}`));
+    console.error(pc16.red(`\u2717 ${err.message}`));
     process.exitCode = 1;
   }
 }