@gaberrb/polypus 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,11 @@
 # Polypus 🐙
 
+[![CI](https://github.com/GaberRB/polypus/actions/workflows/ci.yml/badge.svg)](https://github.com/GaberRB/polypus/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@gaberrb/polypus?color=9266F5&logo=npm)](https://www.npmjs.com/package/@gaberrb/polypus)
+[![license](https://img.shields.io/badge/license-MIT-AB8EFA)](LICENSE)
+
+**📖 Site:** https://gaberrb.github.io/polypus/ · **📦 npm:** [`@gaberrb/polypus`](https://www.npmjs.com/package/@gaberrb/polypus)
+
 An agentic coding harness that makes **any** AI API generate and apply code —
 even models **without** native tool-calling. Bring your own keys: OpenRouter,
 Ollama, Anthropic, or any OpenAI-compatible endpoint. Run one agent, or split a
@@ -221,6 +227,20 @@ npm run typecheck
 npm test           # vitest
 ```
 
+## Contributing
+
+Contributions are welcome — but **open an issue first**. Issues are triaged and labeled
+`accepted` before any PR; PRs without a linked accepted issue don't pass CI. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the full flow (issue → `accepted` → branch → PR → review).
+
+## Apoie o projeto
+
+Se o Polypus te ajudou, você pode apoiar o desenvolvimento via **PIX** 💜
+
+> **Chave PIX (e-mail):** `gabrielriosbelmiro@gmail.com`
+
+Qualquer valor é muito bem-vindo e ajuda a manter o projeto vivo. Obrigado!
+
 ## Author
 
 **Gabriel Rios**

package/dist/index.js

@@ -121,6 +121,7 @@ var en = {
   "run.stopped": "\u26A0 Stopped after {steps} steps without a finish signal. You can continue with another instruction.",
   "run.confirm": "Allow {summary}?",
   "run.reprompt": "\u21BB no tool call \u2014 reinforcing instructions (attempt {attempt})",
+  "run.autocorrect": "\u21BB tool failed \u2014 auto-correcting with extra context",
   "run.cancelled": "\u25A0 cancelled",
   // repl
   "repl.welcome": "Polypus interactive session.",
@@ -308,6 +309,7 @@ var ptBR = {
   "run.stopped": "\u26A0 Parou ap\xF3s {steps} passos sem sinal de conclus\xE3o. Voc\xEA pode continuar com outra instru\xE7\xE3o.",
   "run.confirm": "Permitir {summary}?",
   "run.reprompt": "\u21BB nenhuma chamada de tool \u2014 refor\xE7ando instru\xE7\xF5es (tentativa {attempt})",
+  "run.autocorrect": "\u21BB tool falhou \u2014 autocorrigindo com contexto extra",
   "run.cancelled": "\u25A0 cancelado",
   "repl.welcome": "Sess\xE3o interativa do Polypus.",
   "repl.welcomeHint": " Digite /help para comandos, /exit para sair.",
@@ -1442,6 +1444,182 @@ function getTool(name) {
   return TOOLS[name];
 }
 
+// src/core/agent/correction.ts
+import { readFile as readFile4, readdir as readdir2 } from "fs/promises";
+import { dirname as dirname2, resolve as resolve6 } from "path";
+async function buildCorrection(call, output, deps) {
+  const deterministic = await deterministicCorrection(call, output, deps);
+  if (deterministic) return deterministic;
+  if (deps.escalate) return deps.escalate({ call, output, toolSpec: deps.toolSpec });
+  return null;
+}
+async function deterministicCorrection(call, output, deps) {
+  const path = typeof call.arguments.path === "string" ? call.arguments.path : void 0;
+  if (call.name === "edit_file" && /was not found/i.test(output) && path) {
+    const search = typeof call.arguments.search === "string" ? call.arguments.search : "";
+    const snippet = await snippetNearSearch(deps.workspace, path, search);
+    if (snippet) {
+      return [
+        "AUTO-CORRECTION \u2014 the 'search' text does not exist verbatim in the file.",
+        "Here is the file's actual content (line-numbered). Copy the 'search' value EXACTLY",
+        "from these lines (including indentation and whitespace), then resend edit_file:",
+        "",
+        snippet
+      ].join("\n");
+    }
+  }
+  if (call.name === "edit_file" && /matched \d+ times/i.test(output) && path) {
+    const search = typeof call.arguments.search === "string" ? call.arguments.search : "";
+    const lines = await occurrenceLines(deps.workspace, path, search);
+    if (lines.length > 0) {
+      return [
+        `AUTO-CORRECTION \u2014 the 'search' text is not unique; it appears at lines ${lines.join(", ")}.`,
+        "Add more surrounding lines to 'search' so it matches exactly one location, then resend."
+      ].join("\n");
+    }
+  }
+  if (/ENOENT|no such file/i.test(output) && path) {
+    const listing = await listNearest(deps.workspace, path);
+    if (listing) {
+      return [
+        "AUTO-CORRECTION \u2014 that path does not exist. Nearby existing entries:",
+        "",
+        listing,
+        "",
+        "Use list_dir to confirm the correct path, or create the parent directory first."
+      ].join("\n");
+    }
+  }
+  if (/denied|not allowed/i.test(output)) {
+    return [
+      "AUTO-CORRECTION \u2014 this action was blocked by the permission policy.",
+      `Editable paths (glob allow-list): ${deps.allow.join(", ") || "(none)"}.`,
+      "Target a path inside the allow-list, or stop and report that the change is out of scope."
+    ].join("\n");
+  }
+  if (deps.toolSpec && /needs .* arguments|Invalid|required|Resend the tool call/i.test(output)) {
+    return [
+      "AUTO-CORRECTION \u2014 the call had missing or invalid arguments. Expected schema:",
+      "",
+      formatSchema(deps.toolSpec),
+      "",
+      "Resend the tool call with every required argument filled in."
+    ].join("\n");
+  }
+  return null;
+}
+function makeLLMEscalator(provider) {
+  return async ({ call, output, toolSpec }) => {
+    const prompt = [
+      "A tool call just failed. Diagnose WHY in one or two sentences, then give a concrete,",
+      "actionable instruction for how to correct the call. Do not apologize and do not call any tool.",
+      "",
+      `Tool: ${call.name}`,
+      `Arguments: ${JSON.stringify(call.arguments)}`,
+      `Error: ${output}`,
+      toolSpec ? `Schema: ${JSON.stringify(toolSpec.parameters)}` : ""
+    ].join("\n");
+    try {
+      const res = await provider.chat({
+        messages: [
+          { role: "system", content: "You are a debugging assistant for an autonomous coding agent." },
+          { role: "user", content: prompt }
+        ],
+        params: { maxTokens: 400 }
+      });
+      const text2 = res.content.trim();
+      return text2 ? `AUTO-CORRECTION (diagnosis):
+${text2}` : null;
+    } catch {
+      return null;
+    }
+  };
+}
+async function readWorkspaceFile(workspace, path) {
+  try {
+    return await readFile4(resolve6(workspace, path), "utf8");
+  } catch {
+    return null;
+  }
+}
+function numberedWindow(content, center2, radius) {
+  const lines = content.split("\n");
+  const start = Math.max(0, center2 - radius);
+  const end = Math.min(lines.length, center2 + radius + 1);
+  const width = String(end).length;
+  return lines.slice(start, end).map((line, i) => `${String(start + i + 1).padStart(width, " ")} | ${line}`).join("\n");
+}
+async function snippetNearSearch(workspace, path, search) {
+  const content = await readWorkspaceFile(workspace, path);
+  if (content === null) return null;
+  const lines = content.split("\n");
+  const anchor = bestAnchorLine(lines, search);
+  return numberedWindow(content, anchor >= 0 ? anchor : 0, 6);
+}
+function bestAnchorLine(lines, search) {
+  const target = search.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  if (!target) return -1;
+  const targetWords = new Set(tokens(target));
+  let best = -1;
+  let bestScore = 0;
+  lines.forEach((line, i) => {
+    if (line.includes(target)) {
+      if (bestScore < Number.MAX_SAFE_INTEGER) {
+        best = i;
+        bestScore = Number.MAX_SAFE_INTEGER;
+      }
+      return;
+    }
+    const score = tokens(line).filter((w) => targetWords.has(w)).length;
+    if (score > bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  });
+  return best;
+}
+function tokens(s) {
+  return s.split(/\W+/).filter((w) => w.length > 0);
+}
+async function occurrenceLines(workspace, path, search) {
+  const content = await readWorkspaceFile(workspace, path);
+  if (content === null || search.length === 0) return [];
+  const out = [];
+  let from = 0;
+  for (; ; ) {
+    const idx = content.indexOf(search, from);
+    if (idx === -1) break;
+    out.push(content.slice(0, idx).split("\n").length);
+    from = idx + search.length;
+  }
+  return out;
+}
+async function listNearest(workspace, path) {
+  let dir = dirname2(resolve6(workspace, path));
+  for (let i = 0; i < 8; i++) {
+    try {
+      const entries = await readdir2(dir, { withFileTypes: true });
+      const rel = dir === resolve6(workspace) ? "." : dir;
+      const names = entries.slice(0, 40).map((e) => e.isDirectory() ? `${e.name}/` : e.name);
+      return `${rel}:
+  ${names.join("  ") || "(empty)"}`;
+    } catch {
+      const parent = dirname2(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+  return null;
+}
+function formatSchema(spec) {
+  const props = spec.parameters.properties ?? {};
+  const required = new Set(spec.parameters.required ?? []);
+  const lines = Object.entries(props).map(
+    ([name, v]) => `  - ${name} (${v.type ?? "any"}, ${required.has(name) ? "required" : "optional"})` + (v.description ? `: ${v.description}` : "")
+  );
+  return lines.join("\n") || "  (no parameters)";
+}
+
 // src/core/agent/loop.ts
 function looksLikeStall(text2) {
   const lc = text2.toLowerCase();
@@ -1492,6 +1670,7 @@ async function runAgent(opts) {
   let lastFailSig = "";
   let failStreak = 0;
   const maxToolRetries = opts.maxToolRetries ?? 3;
+  const autoCorrect = opts.autoCorrect ?? true;
   const usage = { 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 };
@@ -1538,12 +1717,29 @@ async function runAgent(opts) {
       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(", ")}` };
       events?.onToolResult?.(call, result);
-      messages.push(driver.toolResultMessage(call, result.output));
+      const sig = `${call.name}:${JSON.stringify(call.arguments)}`;
+      let resultText = result.output;
+      if (!result.ok && autoCorrect) {
+        const guidance = await buildCorrection(call, result.output, {
+          workspace: opts.workspace,
+          allow: opts.promptContext.allow,
+          toolSpec: tool?.spec,
+          // Only spend a fixer-LLM call once the model has already repeated a
+          // failing call — the first failure gets deterministic help for free.
+          escalate: sig === lastFailSig ? makeLLMEscalator(agent.provider) : void 0
+        });
+        if (guidance) {
+          resultText = `${result.output}
+
+${guidance}`;
+          events?.onCorrection?.(call, guidance);
+        }
+      }
+      messages.push(driver.toolResultMessage(call, resultText));
       if (result.ok) {
         failStreak = 0;
         lastFailSig = "";
       } else {
-        const sig = `${call.name}:${JSON.stringify(call.arguments)}`;
         failStreak = sig === lastFailSig ? failStreak + 1 : 1;
         lastFailSig = sig;
         if (failStreak >= maxToolRetries) {
@@ -2403,6 +2599,10 @@ function renderEvents(spinner3) {
     onReprompt(attempt) {
       spinner3.stop();
       console.log(pc7.yellow("  " + t("run.reprompt", { attempt })));
+    },
+    onCorrection() {
+      spinner3.stop();
+      console.log(pc7.yellow("    \u21BB " + t("run.autocorrect")));
     }
   };
 }