@pentoshi/clai 3.6.0 → 3.7.3

package/dist/agent/loop-guard.js

@@ -20,14 +20,14 @@ const READ_ONLY_TOOLS = new Set([
     "image.ocr",
     "pdf.read",
 ]);
-/**
- * Track and detect tool-call repetition patterns so the agent doesn't
- * waste steps in loops.
- */
 export class LoopGuard {
     attempts = [];
     signatureCount = new Map();
     signatureSuccess = new Map();
+    /** Failed read-only signatures that already used their one free env-change retry. */
+    failedReadRetryUsed = new Set();
+    lastSuccessfulNonMetaStep = -1;
+    constructor(_options = {}) { }
     /**
      * Produce a canonical string for a (name, args) pair so that calls
      * with identical semantics match even if arg order differs or
@@ -38,7 +38,9 @@ export class LoopGuard {
         for (const key of Object.keys(args).sort()) {
             let value = args[key];
             // Normalize command whitespace for shell.exec
-            if (name === "shell.exec" && key === "command" && typeof value === "string") {
+            if ((name === "shell.exec" || name === "shell.start") &&
+                key === "command" &&
+                typeof value === "string") {
                 value = value.trim().replace(/\s+/g, " ");
             }
             sorted[key] = value;
@@ -49,27 +51,36 @@ export class LoopGuard {
         const sig = this.canonicalize(name, args);
         this.attempts.push({ step, callName: name, canonicalSignature: sig, ok, exitCode });
         this.signatureCount.set(sig, (this.signatureCount.get(sig) ?? 0) + 1);
-        // Remember whether this exact call has EVER succeeded. A call that only
-        // ever failed should be allowed to retry (e.g. fs.write that hit ENOENT,
-        // a command that needed installing first) without being flagged as a
-        // redundant loop.
-        if (ok)
+        // Remember whether this exact call has EVER succeeded.
+        if (ok) {
             this.signatureSuccess.set(sig, true);
-        else if (!this.signatureSuccess.has(sig))
-            this.signatureSuccess.set(sig, false);
-        // X11: after a successful mutate on a path, allow re-reading that path.
-        if (ok &&
-            (name === "fs.write" ||
-                name === "fs.writeMany" ||
-                name === "fs.edit" ||
-                name === "fs.replaceLines" ||
-                name === "fs.append" ||
-                name === "fs.delete")) {
-            this.invalidateReadsForMutatedPaths(name, args);
+            if (name !== "task.update" && name !== "plan.create") {
+                this.lastSuccessfulNonMetaStep = step;
+            }
+        }
+        else {
+            if (!this.signatureSuccess.has(sig))
+                this.signatureSuccess.set(sig, false);
+        }
+        // After successful *mutates* (not reads), allow re-list/re-read of those paths.
+        // Never invalidate on fs.read/list themselves — that wiped the dedup counter
+        // on every successful read and disabled loop detection.
+        if (ok && this.isPathMutatingTool(name)) {
+            this.invalidateReadsAfterSuccess(name, args);
         }
     }
-    /** Drop successful fs.read signatures that touch the mutated path(s). */
-    invalidateReadsForMutatedPaths(name, args) {
+    isPathMutatingTool(name) {
+        return (name === "fs.write" ||
+            name === "fs.writeMany" ||
+            name === "fs.edit" ||
+            name === "fs.replaceLines" ||
+            name === "fs.append" ||
+            name === "fs.delete" ||
+            name === "shell.exec" ||
+            name === "shell.start");
+    }
+    /** Drop list/read signatures that touch paths a successful tool may have created. */
+    invalidateReadsAfterSuccess(name, args) {
         const paths = [];
         if (typeof args.path === "string")
             paths.push(args.path);
@@ -80,14 +91,29 @@ export class LoopGuard {
                 }
             }
         }
-        if (paths.length === 0)
+        if ((name === "shell.exec" || name === "shell.start") &&
+            typeof args.command === "string") {
+            const cmd = args.command;
+            // mkdir -p path, create-vite name, cd path
+            for (const m of cmd.matchAll(/(?:mkdir\s+(?:-p\s+)?|cd\s+|create-[\w@./-]+\s+|vite@\S+\s+)(['"]?)([^\s;'"]+)\1/gi)) {
+                if (m[2] && m[2] !== ".")
+                    paths.push(m[2]);
+            }
+            if (typeof args.cwd === "string")
+                paths.push(args.cwd);
+        }
+        if (paths.length === 0) {
+            // Any successful shell still clears failed fs.list of unknown paths once
+            // via the generic read-only retry path in shouldBlock.
             return;
-        for (const [sig] of this.signatureCount) {
-            if (!sig.startsWith("fs.read::"))
+        }
+        for (const sig of [...this.signatureCount.keys()]) {
+            if (!sig.startsWith("fs.read::") && !sig.startsWith("fs.list::"))
                 continue;
-            if (paths.some((p) => sig.includes(p))) {
+            if (paths.some((p) => p.length > 1 && sig.includes(p))) {
                 this.signatureCount.delete(sig);
                 this.signatureSuccess.delete(sig);
+                this.failedReadRetryUsed.delete(sig);
             }
         }
     }
@@ -98,16 +124,12 @@ export class LoopGuard {
      * `{ block: false, reason: "..." }` for a warning (first repeat), or
      * `{ block: true, reason: "..." }` to force summary (second+ repeat).
      *
-     * A call whose every prior attempt FAILED is never blocked — the model is
-     * expected to fix the cause (install a tool, create a dir) and retry. Only
-     * calls that already SUCCEEDED are deduped, since re-running them wastes a
-     * step and risks an infinite summarize loop.
-     *
-     * Read-only tools (web.fetch, fs.read, etc.) get a higher threshold (3)
-     * because they may legitimately need re-calling after context compaction
-     * removes their results.
+     * Failed read-only tools may retry once after any successful intervening
+     * non-meta work (e.g. list missing dir → scaffold → list again). Failed
+     * mutates still need structured retry context or a changed path.
+     * Successful identical mutates are still deduped.
      */
-    shouldBlock(name, args) {
+    shouldBlock(name, args, retryContext) {
         if (name === "task.update" || name === "plan.create") {
             return { block: false };
         }
@@ -115,9 +137,41 @@ export class LoopGuard {
         const count = this.signatureCount.get(sig) ?? 0;
         if (count === 0)
             return { block: false };
-        // Prior attempts all failed → allow the retry, no warning.
-        if (this.signatureSuccess.get(sig) === false)
-            return { block: false };
+        // Previously-failed signature: allow structured retry, or one free retry
+        // for read-only tools after environment-changing successful work.
+        if (this.signatureSuccess.get(sig) === false) {
+            const structuredReason = retryContext?.retryReason;
+            const authorized = retryContext?.dependenciesChanged === true ||
+                retryContext?.environmentChanged === true ||
+                Boolean(structuredReason?.code.trim() && structuredReason.detail.trim());
+            if (authorized) {
+                return {
+                    block: false,
+                    reason: `${name} retry authorized by changed context or structured rationale.`,
+                };
+            }
+            if (READ_ONLY_TOOLS.has(name) && !this.failedReadRetryUsed.has(sig)) {
+                // Permit one retry after any successful non-meta tool since the fail.
+                const lastFailStep = [...this.attempts]
+                    .reverse()
+                    .find((a) => a.canonicalSignature === sig && !a.ok)?.step;
+                if (lastFailStep !== undefined &&
+                    this.lastSuccessfulNonMetaStep > lastFailStep) {
+                    this.failedReadRetryUsed.add(sig);
+                    // Reset counters so a successful retry is clean
+                    this.signatureCount.delete(sig);
+                    this.signatureSuccess.delete(sig);
+                    return {
+                        block: false,
+                        reason: `${name} retry allowed after successful work changed the environment.`,
+                    };
+                }
+            }
+            return {
+                block: true,
+                reason: `${name} previously failed with identical arguments. Change dependencies/environment or provide a structured retry reason.`,
+            };
+        }
         // Mutating file tools deserve tool-appropriate wording. Telling a model
         // that just wrote a file to "use the results you already have" is
         // nonsensical and has caused models to assume the whole task is done.

package/dist/agent/loop-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"loop-guard.js","sourceRoot":"","sources":["../../src/agent/loop-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop-guard.js","sourceRoot":"","sources":["../../src/agent/loop-guard.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,SAAS;IACT,SAAS;IACT,WAAW;IACX,SAAS;IACT,aAAa;IACb,YAAY;IACZ,eAAe;IACf,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAyBH,MAAM,OAAO,SAAS;IACZ,QAAQ,GAAkB,EAAE,CAAC;IAC7B,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,gBAAgB,GAAG,IAAI,GAAG,EAAmB,CAAC;IACtD,qFAAqF;IAC7E,mBAAmB,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,yBAAyB,GAAG,CAAC,CAAC,CAAC;IAEvC,YAAY,WAA6B,EAAE,IAAG,CAAC;IAE/C;;;;OAIG;IACH,YAAY,CAAC,IAAY,EAAE,IAA6B;QACtD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YACtB,8CAA8C;YAC9C,IACE,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,aAAa,CAAC;gBACjD,GAAG,KAAK,SAAS;gBACjB,OAAO,KAAK,KAAK,QAAQ,EACzB,CAAC;gBACD,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;QACD,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED,aAAa,CACX,IAAY,EACZ,IAAY,EACZ,IAA6B,EAC7B,EAAW,EACX,QAA6B;QAE7B,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,uDAAuD;QACvD,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACrC,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;gBACrD,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC;YACxC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7E,CAAC;QAED,gFAAgF;QAChF,6EAA6E;QAC7E,wDAAwD;QACxD,IAAI,EAAE,IAAI,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,2BAA2B,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,IAAY;QACrC,OAAO,CACL,IAAI,KAAK,UAAU;YACnB,IAAI,KAAK,cAAc;YACvB,IAAI,KAAK,SAAS;YAClB,IAAI,KAAK,iBAAiB;YAC1B,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,YAAY;YACrB,IAAI,KAAK,aAAa,CACvB,CAAC;IACJ,CAAC;IAED,qFAAqF;IAC7E,2BAA2B,CACjC,IAAY,EACZ,IAA6B;QAE7B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC3B,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAAuB,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACpF,KAAK,CAAC,IAAI,CAAE,CAAsB,CAAC,IAAI,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;QACD,IACE,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,aAAa,CAAC;YACjD,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAChC,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;YACzB,2CAA2C;YAC3C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,CAC1B,oFAAoF,CACrF,EAAE,CAAC;gBACF,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7C,CAAC;YACD,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,yEAAyE;YACzE,uDAAuD;YACvD,OAAO;QACT,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;gBAAE,SAAS;YAC3E,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAClC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,WAAW,CACT,IAAY,EACZ,IAA6B,EAC7B,YAA2B;QAE3B,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YACrD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEhD,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAEzC,yEAAyE;QACzE,kEAAkE;QAClE,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;YAC7C,MAAM,gBAAgB,GAAG,YAAY,EAAE,WAAW,CAAC;YACnD,MAAM,UAAU,GACd,YAAY,EAAE,mBAAmB,KAAK,IAAI;gBAC1C,YAAY,EAAE,kBAAkB,KAAK,IAAI;gBACzC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3E,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,GAAG,IAAI,+DAA+D;iBAC/E,CAAC;YACJ,CAAC;YACD,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpE,sEAAsE;gBACtE,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;qBACpC,OAAO,EAAE;qBACT,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kBAAkB,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC;gBAC5D,IACE,YAAY,KAAK,SAAS;oBAC1B,IAAI,CAAC,yBAAyB,GAAG,YAAY,EAC7C,CAAC;oBACD,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBAClC,gDAAgD;oBAChD,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAChC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAClC,OAAO;wBACL,KAAK,EAAE,KAAK;wBACZ,MAAM,EAAE,GAAG,IAAI,+DAA+D;qBAC/E,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,MAAM,EAAE,GAAG,IAAI,oHAAoH;aACpI,CAAC;QACJ,CAAC;QAED,wEAAwE;QACxE,kEAAkE;QAClE,sEAAsE;QACtE,MAAM,OAAO,GACX,IAAI,KAAK,UAAU;YACnB,IAAI,KAAK,cAAc;YACvB,IAAI,KAAK,SAAS;YAClB,IAAI,KAAK,iBAAiB;YAC1B,IAAI,KAAK,WAAW,CAAC;QAEvB,oEAAoE;QACpE,0DAA0D;QAC1D,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAEpD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,OAAO;oBACb,CAAC,CAAC,GAAG,IAAI,8HAA8H;oBACvI,CAAC,CAAC,IAAI,KAAK,SAAS;wBAClB,CAAC,CAAC,GAAG,IAAI,2KAA2K;wBACpL,CAAC,CAAC,GAAG,IAAI,gHAAgH;aAC9H,CAAC;QACJ,CAAC;QAED,qDAAqD;QACrD,OAAO;YACL,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,OAAO;gBACb,CAAC,CAAC,GAAG,IAAI,uBAAuB,KAAK,gJAAgJ;gBACrL,CAAC,CAAC,IAAI,KAAK,SAAS;oBAClB,CAAC,CAAC,GAAG,IAAI,uBAAuB,KAAK,kJAAkJ;oBACvL,CAAC,CAAC,GAAG,IAAI,uBAAuB,KAAK,0HAA0H;SACpK,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,IAA6B;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,SAAS,GAAG,CAAC;QAC/B,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,SAAS;YAAE,OAAO,KAAK,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,uBAAuB;QACrB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,EAAE;gBAAE,KAAK,EAAE,CAAC;;gBAC9B,MAAM;QACb,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,oBAAoB;QAClB,MAAM,mBAAmB,GAAG,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAC3D,IAAI,mBAAmB,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAEzC,6DAA6D;QAC7D,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,mBAAmB,CAAC,CAAC;QAC9D,MAAM,WAAW,GAAG,WAAW;aAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;aACtE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB;aAC5B,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,QAAQ,GAAG,mBAAmB,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAEnE,OAAO,mCAAmC,QAAQ,OAAO,mBAAmB;;;EAG9E,WAAW;;;;;;;;;;;;gHAYmG,CAAC;IAC/G,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CACxC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;CACF"}

package/dist/agent/must-continue.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Completion-time recovery decisions: when a tool-free (or incomplete)
+ * final answer must be rejected and the agent forced to act.
+ */
+export interface RecoveryBudgets {
+    actionIntent: number;
+    errorFix: number;
+    forcePlan: number;
+    featureImpl: number;
+    runtimeVerify: number;
+    failedProbe: number;
+    prematureComplete: number;
+    shallowPentest: number;
+    freshnessUsed: boolean;
+}
+export declare function createRecoveryBudgets(): RecoveryBudgets;
+export type RecoveryKind = "error_fix" | "narration" | "force_plan" | "feature_impl" | "runtime_verify" | "failed_probe" | "premature_complete" | "freshness" | "shallow_pentest";
+export interface RecoveryAction {
+    kind: RecoveryKind;
+    /** User/model-facing instruction to append. */
+    message: string;
+    /** Short terminal notice. */
+    notice: string;
+    budgetKey: keyof RecoveryBudgets;
+}
+export declare function budgetRemaining(budgets: RecoveryBudgets, key: keyof RecoveryBudgets): boolean;
+export declare function consumeBudget(budgets: RecoveryBudgets, key: keyof RecoveryBudgets): void;
+export declare function recoveryForErrorDiagnosis(nativeTools: boolean): RecoveryAction;
+export declare function recoveryForNarration(nativeTools: boolean, mode: "plan_open" | "pentest" | "web" | "build_plan_prose" | "build" | "generic"): RecoveryAction;
+/** Plan mode only — agent mode must not force plan.create. */
+export declare function recoveryForMissingPlan(nativeTools: boolean): RecoveryAction;
+export declare function recoveryForMissingFeature(projectRoot?: string): RecoveryAction;
+export declare function recoveryForRuntimeVerify(projectRoot?: string): RecoveryAction;
+export declare function recoveryForFailedProbe(): RecoveryAction;
+export declare function recoveryForPrematureComplete(input: {
+    unfinished: Array<{
+        id: string;
+        title: string;
+        state: string;
+    }>;
+    next: {
+        id: string;
+        title: string;
+        state: string;
+    };
+    pentest: boolean;
+    errorFix: boolean;
+}): RecoveryAction;
+export declare function recoveryForFreshness(extra: string): RecoveryAction;
+/** True when a final pentest write-up looks like skim recon without real coverage. */
+export declare function looksLikeShallowPentestReport(text: string, opts: {
+    productiveSteps: number;
+    sawActiveTest: boolean;
+}): boolean;
+export declare function recoveryForShallowPentest(): RecoveryAction;
+export declare function freestyleClaimsAppReady(text: string): boolean;

package/dist/agent/must-continue.js

@@ -0,0 +1,240 @@
+/**
+ * Completion-time recovery decisions: when a tool-free (or incomplete)
+ * final answer must be rejected and the agent forced to act.
+ */
+export function createRecoveryBudgets() {
+    return {
+        actionIntent: 0,
+        errorFix: 0,
+        forcePlan: 0,
+        featureImpl: 0,
+        runtimeVerify: 0,
+        failedProbe: 0,
+        prematureComplete: 0,
+        shallowPentest: 0,
+        freshnessUsed: false,
+    };
+}
+const LIMITS = {
+    actionIntent: 3,
+    errorFix: 3,
+    forcePlan: 2,
+    featureImpl: 2,
+    runtimeVerify: 2,
+    failedProbe: 3,
+    prematureComplete: 6,
+    shallowPentest: 2,
+    freshnessUsed: 1,
+};
+export function budgetRemaining(budgets, key) {
+    if (key === "freshnessUsed")
+        return !budgets.freshnessUsed;
+    return budgets[key] < LIMITS[key];
+}
+export function consumeBudget(budgets, key) {
+    if (key === "freshnessUsed") {
+        budgets.freshnessUsed = true;
+        return;
+    }
+    budgets[key] = budgets[key] + 1;
+}
+export function recoveryForErrorDiagnosis(nativeTools) {
+    return {
+        kind: "error_fix",
+        budgetKey: "errorFix",
+        notice: "error diagnosed but not fixed — forcing tool call",
+        message: nativeTools
+            ? "You diagnosed an error and described the fix but called NO tool. " +
+                "Apply the fix now (fs.edit / fs.write / shell.exec), then re-verify. " +
+                "Do not stop after identifying the error."
+            : "You diagnosed an error and described the fix but emitted NO tool call. " +
+                "Apply the fix now, e.g.:\n" +
+                '```tool\n{"name":"fs.edit","args":{"path":"<file>","oldText":"...","newText":"..."}}\n```\n' +
+                "Then re-run the failing check.",
+    };
+}
+export function recoveryForNarration(nativeTools, mode) {
+    const base = {
+        kind: "narration",
+        budgetKey: "actionIntent",
+        notice: "described an action but emitted no tool call",
+    };
+    if (mode === "plan_open") {
+        return {
+            ...base,
+            message: nativeTools
+                ? "You wrote a message but called NO tool. Call the next tool now (task.update / fs.write / shell.exec)."
+                : "You wrote a message but emitted NO ```tool block. Emit the next tool call now.",
+        };
+    }
+    if (mode === "pentest") {
+        return {
+            ...base,
+            notice: "described a security action but emitted no tool call",
+            message: nativeTools
+                ? "You described security work but called NO tool. Call a real tool now (net.scan / http.fetch / dns.lookup / shell.exec)."
+                : "You described security work but emitted NO ```tool block. Emit a real tool call now (e.g. sysinfo, net.scan, http.fetch).",
+        };
+    }
+    if (mode === "web") {
+        return {
+            ...base,
+            notice: "described a web action but emitted no tool call",
+            message: nativeTools
+                ? "You claimed a search/fetch but called NO tool. Call web.search or web.fetch now, then answer from results."
+                : "You claimed a search/fetch but emitted NO ```tool block. Emit web.search or web.fetch now.",
+        };
+    }
+    if (mode === "build_plan_prose") {
+        return {
+            ...base,
+            notice: "plan was written as text, not created",
+            message: nativeTools
+                ? 'You wrote the plan as prose but did NOT call plan.create. Call plan.create now with goal, detail, tasks, and kind="coding" or "pentest".'
+                : "You wrote the plan as prose but did NOT call plan.create. Emit one plan.create tool block now.",
+        };
+    }
+    if (mode === "build") {
+        return {
+            ...base,
+            message: nativeTools
+                ? 'You described work but called NO tool. Call a tool now (e.g. fs.list path="."), then plan.create when ready.'
+                : "You described work but emitted NO ```tool block. Explore first, then plan.create when ready.",
+        };
+    }
+    return {
+        ...base,
+        message: nativeTools
+            ? "You described an action but called NO tool. Call the appropriate tool now."
+            : "You described an action but emitted NO ```tool block. Emit a real tool call now.",
+    };
+}
+/** Plan mode only — agent mode must not force plan.create. */
+export function recoveryForMissingPlan(nativeTools) {
+    return {
+        kind: "force_plan",
+        budgetKey: "forcePlan",
+        notice: "plan mode missing plan.create",
+        message: nativeTools
+            ? "You are in plan mode and tried to finish without a durable plan. Gather any remaining context you need, then call plan.create " +
+                "(goal, rich detail with context/approach/risks/verify, all relevant tasks — no artificial cap, kind=coding|pentest|general as appropriate). Do not implement yet."
+            : "You are in plan mode and tried to finish without a durable plan. Gather context if needed, then emit plan.create with a comprehensive plan (any relevant task count). Do not implement yet.",
+    };
+}
+export function recoveryForMissingFeature(projectRoot) {
+    const rootHint = projectRoot
+        ? ` Write under "${projectRoot}" with absolute paths.`
+        : "";
+    return {
+        kind: "feature_impl",
+        budgetKey: "featureImpl",
+        notice: "feature not implemented — scaffold alone is incomplete",
+        message: "INCOMPLETE: the user asked for a working product feature, not a blank framework starter. " +
+            "Scaffold alone is a failure. Implement the requested feature now (replace starter boilerplate) " +
+            "with fs.write / fs.writeMany. Do not shell.start until that feature exists." +
+            rootHint,
+    };
+}
+export function recoveryForRuntimeVerify(projectRoot) {
+    const rootHint = projectRoot ? ` Use cwd "${projectRoot}".` : "";
+    return {
+        kind: "runtime_verify",
+        budgetKey: "runtimeVerify",
+        notice: "local app missing runtime proof",
+        message: "This is a local app build: do not stop after writing files or only telling the user how to run it. " +
+            "Prove the app is running with ANY of: shell.start + shell.tail ready, port LISTEN (lsof/ss), " +
+            "or localhost GET (http.fetch or curl). If the server is already listening, do NOT restart it " +
+            "just to re-mint evidence — confirm once, leave it running, task.update done, report URL + port + job id." +
+            rootHint,
+    };
+}
+export function recoveryForFailedProbe() {
+    return {
+        kind: "failed_probe",
+        budgetKey: "failedProbe",
+        notice: "localhost probe failed — fix and re-verify",
+        message: "The local HTTP probe failed (4xx/5xx or connection refused). Do not stop. " +
+            "Diagnose from the error, apply a real fix with fs.edit/fs.write, re-probe, and only then mark verify done. " +
+            "Identifying the error without a tool call is incomplete.",
+    };
+}
+export function recoveryForPrematureComplete(input) {
+    const list = input.unfinished
+        .map((t) => `[${t.id}] ${t.title}`)
+        .join("; ");
+    let instruction = `Resume task ${input.next.id} ("${input.next.title}"): `;
+    if (input.errorFix) {
+        instruction =
+            `Fix the failure with a tool first (fs.edit/fs.write), then continue task ${input.next.id} ("${input.next.title}"): `;
+    }
+    if (input.pentest) {
+        instruction +=
+            `task.update in_progress, then recon/test with real tools (dns/http/net.scan — not a local dev server), verify, mark done. `;
+    }
+    else if (input.next.state === "pending") {
+        instruction +=
+            `task.update in_progress, do the work, verify, mark done. `;
+    }
+    else {
+        instruction += `finish the work, verify, mark done. `;
+    }
+    instruction += "Continue until every task is finished.";
+    return {
+        kind: "premature_complete",
+        budgetKey: "prematureComplete",
+        notice: `${input.unfinished.length} plan task(s) still unfinished`,
+        message: `You have not finished the approved plan: ${input.unfinished.length} task(s) remain (${list}). ` +
+            `Do not claim completion without tool evidence. ${instruction}`,
+    };
+}
+export function recoveryForFreshness(extra) {
+    return {
+        kind: "freshness",
+        budgetKey: "freshnessUsed",
+        notice: "current-info question — search before answering",
+        message: extra,
+    };
+}
+/** True when a final pentest write-up looks like skim recon without real coverage. */
+export function looksLikeShallowPentestReport(text, opts) {
+    if (opts.sawActiveTest)
+        return false;
+    if (opts.productiveSteps < 3)
+        return false;
+    const t = text.trim();
+    if (t.length < 80)
+        return false;
+    const lower = t.toLowerCase();
+    if (!/\b(finding|vulnerab|assessment|report|recon|open port|security posture|risk rating)\b/.test(lower)) {
+        return false;
+    }
+    const deep = /\b(idor|broken access|injection|xss|csrf|ssrf|rce|sqli|auth.?bypass|privilege|jwt|poc|exploit|confirmed|reproduc|ffuf|gobuster|ferox|directory enum|content discovery|crt\.sh|certificate transparency)\b/i.test(t);
+    if (deep)
+        return false;
+    const shallow = /\b(open ports?|port\s+\d+|server header|missing (?:security )?header|http\/1|tls|banner|robots\.txt|top[- ]?ports?|mature (?:security )?posture|overall risk rating:\s*low)\b/i.test(t);
+    const claimsComplete = /\b(no critical|no high|mature|strong security posture|not vulnerable)\b/i.test(t) &&
+        !/\b(untested|residual|not (?:tested|enumerated|scanned)|limited scope)\b/i.test(t);
+    return shallow || claimsComplete;
+}
+export function recoveryForShallowPentest() {
+    return {
+        kind: "shallow_pentest",
+        budgetKey: "shallowPentest",
+        notice: "pentest coverage looks thin — expand surface mapping",
+        message: "Coverage looks thin (ports/headers/robots or early closure without residual risk). " +
+            "Before finalizing: write a short threat model (top hypotheses for this stack), " +
+            "expand attack surface — escalate ports if only top-N was used, " +
+            "subdomain strategy beyond a few digs, content/API discovery (ffuf/gobuster + wordlist.find), " +
+            "JS harvest, then actively test high-value vectors. " +
+            "Background long scans while doing other recon. End with residual/untested honesty — " +
+            "do not claim mature posture if major classes were never attempted.",
+    };
+}
+export function freestyleClaimsAppReady(text) {
+    return (/\b(?:npm|pnpm|yarn|bun)\s+run\s+dev\b/i.test(text) ||
+        /\b(?:cargo\s+run|flask\s+run|uvicorn|rails\s+s|python\s+-m\s+http\.server)\b/i.test(text) ||
+        /\bopen\s+http:\/\/localhost\b/i.test(text) ||
+        /\bhow to run\b/i.test(text) ||
+        /\b(?:created|built|ready|complete)\b/i.test(text));
+}
+//# sourceMappingURL=must-continue.js.map

package/dist/agent/must-continue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"must-continue.js","sourceRoot":"","sources":["../../src/agent/must-continue.ts"],"names":[],"mappings":"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"}

package/dist/agent/outcomes.d.ts

@@ -0,0 +1,101 @@
+export type OutcomeKind = "answer" | "build" | "bugfix" | "operation" | "pentest";
+export type OutcomeStatus = "active" | "succeeded" | "partial" | "blocked" | "failed" | "aborted" | "paused_budget";
+export type CriterionStatus = "unproven" | "supported" | "proven" | "refuted" | "waived";
+export type EvidenceKind = "observation" | "automated-check" | "process-start" | "readiness" | "probe" | "reproduction" | "impact" | "artifact" | "scanner-lead";
+export interface OutcomeCriterion {
+    id: string;
+    statement: string;
+    required: boolean;
+    status: CriterionStatus;
+    evidenceIds: string[];
+    revision: number;
+    domain?: "general" | "feature" | "bugfix" | "server" | "pentest-finding" | undefined;
+}
+export interface OutcomeContract {
+    schemaVersion: 1;
+    id: string;
+    sessionId: string;
+    userIntent: string;
+    kind: OutcomeKind;
+    criteria: OutcomeCriterion[];
+    assumptions: string[];
+    constraints: string[];
+    status: OutcomeStatus;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EvidenceRecord {
+    schemaVersion: 1;
+    id: string;
+    outcomeId: string;
+    criterionIds: string[];
+    taskId?: string | undefined;
+    source: {
+        tool: string;
+        callId: string;
+        artifact?: string | undefined;
+    };
+    kind: EvidenceKind;
+    observedAt: string;
+    freshness: "current" | "stale";
+    strength: "supporting" | "decisive";
+    observation: string;
+    result: "pass" | "fail" | "inconclusive";
+    environment?: Record<string, string> | undefined;
+    outcomeRevision: number;
+}
+export interface OutcomeEnvelope {
+    schemaVersion: 1;
+    outcome: OutcomeContract;
+    evidence: EvidenceRecord[];
+    failedHypotheses: Array<{
+        signature: string;
+        premise: string;
+        observedAt: string;
+    }>;
+}
+export declare function createOutcome(input: {
+    sessionId: string;
+    userIntent: string;
+    kind: OutcomeKind;
+    criteria: Array<Pick<OutcomeCriterion, "statement" | "required" | "domain"> & {
+        id?: string;
+    }>;
+}): OutcomeContract;
+export declare function reviseOutcome(outcome: OutcomeContract, criteria: OutcomeContract["criteria"]): OutcomeContract;
+export declare function linkEvidence(outcome: OutcomeContract, evidence: EvidenceRecord): void;
+export declare function validateCriterionEvidence(criterion: OutcomeCriterion, records: readonly EvidenceRecord[]): {
+    ok: boolean;
+    reason?: string;
+};
+export declare function deriveOutcomeStatus(outcome: OutcomeContract, records: readonly EvidenceRecord[]): OutcomeStatus;
+export declare function saveOutcomeState(envelope: OutcomeEnvelope): Promise<void>;
+export declare function loadOutcomeState(sessionId: string): Promise<OutcomeEnvelope | undefined>;
+export declare function createEvidence(input: Omit<EvidenceRecord, "schemaVersion" | "id" | "observedAt">): EvidenceRecord;
+export declare function inferOutcomeKind(input: {
+    userIntent: string;
+    buildLike?: boolean;
+    pentestLike?: boolean;
+}): OutcomeKind;
+export declare function defaultOutcomeCriteria(kind: OutcomeKind, userIntent: string): Array<Pick<OutcomeCriterion, "id" | "statement" | "required" | "domain">>;
+export declare function openOutcomeState(input: {
+    sessionId: string;
+    userIntent: string;
+    kind: OutcomeKind;
+    continueExisting?: boolean;
+}): Promise<OutcomeEnvelope>;
+export declare function recordFailedHypothesis(envelope: OutcomeEnvelope, input: {
+    signature: string;
+    premise: string;
+}): void;
+export declare function recordToolEvidence(envelope: OutcomeEnvelope, input: {
+    tool: string;
+    callId: string;
+    ok: boolean;
+    output: string;
+    artifact?: string | undefined;
+    taskId?: string | undefined;
+    args?: Record<string, unknown> | undefined;
+}): EvidenceRecord[];
+export declare function recordAnswerEvidence(envelope: OutcomeEnvelope, answer: string): EvidenceRecord | undefined;