@wrongstack/tools 0.289.0 → 0.291.0

package/dist/auto-proceed-loop-guard.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Auto-proceed loop guard.
+ *
+ * ## Problem
+ *
+ * The REPL and TUI both implement an "auto" autonomy mode that, after every
+ * completed agent turn, feeds the next suggestion (or top auto="true" item)
+ * back as a fresh prompt. When the agent emits the same `<nextsteps>` block
+ * on every reply — which happens whenever the model's output is stable but
+ * autonomy treats the next step as "still actionable" — the loop self-feeds
+ * the same instruction 2–3 times in a row before the longer
+ * `autoProceedMaxIterations` cap (default 50) trips.
+ *
+ * The user reports the visible symptom: the same response, including the same
+ * `<nextsteps>` block, repeats. Manual input from the user is the only thing
+ * that breaks out. They suspect the next-steps mechanism is the source.
+ *
+ * The 50-iteration cap is intentionally loose — it is a runaway safety net,
+ * not a UX signal. By the time it trips, the user has already watched the
+ * same response 50 times.
+ *
+ * ## Approach
+ *
+ * A small, pure, browser-safe stateful helper that records the last few
+ * prompts fed through the auto-proceed / auto-submit path. It normalizes
+ * prompts (whitespace, casing) so trivial rewordings are not collapsed, but
+ * identical re-feeds are. When the same normalized prompt is fed
+ * `repeatThreshold` (default 2) times in a row, the guard returns
+ * `{ shouldHalt: true }`.
+ *
+ * Callers are expected to:
+ *   1. Call `record(prompt)` immediately before each auto-feed.
+ *   2. If `shouldHalt` is true, clear the suggestion + auto-suggestion store,
+ *      cancel any pending countdown, and surface a "we detected a loop"
+ *      message asking the user what's happening. Do NOT feed the prompt.
+ *   3. Call `reset()` whenever the user types anything manually (REPL manual
+ *      input or any user-driven submit) so the next auto-feed starts clean.
+ *
+ * The default `repeatThreshold` is 2 — i.e. the second consecutive identical
+ * feed (the first re-feed of an already-seen prompt) halts the loop. That
+ * matches the user's report ("receiving the same prompt 2-3 times in a row
+ * causes the system to enter a loop"). Setting it to 2 catches the loop on
+ * the first identical re-feed rather than after the 50-iteration runaway cap trips.
+ *
+ * The window size is intentionally small (default 3). The loop we care about
+ * is the immediate repetition — a longer history would misfire on legitimate
+ * "do X, then do Y, then do X" sequences the model occasionally returns to.
+ *
+ * This module is BROWSER-SAFE — no Node-only imports — so it can be imported
+ * from Vite-bundled WebUI as well as Node-based CLI/TUI.
+ */
+/**
+ * Normalize a prompt for repetition comparison. Whitespace is collapsed and
+ * trimmed; case is folded to lowercase. Nothing semantic is removed, so two
+ * prompts that differ in any meaningful way (extra word, different code,
+ * different file path) compare as distinct. Two prompts that differ only by
+ * leading/trailing whitespace and casing are treated as identical.
+ */
+export declare function normalizeForRepetition(prompt: string): string;
+export interface LoopGuardOptions {
+    /**
+     * How many consecutive identical prompts (after normalization) trigger a
+     * halt. Default 2 — i.e. the second consecutive identical feed (the first
+     * re-feed of an already-seen prompt) halts the loop. Clamped to >= 2.
+     */
+    repeatThreshold?: number;
+    /**
+     * How many of the most recent feeds to retain for comparison. The window
+     * is searched from newest to oldest; the guard cares about the run of
+     * identical entries ending at the most recent one, not about identical
+     * entries anywhere in history. Default 3.
+     */
+    windowSize?: number;
+}
+export interface RepetitionSignal {
+    /** The normalized prompt that just got recorded. */
+    normalized: string;
+    /**
+     * Number of consecutive identical feeds ending at the most recent feed,
+     * including this one. Always >= 1.
+     */
+    runLength: number;
+    /**
+     * True when the run length has crossed `repeatThreshold`. Callers must
+     * stop feeding and surface a user prompt instead.
+     */
+    shouldHalt: boolean;
+}
+export interface AutoProceedLoopGuard {
+    /**
+     * Record a prompt that is about to be auto-fed. Returns the repetition
+     * signal for that prompt. When `shouldHalt` is true the caller MUST NOT
+     * feed the prompt — it has been recorded for post-mortem inspection, but
+     * the loop must be broken instead.
+     */
+    record(prompt: string): RepetitionSignal;
+    /**
+     * Drop the history. Call this on any manual user input so a fresh run
+     * starts with no memory of the prior cycle.
+     */
+    reset(): void;
+    /**
+     * Read-only view of the most recent normalized prompts (newest last).
+     * Useful for diagnostics and for the message shown to the user when the
+     * guard halts the loop.
+     */
+    history(): readonly string[];
+    /**
+     * How many entries the guard is currently retaining.
+     */
+    size(): number;
+}
+/**
+ * Build a fresh loop guard. Defaults: `repeatThreshold = 2`, `windowSize = 3`.
+ *
+ * @example
+ *   const guard = createAutoProceedLoopGuard();
+ *   for (const prompt of candidates) {
+ *     const signal = guard.record(prompt);
+ *     if (signal.shouldHalt) {
+ *       haltAutoProceedAndAskUser(signal);
+ *       break;
+ *     }
+ *     feedPrompt(prompt);
+ *   }
+ */
+export declare function createAutoProceedLoopGuard(options?: LoopGuardOptions): AutoProceedLoopGuard;
+//# sourceMappingURL=auto-proceed-loop-guard.d.ts.map

package/dist/auto-proceed-loop-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-proceed-loop-guard.d.ts","sourceRoot":"","sources":["../src/auto-proceed-loop-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACzC;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IACd;;;;OAIG;IACH,OAAO,IAAI,SAAS,MAAM,EAAE,CAAC;IAC7B;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,gBAAqB,GAAG,oBAAoB,CAmD/F"}

package/dist/auto-proceed-loop-guard.js

@@ -0,0 +1,46 @@
+// src/auto-proceed-loop-guard.ts
+function normalizeForRepetition(prompt) {
+  return prompt.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function createAutoProceedLoopGuard(options = {}) {
+  const safeIntegerOption = (value, fallback) => {
+    if (value === void 0) return fallback;
+    if (!Number.isFinite(value)) return fallback;
+    return Math.floor(value);
+  };
+  const repeatThreshold = Math.max(2, safeIntegerOption(options.repeatThreshold, 2));
+  const windowSize = Math.max(repeatThreshold, safeIntegerOption(options.windowSize, 3));
+  let buffer = [];
+  function record(prompt) {
+    const normalized = normalizeForRepetition(prompt);
+    buffer.push(normalized);
+    if (buffer.length > windowSize) {
+      buffer = buffer.slice(buffer.length - windowSize);
+    }
+    let runLength = 0;
+    for (let i = buffer.length - 1; i >= 0; i--) {
+      if (buffer[i] === normalized) runLength++;
+      else break;
+    }
+    return {
+      normalized,
+      runLength,
+      shouldHalt: runLength >= repeatThreshold
+    };
+  }
+  function reset() {
+    buffer = [];
+  }
+  function history() {
+    return buffer.slice();
+  }
+  function size() {
+    return buffer.length;
+  }
+  return { record, reset, history, size };
+}
+export {
+  createAutoProceedLoopGuard,
+  normalizeForRepetition
+};
+//# sourceMappingURL=auto-proceed-loop-guard.js.map

package/dist/auto-proceed-loop-guard.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/auto-proceed-loop-guard.ts"],
+  "sourcesContent": ["/**\n * Auto-proceed loop guard.\n *\n * ## Problem\n *\n * The REPL and TUI both implement an \"auto\" autonomy mode that, after every\n * completed agent turn, feeds the next suggestion (or top auto=\"true\" item)\n * back as a fresh prompt. When the agent emits the same `<nextsteps>` block\n * on every reply \u2014 which happens whenever the model's output is stable but\n * autonomy treats the next step as \"still actionable\" \u2014 the loop self-feeds\n * the same instruction 2\u20133 times in a row before the longer\n * `autoProceedMaxIterations` cap (default 50) trips.\n *\n * The user reports the visible symptom: the same response, including the same\n * `<nextsteps>` block, repeats. Manual input from the user is the only thing\n * that breaks out. They suspect the next-steps mechanism is the source.\n *\n * The 50-iteration cap is intentionally loose \u2014 it is a runaway safety net,\n * not a UX signal. By the time it trips, the user has already watched the\n * same response 50 times.\n *\n * ## Approach\n *\n * A small, pure, browser-safe stateful helper that records the last few\n * prompts fed through the auto-proceed / auto-submit path. It normalizes\n * prompts (whitespace, casing) so trivial rewordings are not collapsed, but\n * identical re-feeds are. When the same normalized prompt is fed\n * `repeatThreshold` (default 2) times in a row, the guard returns\n * `{ shouldHalt: true }`.\n *\n * Callers are expected to:\n *   1. Call `record(prompt)` immediately before each auto-feed.\n *   2. If `shouldHalt` is true, clear the suggestion + auto-suggestion store,\n *      cancel any pending countdown, and surface a \"we detected a loop\"\n *      message asking the user what's happening. Do NOT feed the prompt.\n *   3. Call `reset()` whenever the user types anything manually (REPL manual\n *      input or any user-driven submit) so the next auto-feed starts clean.\n *\n * The default `repeatThreshold` is 2 \u2014 i.e. the second consecutive identical\n * feed (the first re-feed of an already-seen prompt) halts the loop. That\n * matches the user's report (\"receiving the same prompt 2-3 times in a row\n * causes the system to enter a loop\"). Setting it to 2 catches the loop on\n * the first identical re-feed rather than after the 50-iteration runaway cap trips.\n *\n * The window size is intentionally small (default 3). The loop we care about\n * is the immediate repetition \u2014 a longer history would misfire on legitimate\n * \"do X, then do Y, then do X\" sequences the model occasionally returns to.\n *\n * This module is BROWSER-SAFE \u2014 no Node-only imports \u2014 so it can be imported\n * from Vite-bundled WebUI as well as Node-based CLI/TUI.\n */\n\n/**\n * Normalize a prompt for repetition comparison. Whitespace is collapsed and\n * trimmed; case is folded to lowercase. Nothing semantic is removed, so two\n * prompts that differ in any meaningful way (extra word, different code,\n * different file path) compare as distinct. Two prompts that differ only by\n * leading/trailing whitespace and casing are treated as identical.\n */\nexport function normalizeForRepetition(prompt: string): string {\n  return prompt.replace(/\\s+/g, ' ').trim().toLowerCase();\n}\n\nexport interface LoopGuardOptions {\n  /**\n   * How many consecutive identical prompts (after normalization) trigger a\n   * halt. Default 2 \u2014 i.e. the second consecutive identical feed (the first\n   * re-feed of an already-seen prompt) halts the loop. Clamped to >= 2.\n   */\n  repeatThreshold?: number;\n  /**\n   * How many of the most recent feeds to retain for comparison. The window\n   * is searched from newest to oldest; the guard cares about the run of\n   * identical entries ending at the most recent one, not about identical\n   * entries anywhere in history. Default 3.\n   */\n  windowSize?: number;\n}\n\nexport interface RepetitionSignal {\n  /** The normalized prompt that just got recorded. */\n  normalized: string;\n  /**\n   * Number of consecutive identical feeds ending at the most recent feed,\n   * including this one. Always >= 1.\n   */\n  runLength: number;\n  /**\n   * True when the run length has crossed `repeatThreshold`. Callers must\n   * stop feeding and surface a user prompt instead.\n   */\n  shouldHalt: boolean;\n}\n\nexport interface AutoProceedLoopGuard {\n  /**\n   * Record a prompt that is about to be auto-fed. Returns the repetition\n   * signal for that prompt. When `shouldHalt` is true the caller MUST NOT\n   * feed the prompt \u2014 it has been recorded for post-mortem inspection, but\n   * the loop must be broken instead.\n   */\n  record(prompt: string): RepetitionSignal;\n  /**\n   * Drop the history. Call this on any manual user input so a fresh run\n   * starts with no memory of the prior cycle.\n   */\n  reset(): void;\n  /**\n   * Read-only view of the most recent normalized prompts (newest last).\n   * Useful for diagnostics and for the message shown to the user when the\n   * guard halts the loop.\n   */\n  history(): readonly string[];\n  /**\n   * How many entries the guard is currently retaining.\n   */\n  size(): number;\n}\n\n/**\n * Build a fresh loop guard. Defaults: `repeatThreshold = 2`, `windowSize = 3`.\n *\n * @example\n *   const guard = createAutoProceedLoopGuard();\n *   for (const prompt of candidates) {\n *     const signal = guard.record(prompt);\n *     if (signal.shouldHalt) {\n *       haltAutoProceedAndAskUser(signal);\n *       break;\n *     }\n *     feedPrompt(prompt);\n *   }\n */\nexport function createAutoProceedLoopGuard(options: LoopGuardOptions = {}): AutoProceedLoopGuard {\n  // Validate options defensively. Non-finite values (NaN, Infinity) MUST\n  // fall back to the documented default \u2014 a guard that silently disables\n  // itself is worse than no guard at all. Specifically:\n  //   - `repeatThreshold: NaN` would cause `Math.floor(NaN) = NaN`,\n  //     `Math.max(2, NaN) = NaN`, and `runLength >= NaN` is always false,\n  //     making the guard permanent no-op.\n  //   - `windowSize: NaN` / `Infinity` would skip the trim branch entirely\n  //     (`buffer.length > NaN` and `buffer.length > Infinity` are both\n  //     false), so the buffer would grow without bound.\n  const safeIntegerOption = (value: number | undefined, fallback: number): number => {\n    if (value === undefined) return fallback;\n    if (!Number.isFinite(value)) return fallback;\n    return Math.floor(value);\n  };\n  const repeatThreshold = Math.max(2, safeIntegerOption(options.repeatThreshold, 2));\n  const windowSize = Math.max(repeatThreshold, safeIntegerOption(options.windowSize, 3));\n  let buffer: string[] = [];\n\n  function record(prompt: string): RepetitionSignal {\n    const normalized = normalizeForRepetition(prompt);\n    buffer.push(normalized);\n    if (buffer.length > windowSize) {\n      buffer = buffer.slice(buffer.length - windowSize);\n    }\n    // Count the trailing run of identical normalized prompts.\n    let runLength = 0;\n    for (let i = buffer.length - 1; i >= 0; i--) {\n      if (buffer[i] === normalized) runLength++;\n      else break;\n    }\n    return {\n      normalized,\n      runLength,\n      shouldHalt: runLength >= repeatThreshold,\n    };\n  }\n\n  function reset(): void {\n    buffer = [];\n  }\n\n  function history(): readonly string[] {\n    return buffer.slice();\n  }\n\n  function size(): number {\n    return buffer.length;\n  }\n\n  return { record, reset, history, size };\n}\n"],
+  "mappings": ";AA2DO,SAAS,uBAAuB,QAAwB;AAC7D,SAAO,OAAO,QAAQ,QAAQ,GAAG,EAAE,KAAK,EAAE,YAAY;AACxD;AAwEO,SAAS,2BAA2B,UAA4B,CAAC,GAAyB;AAU/F,QAAM,oBAAoB,CAAC,OAA2B,aAA6B;AACjF,QAAI,UAAU,OAAW,QAAO;AAChC,QAAI,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO;AACpC,WAAO,KAAK,MAAM,KAAK;AAAA,EACzB;AACA,QAAM,kBAAkB,KAAK,IAAI,GAAG,kBAAkB,QAAQ,iBAAiB,CAAC,CAAC;AACjF,QAAM,aAAa,KAAK,IAAI,iBAAiB,kBAAkB,QAAQ,YAAY,CAAC,CAAC;AACrF,MAAI,SAAmB,CAAC;AAExB,WAAS,OAAO,QAAkC;AAChD,UAAM,aAAa,uBAAuB,MAAM;AAChD,WAAO,KAAK,UAAU;AACtB,QAAI,OAAO,SAAS,YAAY;AAC9B,eAAS,OAAO,MAAM,OAAO,SAAS,UAAU;AAAA,IAClD;AAEA,QAAI,YAAY;AAChB,aAAS,IAAI,OAAO,SAAS,GAAG,KAAK,GAAG,KAAK;AAC3C,UAAI,OAAO,CAAC,MAAM,WAAY;AAAA,UACzB;AAAA,IACP;AACA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,YAAY,aAAa;AAAA,IAC3B;AAAA,EACF;AAEA,WAAS,QAAc;AACrB,aAAS,CAAC;AAAA,EACZ;AAEA,WAAS,UAA6B;AACpC,WAAO,OAAO,MAAM;AAAA,EACtB;AAEA,WAAS,OAAe;AACtB,WAAO,OAAO;AAAA,EAChB;AAEA,SAAO,EAAE,QAAQ,OAAO,SAAS,KAAK;AACxC;",
+  "names": []
+}