z0gcode 0.3.0 → 0.3.2

package/README.md

@@ -75,7 +75,7 @@ z0g transcribe memo.mp3                                  # transcribe audio on 0
 z0g serve --mcp                                          # expose z0gcode's 0G tools over MCP
 ```
 
-**In the REPL**, type `/` then **Tab** to autocomplete slash commands: `/chats`, `/new`, `/rename`, `/init`, `/goal`, `/mode`, `/model`, `/effort`, `/subagents`, `/onchain`, `/skills`, `/attest`, `/share`, `/pull`, `/mint`, `/plan`, `/verify`, `/clear`, `/help`, `/exit`. `/chats` opens an arrow-key session picker (type to search, `ctrl-r` rename, `ctrl-x` delete); `/new [title]` starts a chat and `/rename <title>` renames the current one. `/mode ask|auto|plan` switches the permission mode; `/model` opens the model picker (saved to `~/.z0gcode/settings.json`); `/effort low|medium|high` (or `default`) tunes reasoning depth vs speed and cost; `/subagents on|off` toggles parallel subagents; `/onchain on|off` toggles gas-spending on-chain actions (off by default); `/skills` lists and toggles your skills; `/share [anchor]` exports the session (encrypted) to 0G Storage (and anchors it on 0G Chain), and `/pull <root>` fetches, verifies, and decrypts one back. A short intro animation and a "thinking on 0G" indicator play on a color TTY; set `Z0G_NO_ANIM=1` to disable. Each turn is separated by a divider carrying a running session token and cost counter.
+**In the REPL**, type `/` then **Tab** to autocomplete slash commands: `/chats`, `/new`, `/rename`, `/init`, `/goal`, `/mode`, `/model`, `/effort`, `/subagents`, `/onchain`, `/skills`, `/attest`, `/share`, `/pull`, `/mint`, `/plan`, `/verify`, `/clear`, `/help`, `/exit`. `/chats` opens an arrow-key session picker (type to search, `ctrl-r` rename, `ctrl-x` delete); `/new [title]` starts a chat and `/rename <title>` renames the current one. `/mode ask|auto|plan` switches the permission mode; `/model` opens the model picker (saved to `~/.z0gcode/settings.json`); `/effort low|medium|high` (or `default`) tunes reasoning depth vs speed and cost; `/subagents on|off` toggles parallel subagents; `/onchain on|off` toggles gas-spending on-chain actions (off by default); `/escalate on|off` toggles switching to a stronger model on repeated failures; `/skills` lists and toggles your skills; `/share [anchor]` exports the session (encrypted) to 0G Storage (and anchors it on 0G Chain), and `/pull <root>` fetches, verifies, and decrypts one back. A short intro animation and a "thinking on 0G" indicator play on a color TTY; set `Z0G_NO_ANIM=1` to disable. Each turn is separated by a divider carrying a running session token and cost counter.
 
 **Options:** `--auto`, `--onchain`, `--continue`, `--resume`, `--new`, `--model <id>`, `--effort low|medium|high`, `--no-subagents`, `--verify "<cmd>"`, `--auto-verify`, `--max-steps <n>`, `--cwd <dir>`, and `--json` (with `models`).
 
@@ -90,7 +90,7 @@ z0g serve --mcp                                          # expose z0gcode's 0G t
 - **Project context**: `AGENTS.md` (and `.z0g/context.md`) are auto-loaded into the agent's system prompt on every run, so it follows your conventions and uses your real build/test/run commands. `z0g init` (or `/init`) analyzes the repo and writes an accurate `AGENTS.md` for you.
 - **Checkpoints and undo**: every file edit is logged with its before/after content per turn, so `z0g undo` (or `/undo`) reverts the last turn's changes (restoring files, deleting ones it created); `z0g checkpoints` lists what you can step back through.
 - **Custom commands and hooks**: drop `.z0g/commands/<name>.md` to add a `/<name>` slash command (the file is a prompt template; `$ARGUMENTS` is substituted, optional `description:` frontmatter, Tab-completed and listed by `/commands`). Define lifecycle hooks in `.z0g/hooks.json` (`preRun` / `postRun` shell commands, e.g. run your formatter or tests after each turn); hooks run shell, so they only fire with `--auto`.
-- Reliability on a decentralized backend: app-level multi-model fallback, retry and backoff, tool-JSON repair, a loop breaker, and model escalation.
+- Reliability on a decentralized backend: app-level multi-model fallback, retry and backoff, tool-JSON repair, a loop breaker (on repeated identical calls, or the same tool result with no progress, it first escalates to a stronger model to try to get unstuck and only then hands control back, instead of spinning), and model escalation (when a tool fails repeatedly it moves to a stronger fallback for the rest of the turn; on by default after 3 failures, toggle with `/escalate on|off` or `--no-escalate`).
 - **Parallel subagents**: `spawn_subagents` fans out independent, read-only subtasks (review many files, research, audit, map a codebase) as isolated agents running in parallel, capped by `ZOG_MAX_PARALLEL`. The parent synthesizes the results and each subagent's transcript is saved. With 0G's cheap inference, fanning out to many agents costs cents: massively parallel agents at 0G prices. On by default; toggle with `/subagents on|off` or `--no-subagents`.
 - **Parallel write subagents**: with `--auto` in a git repo, `spawn_write_subagents` fans out subtasks that WRITE code, each in its own isolated **git worktree**, then merges every diff back into the working tree. Disjoint file sets merge automatically; overlapping edits are reported and skipped (never half-applied), and the merged changes are checkpointed so `z0g undo` reverts them. Verified end-to-end on 0G.
 

package/bin/z0g.mjs

@@ -60,6 +60,7 @@ function helpText() {
       ["--model <id>", "Override the model (default " + CONFIG.model + ")"],
       ["--effort <l>", "Reasoning effort: low, medium, high (default: model's own)"],
       ["--no-subagents", "Disable parallel subagents for this run"],
+      ["--no-escalate", "Do not switch to a stronger model on repeated tool failures"],
       ['--verify "<cmd>"', "Run, then verify and self-correct with this command"],
       ["--auto-verify", "Same, auto-detecting the verify command"],
       ["--max-steps <n>", "Max agent steps (default " + CONFIG.maxSteps + ")"],
@@ -93,6 +94,7 @@ const SLASH_COMMANDS = [
   ["/effort", "Set reasoning effort (low|medium|high|default)"],
   ["/subagents", "Enable or disable parallel subagents (on|off)"],
   ["/onchain", "Enable or disable gas-spending on-chain actions (on|off)"],
+  ["/escalate", "Toggle switching to a stronger model on repeated failures (on|off)"],
   ["/skills", "List skills; /skills enable|disable <name>"],
   ["/commands", "List project custom commands (.z0g/commands/*.md)"],
   ["/attest", "Show the provenance manifest"],
@@ -249,6 +251,7 @@ function parse(argv) {
     else if (a === "--no-subagents") flags.subagents = false;
     else if (a === "--onchain") flags.onchain = true;
     else if (a === "--no-onchain") flags.onchain = false;
+    else if (a === "--no-escalate") flags.escalate = false;
     else if (a === "--force") flags.force = true;
     else if (a === "--import") flags.import = true;
     else if (a === "--verify") flags.verify = argv[++i];
@@ -714,13 +717,13 @@ async function runTask(task, flags) {
     // Auto-verify: a normal run becomes self-correcting when a verify command is present.
     const verifyCmd = flags.verify || (flags.autoVerify ? detectVerifyCmd(cwd) : null);
     if (verifyCmd) {
-      await runGoal({ client: makeClient(), objective: task, cwd, sessionId, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, verifyCmd, maxIters: 3, history: opened.history });
+      await runGoal({ client: makeClient(), objective: task, cwd, sessionId, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, verifyCmd, maxIters: 3, history: opened.history });
       return;
     }
     const client = makeClient();
     const mcp = await loadMcp(cwd);
     if (mcp?.count) ui.info(`MCP: ${mcp.count} tool(s) from configured servers`);
-    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, history: opened.history, mcp });
+    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, history: opened.history, mcp });
     if (res?.messages) await saveMessages(cwd, sessionId, res.messages);
     await mcp?.close();
   } finally {
@@ -743,7 +746,7 @@ async function cmdGoal(objective, flags) {
   try {
     const verifyCmd = flags.verify || detectVerifyCmd(cwd);
     if (!flags.auto) ui.info("tip: run goal with --auto so the agent can run and verify its own work.");
-    await runGoal({ client, objective, cwd, sessionId: opened.id, sessionDir: opened.dir, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, verifyCmd, maxIters: 3, history: opened.history });
+    await runGoal({ client, objective, cwd, sessionId: opened.id, sessionDir: opened.dir, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, verifyCmd, maxIters: 3, history: opened.history });
   } finally {
     process.removeListener("SIGINT", onSig);
     pruneEmptySync(cwd, opened.id);
@@ -762,6 +765,7 @@ async function repl(flags) {
   let effort = flags.effort;
   let subagents = flags.subagents;
   let onchain = flags.onchain;
+  let escalate = flags.escalate;
   // Permission mode: auto (run all) | ask (approve each) | plan (read-only).
   let mode = flags.auto ? "auto" : "ask";
   const allowedCmds = new Set(loadSettings(cwd).allowedCommands || []);
@@ -786,6 +790,7 @@ async function repl(flags) {
   const activeModel = () => model || CONFIG.model;
   const activeEffort = () => (effort === "" ? null : (effort || CONFIG.effort));
   const activeOnchain = () => (onchain !== undefined ? onchain : CONFIG.onchain);
+  const activeEscalate = () => (escalate !== undefined ? escalate : CONFIG.escalate);
   // Approve a gated action in "ask" mode. Remembers "always" choices in settings
   // so it never asks again for that program (or for on-chain actions).
   const approve = async (kind, desc) => {
@@ -821,7 +826,7 @@ async function repl(flags) {
   // Run one agent turn: hooks, the agent, then persist history + tokens.
   const runTurn = async (task) => {
     await runHooks(cwd, "preRun", hooks, flags.auto, task);
-    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), history, mcp });
+    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), preferredEscalate: activeEscalate(), history, mcp });
     history = res.messages;
     if (res.usageTotal) { sessTokens.in += res.usageTotal.prompt || 0; sessTokens.out += res.usageTotal.completion || 0; }
     await saveMessages(cwd, sessionId, history);
@@ -926,6 +931,17 @@ async function repl(flags) {
           console.log(ui.warn("usage: /onchain on|off"));
         }
       }
+      else if (cmd === "escalate") {
+        const a = arg.toLowerCase().trim();
+        if (a === "on" || a === "off") {
+          escalate = a === "on"; saveSetting("escalate", escalate);
+          ui.info("escalate " + (escalate ? "on" : "off") + " (saved)" + (escalate ? "  ·  switches to a stronger model after " + CONFIG.escalateAfter + " tool failures" : "  ·  stays on the chosen model"));
+        } else if (!a) {
+          ui.info("escalate: " + (activeEscalate() ? "on" : "off") + "  ·  after " + CONFIG.escalateAfter + " failures  ·  usage: /escalate on|off");
+        } else {
+          console.log(ui.warn("usage: /escalate on|off"));
+        }
+      }
       else if (cmd === "mode") {
         const a = arg.toLowerCase().trim();
         if (["ask", "auto", "plan"].includes(a)) {
@@ -1002,7 +1018,7 @@ async function repl(flags) {
         else { console.log(ui.section("Custom commands", customCmds.length + " loaded")); for (const c of customCmds) console.log("  " + ui.accent("/" + c.name) + "  " + ui.muted(c.description)); }
       }
       else if (cmd === "goal") {
-        await runGoal({ client, objective: arg, cwd, sessionId, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), verifyCmd: flags.verify || detectVerifyCmd(cwd), maxIters: 3, history });
+        await runGoal({ client, objective: arg, cwd, sessionId, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), preferredEscalate: activeEscalate(), verifyCmd: flags.verify || detectVerifyCmd(cwd), maxIters: 3, history });
         history = await readMessages(cwd, sessionId) || history;
       }
       else if (customMap[cmd]) {
@@ -1029,7 +1045,7 @@ async function main() {
   if (flags.version) {
     let v = "";
     try { v = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version; } catch {}
-    console.log("z0gcode " + (v || "0.3.0"));
+    console.log("z0gcode " + (v || "0.3.2"));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z0gcode",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A terminal coding agent whose brain runs on 0G Compute: private, verifiable AI with on-chain provenance.",
   "type": "module",
   "bin": {

package/src/agent.mjs

@@ -57,7 +57,7 @@ function parseArgs(raw) {
   }
 }
 
-export async function runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, onModel, history, mcp, quiet = false, toolNames = null, isSubagent = false }) {
+export async function runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, onModel, history, mcp, quiet = false, toolNames = null, isSubagent = false }) {
   const q = !!quiet;
   // "" means an explicit unset (use the model's own default); undefined falls back.
   const effort = preferredEffort === "" ? null : (preferredEffort || CONFIG.effort);
@@ -91,7 +91,11 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
     : [{ role: "system", content: systemPrompt(cwd) }, { role: "user", content: task }];
 
   const recent = []; // circuit breaker on repeated identical tool calls
+  const results = []; // no-progress breaker: repeated identical tool RESULTS
+  let loopEscalated = false; // escalate once on a spin before giving up
   const failCounts = {}; // per-tool failure counter, drives model escalation
+  const escalateOn = preferredEscalate !== undefined ? preferredEscalate : CONFIG.escalate;
+  const escalateAfter = CONFIG.escalateAfter;
   let escalate = false;
   let activeModel = models[0];
   const usageTotal = { prompt: 0, completion: 0, total: 0 };
@@ -158,6 +162,7 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
       return { ok: true, steps: step + 1, changes: prov.count(), messages, finalText, usageTotal };
     }
 
+    let stuck = false;
     for (const tc of toolCalls) {
       const name = tc.function?.name;
       const args = parseArgs(tc.function?.arguments);
@@ -286,10 +291,33 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
         }
       } else {
         failCounts[name] = (failCounts[name] || 0) + 1;
-        if (failCounts[name] >= 2) escalate = true; // stuck on this tool: try a stronger model
+        if (escalateOn && failCounts[name] >= escalateAfter) escalate = true; // stuck on this tool: try a stronger model
       }
 
       messages.push({ role: "tool", tool_call_id: tc.id, content: String(res.content ?? (res.ok ? "OK" : "ERROR")) });
+
+      // No-progress breaker: the same tool returning the same result repeatedly
+      // means the agent is spinning (e.g. re-checking a state only a human can
+      // change). Stop cleanly and hand control back, instead of burning steps.
+      const rkey = `${name}|${res.summary || ""}|${String(res.content ?? "").slice(0, 300)}`;
+      results.push(rkey);
+      if (results.length > 8) results.shift();
+      const repeat = results.filter((k) => k === rkey).length;
+      // Spinning on the same result: it is usually a model limitation, so first
+      // escalate to a stronger model (and stay on it) to give it a chance to get
+      // unstuck; only give up and hand control back if it still makes no progress.
+      if (repeat === 2 && escalateOn && !loopEscalated && activeModel === models[0]) {
+        escalate = true; loopEscalated = true;
+        if (!q) ui.info("spinning on the same result: trying a stronger model");
+      }
+      if (repeat >= (escalateOn ? 4 : 3)) stuck = true;
+    }
+
+    if (stuck) {
+      finalText = "Stopped: I kept getting the same result without new progress. If this needs a manual step (a permission or setting change), do it and ask me again, or refine the task.";
+      if (!q) { ui.error("Stopped: no progress (same tool result 3 times)."); ui.assistant(finalText); }
+      usageTotal.total = usageTotal.prompt + usageTotal.completion;
+      return { ok: false, steps: step + 1, changes: prov.count(), messages, finalText, usageTotal };
     }
   }
 

package/src/config.mjs

@@ -65,6 +65,15 @@ export const CONFIG = {
     if (e !== undefined) return e;
     return typeof settings.onchain === "boolean" ? settings.onchain : false;
   })(),
+
+  // Escalate to a stronger fallback model when a tool fails repeatedly. ON by
+  // default (env > settings > on); escalateAfter is the failure threshold.
+  escalate: (() => {
+    const e = boolOf(process.env.ZOG_ESCALATE);
+    if (e !== undefined) return e;
+    return typeof settings.escalate === "boolean" ? settings.escalate : true;
+  })(),
+  escalateAfter: Math.max(2, Number(process.env.ZOG_ESCALATE_AFTER || settings.escalateAfter || 3)),
 };
 
 export function modelChain(preferred) {

package/src/goal.mjs

@@ -14,12 +14,12 @@ function runCmd(cmd, cwd) {
   });
 }
 
-export async function runGoal({ client, objective, cwd, sessionId, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, verifyCmd, maxIters = 3, history: historyParam = null }) {
+export async function runGoal({ client, objective, cwd, sessionId, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, verifyCmd, maxIters = 3, history: historyParam = null }) {
   let history = historyParam ?? null;
   let task = objective;
   for (let iter = 1; iter <= maxIters; iter++) {
     console.log(ui.section("Goal", "iteration " + iter + "/" + maxIters));
-    const res = await runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, history });
+    const res = await runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, history });
     history = res.messages;
     if (sessionId && Array.isArray(history)) {
       try { await saveMessages(cwd, sessionId, history); } catch {}