rovecode 0.3.3 → 0.4.0-beta.3

package/src/core/guardrails.ts

@@ -1,400 +0,0 @@
-/**
- * Tool-loop guardrails — ported from hermes-agent `agent/tool_guardrails.py`
- * (snapshot: research/source_snapshots/hermes-agent). Bare `:N`
- * citations refer to that file; `run_agent.py:N` cites the runtime wiring.
- *
- * Pure and injectable: no I/O, no globals, no clock. State is one consecutive
- * identical-call streak plus a per-turn call ordinal — O(1) by construction
- * (upstream scalar fields :353-359, reset per user turn in `reset_for_turn`
- * :340-369). Only sha256 hashes are retained, never result payloads.
- *
- * Ported behavior:
- *  - Call signature = tool name + canonical JSON args (sorted keys, compact,
- *    unicode raw, `default=str`) — canonical_tool_args :285-295, hashed via
- *    ToolCallSignature.from_call :243-246 and _sha256 :849-855. Non-mapping
- *    args coerce to {} (:770-771).
- *  - Consecutive identical-call escalation, warn before stub: warn once the
- *    streak exceeds `warnAfterRepeats` (default 2, :119/:123 — first warn is
- *    the 3rd consecutive call, upstream's loop-notice threshold :85, fired
- *    :596-599); stub once it exceeds `stubAfterRepeats` (default 5,
- *    :120/:124 — before_call blocks :391-427 and the runtime substitutes a
- *    synthetic result, run_agent.py:8517-8519, :727-735 = "stub" here).
- *  - Duplicate-result dedup: from the 2nd consecutive identical call whose
- *    fresh result hashes identical (:608-616, :611), the payload becomes a
- *    reference stub (:629-657): min 512 chars (:93, :613), never for failed /
- *    error-looking results (:91-92, :612; classifier tail :326-328), args
- *    preview capped at 120 chars (:98, :642-643). A changed result flows
- *    through whole and resets the streak (:570-571, :585-591).
- *  - Poller exemption: repeatable tools (`process`, `*_get_result`, `*_poll`)
- *    never receive warn/stub verdicts (:63-80, :101-105) but their duplicate
- *    results ARE still dedup-stubbed (:562-567).
- *
- * Deliberate deviations (also listed in the port report):
- *  - `hardStop` defaults to true (upstream hard_stop_enabled false, :118):
- *    the rovecode GuardVerdict contract requires warn→stub escalation by
- *    default. Pass `hardStop: false` for upstream's warn-only default.
- *  - Upstream escalates on failed / idempotent-no-progress completions
- *    (:443-520); the port escalates on consecutive same-signature repetition
- *    (:344-359), forgiven when `checkResult` sees a changed result
- *    (progress-resets, :502-503, :585-591).
- *  - Hermes failure classifiers (:312-324), per-turn caps (:659-724), and
- *    spillover-path stubs (:619-627, :651-657) are out of scope here.
- *  - The dedup stub notes the original result length (task requirement;
- *    upstream omits it, :646-650) and points at the per-turn call ordinal
- *    instead of a tool_call_id (this API has none; upstream likewise omits
- *    the pointer when no id exists, :644-645).
- *  - Poller exemption reaches THROUGH rovecode's mcp_call indirection: every
- *    MCP tool is funneled via the single mcp_call house tool
- *    (src/mcp/tools.ts), so upstream's suffix exemption — aimed at
- *    "generated / MCP tool surfaces" (:74-76) — checks the INNER args.tool
- *    name for mcp_call. Signatures are unaffected (they hash full args).
- *
- * Wiring contract (sequential, as upstream executes tool batches): per tool
- * call run `checkCall` → execute when action !== "stub" → `checkResult` with
- * the RAW output (run_agent.py:8475-8478 — observe the raw result, before any
- * appended guidance). Interleaved/parallel wiring degrades gracefully to
- * fewer detections, never false positives.
- */
-
-import { createHash } from "node:crypto";
-
-export interface GuardVerdict {
-  action: "allow" | "warn" | "stub";
-  /** when warn/stub: text to surface to the model instead of/alongside execution */
-  note?: string;
-}
-
-/** Thresholds mirror upstream defaults; all overridable. */
-export interface GuardrailsOptions {
-  /** gate for warn verdicts (upstream warnings_enabled :117; default true) */
-  warningsEnabled?: boolean;
-  /** gate for stub verdicts (upstream hard_stop_enabled :118 — false there,
-   *  true here; see module doc "deviations") */
-  hardStop?: boolean;
-  /** identical consecutive calls tolerated before warns start; default 2
-   *  (:119/:123) — first warn is the 3rd consecutive call (:85) */
-  warnAfterRepeats?: number;
-  /** identical consecutive calls tolerated before further ones are stubbed;
-   *  default 5 (:120/:124) — the 6th consecutive call is the first blocked */
-  stubAfterRepeats?: number;
-  /** duplicate results shorter than this are never dedup-stubbed; default 512
-   *  (IDENTICAL_RESULT_STUB_MIN_CHARS :93) */
-  dedupMinChars?: number;
-  /** canonical-args preview length inside the dedup stub; default 120
-   *  (_RESULT_STUB_ARGS_PREVIEW_CHARS :98) */
-  argsPreviewChars?: number;
-  /** poller tools exempt from warn/stub verdicts
-   *  (STALL_GUARD_REPEATABLE_TOOLS :68-72) */
-  repeatableTools?: readonly string[];
-  /** poller name suffixes exempt likewise (:77-80) */
-  repeatableSuffixes?: readonly string[];
-}
-
-/** Upstream defaults (citations above), exported for tests and callers. */
-export const GUARDRAIL_DEFAULTS = {
-  warningsEnabled: true,
-  hardStop: true,
-  warnAfterRepeats: 2,
-  stubAfterRepeats: 5,
-  dedupMinChars: 512,
-  argsPreviewChars: 120,
-  repeatableTools: ["process"],
-  repeatableSuffixes: ["_get_result", "_poll"],
-} as const satisfies Required<GuardrailsOptions>;
-
-interface ResolvedOptions {
-  warningsEnabled: boolean;
-  hardStop: boolean;
-  warnAfterRepeats: number;
-  stubAfterRepeats: number;
-  dedupMinChars: number;
-  argsPreviewChars: number;
-  repeatableTools: ReadonlySet<string>;
-  repeatableSuffixes: readonly string[];
-}
-
-/** The single consecutive identical-call streak (upstream fields :353-359). */
-interface Streak {
-  sig: string;
-  /** consecutive identical-signature calls, current call included */
-  count: number;
-  /** hash of the streak's last observed result; null until one is seen */
-  resultHash: string | null;
-  /** 1-based per-turn ordinal of the streak's first call — the dedup stub
-   *  pointer (_identical_streak_first_call_id :357-359) */
-  firstCallIndex: number;
-  /** ordinal of the most recent call — becomes the new first when a changed
-   *  result starts a fresh streak (:589-591) */
-  lastCallIndex: number;
-}
-
-/** Sorted-key compact JSON — ports canonical_tool_args (:285-295): sort_keys,
- *  separators (",",":"), unicode kept raw, default=str for non-JSON values.
- *  Key sort is UTF-16 code-unit order (deterministic; differs from Python's
- *  code-point sort only for astral-plane keys). Cycles degrade to a marker
- *  instead of throwing: a guardrail must never take down the loop. */
-export function canonicalJson(value: unknown, seen: Set<object> = new Set()): string {
-  if (value === null) return "null";
-  switch (typeof value) {
-    case "boolean":
-      return value ? "true" : "false";
-    case "number":
-      // Python json emits NaN/Infinity literally (allow_nan default) — match it
-      return Number.isFinite(value) ? JSON.stringify(value) : String(value);
-    case "string":
-      return JSON.stringify(value);
-    case "object":
-      break;
-    default:
-      // default=str (:294): undefined / bigint / function / symbol → quoted str()
-      return JSON.stringify(String(value));
-  }
-  const obj = value as object;
-  if (seen.has(obj)) return '"[circular]"';
-  seen.add(obj);
-  try {
-    if (Array.isArray(obj)) {
-      return `[${obj.map((v) => canonicalJson(v, seen)).join(",")}]`;
-    }
-    const record = obj as Record<string, unknown>;
-    const parts = Object.keys(record)
-      .sort()
-      .map((k) => `${JSON.stringify(k)}:${canonicalJson(record[k], seen)}`);
-    return `{${parts.join(",")}}`;
-  } finally {
-    seen.delete(obj); // DAG-safe: only true cycles hit the marker
-  }
-}
-
-/** Non-mapping args (arrays included) coerce to {} — ports _coerce_args (:770-771). */
-function coerceArgs(args: unknown): Record<string, unknown> {
-  if (typeof args === "object" && args !== null && !Array.isArray(args)) {
-    return args as Record<string, unknown>;
-  }
-  return {};
-}
-
-/** Deterministic content hash. Upstream hashes utf-8 with surrogatepass
- *  (:849-855); hashing UTF-16LE code units is likewise lossless for lone
- *  surrogates (utf-8 would collapse them to U+FFFD) and never throws. */
-function sha256(text: string): string {
-  return createHash("sha256").update(Buffer.from(text, "utf16le")).digest("hex");
-}
-
-/** Signature = tool name + hash of canonical args (ToolCallSignature.from_call
- *  :243-246). Same tool + same canonical args ⇒ same signature; different
- *  args ⇒ different signature ⇒ never a loop. */
-function signatureOf(tool: string, args: unknown): string {
-  return `${tool}\u0000${sha256(canonicalJson(coerceArgs(args)))}`;
-}
-
-/** Poller-exemption name: rovecode routes all MCP tools through the one `mcp_call`
- *  house tool, so upstream's MCP-surface poller suffixes (:74-80) can never
- *  match the outer name — unwrap to inner args.tool (module doc "deviations").
- *  Exemption only; signatures stay outer name + full args. */
-function exemptionName(tool: string, args: unknown): string {
-  if (tool === "mcp_call") {
-    const inner = coerceArgs(args)["tool"];
-    if (typeof inner === "string" && inner.length > 0) return inner;
-  }
-  return tool;
-}
-
-/** Ports _result_hash (:774-789): JSON results are canonicalized before
- *  hashing; non-JSON hashes raw. Upstream's safe_json_loads yields None for
- *  invalid JSON and literal null alike, so parsed null also hashes raw. */
-function resultHash(output: string): string {
-  let canonical = output;
-  try {
-    const parsed: unknown = JSON.parse(output);
-    if (parsed !== null) canonical = canonicalJson(parsed);
-  } catch {
-    // not JSON → hash the raw string (:787-788)
-  }
-  return sha256(canonical);
-}
-
-/** Generic error sniff, ported from classify_tool_failure's fallback tail
- *  (:326-328); errors are never dedup-stubbed (:91-92, :612). Hermes-specific
- *  branches (:312-324) are not ported. */
-function looksFailed(output: string): boolean {
-  if (output.startsWith("Error")) return true;
-  const head = output.slice(0, 500).toLowerCase();
-  return head.includes('"error"') || head.includes('"failed"');
-}
-
-/** English ordinal ("3rd", "11th") — ports the notice's inline ordinal (:600). */
-function ordinal(n: number): string {
-  const mod100 = n % 100;
-  if (mod100 >= 11 && mod100 <= 13) return `${n}th`;
-  switch (n % 10) {
-    case 1: return `${n}st`;
-    case 2: return `${n}nd`;
-    case 3: return `${n}rd`;
-    default: return `${n}th`;
-  }
-}
-
-/** Junk / non-positive threshold values fall back to the default — ports
- *  _positive_int (:808-815), including float truncation via int(). */
-function positiveInt(value: number | undefined, fallback: number): number {
-  if (value === undefined || !Number.isFinite(value)) return fallback;
-  const parsed = Math.trunc(value);
-  return parsed >= 1 ? parsed : fallback;
-}
-
-export class ToolGuard {
-  private readonly opts: ResolvedOptions;
-  private streak: Streak | null = null;
-  private callIndex = 0;
-
-  constructor(opts?: GuardrailsOptions) {
-    const d = GUARDRAIL_DEFAULTS;
-    this.opts = {
-      warningsEnabled: typeof opts?.warningsEnabled === "boolean" ? opts.warningsEnabled : d.warningsEnabled,
-      hardStop: typeof opts?.hardStop === "boolean" ? opts.hardStop : d.hardStop,
-      warnAfterRepeats: positiveInt(opts?.warnAfterRepeats, d.warnAfterRepeats),
-      stubAfterRepeats: positiveInt(opts?.stubAfterRepeats, d.stubAfterRepeats),
-      dedupMinChars: positiveInt(opts?.dedupMinChars, d.dedupMinChars),
-      argsPreviewChars: positiveInt(opts?.argsPreviewChars, d.argsPreviewChars),
-      repeatableTools: new Set(opts?.repeatableTools ?? d.repeatableTools),
-      repeatableSuffixes: [...(opts?.repeatableSuffixes ?? d.repeatableSuffixes)],
-    };
-  }
-
-  /** Count of signature records retained. Typed `number` (not `0 | 1`) so
-   *  tests of the O(1) bound are not type-system tautologies; the
-   *  single-streak design (:353-359) keeps it ≤ 1. */
-  get trackedSignatures(): number {
-    return this.streak ? 1 : 0;
-  }
-
-  /** Before execution: same-signature repetition tracking (tool + canonical
-   *  args). Any different call resets the streak (:344-351); pollers are
-   *  never annotated (:63-72). Escalation: allow → warn (> warnAfterRepeats)
-   *  → stub (> stubAfterRepeats), upstream's warn-before-block order. */
-  checkCall(tool: string, args: unknown): GuardVerdict {
-    this.callIndex += 1;
-    const sig = signatureOf(tool, args);
-    if (this.streak !== null && this.streak.sig === sig) {
-      this.streak.count += 1;
-      this.streak.lastCallIndex = this.callIndex;
-    } else {
-      this.streak = {
-        sig,
-        count: 1,
-        resultHash: null,
-        firstCallIndex: this.callIndex,
-        lastCallIndex: this.callIndex,
-      };
-    }
-    if (this.isRepeatable(exemptionName(tool, args))) return { action: "allow" };
-    const count = this.streak.count;
-    if (this.opts.hardStop && count > this.opts.stubAfterRepeats) {
-      // block message modeled on before_call's (:396-399, :416-419); surfaced
-      // as a synthetic result upstream (run_agent.py:8517-8519, :727-735)
-      return {
-        action: "stub",
-        note:
-          `[rovecode loop guard: blocked ${tool} — this is the ${ordinal(count)} consecutive call ` +
-          `with identical arguments. Stop repeating it unchanged; change arguments or strategy, ` +
-          `use a different tool, or proceed with what you already have.]`,
-      };
-    }
-    if (this.opts.warningsEnabled && count > this.opts.warnAfterRepeats) {
-      // warn text modeled on the identical-call loop notice (:600-606)
-      return {
-        action: "warn",
-        note:
-          `[rovecode loop guard: this is the ${ordinal(count)} consecutive call to ${tool} ` +
-          `with identical arguments. This looks like a loop — change arguments, use a ` +
-          `different tool, or proceed with what you have.]`,
-      };
-    }
-    return { action: "allow" };
-  }
-
-  /** After execution: byte-identical duplicate result detection (:608-616);
-   *  from the 2nd consecutive identical call the payload becomes a reference
-   *  stub; a changed result passes whole and resets the streak (:570-571,
-   *  :585-591). Call with the RAW output (run_agent.py:8475-8478). `ok` is
-   *  the caller's structured success flag: FAILED results (ok=false) are
-   *  NEVER stubbed — upstream keeps every error verbatim (:91-92, :612) —
-   *  the string sniff is only a fallback when `ok` is not given. */
-  checkResult(tool: string, args: unknown, output: string, ok?: boolean): { output: string; deduped: boolean } {
-    const sig = signatureOf(tool, args);
-    const hash = resultHash(output);
-    if (this.streak === null || this.streak.sig !== sig) {
-      // Result for a call this guard did not see via checkCall (out-of-order
-      // wiring) — adopt it as a fresh streak baseline; detection degrades
-      // gracefully, never false-positives.
-      const idx = Math.max(1, this.callIndex);
-      this.streak = { sig, count: 1, resultHash: hash, firstCallIndex: idx, lastCallIndex: idx };
-      return { output, deduped: false };
-    }
-    const s = this.streak;
-    if (s.resultHash === null) {
-      s.resultHash = hash; // first result of the streak = baseline
-      return { output, deduped: false };
-    }
-    if (s.resultHash !== hash) {
-      // Changed result = progress: the current call starts a new streak
-      // (:585-591) — this also forgives checkCall's warn/stub escalation,
-      // mirroring upstream's reset-on-changed-hash (:502-503).
-      s.count = 1;
-      s.resultHash = hash;
-      s.firstCallIndex = s.lastCallIndex;
-      return { output, deduped: false };
-    }
-    // Identical result (byte-identical; canonically identical for JSON, :774-789).
-    if (
-      s.count < 2 || // stub only from the 2nd identical call (:611)
-      output.length < this.opts.dedupMinChars || // (:93, :613)
-      ok === false || // structured failure: errors always pass verbatim (:91-92, :612)
-      looksFailed(output) // string-sniff fallback when the caller gave no ok flag
-    ) {
-      return { output, deduped: false };
-    }
-    return { output: this.buildDedupStub(tool, args, output.length, s.firstCallIndex), deduped: true };
-  }
-
-  /** USER-turn boundary — call once per agentLoop invocation (and per queued
-   *  follow-up), NEVER per model iteration inside the loop: upstream
-   *  reset_for_turn runs at the start of each run_conversation
-   *  (turn_context.py:700), once per user message; the streak must survive
-   *  model iterations or the guard is inert (:338, :340-369). */
-  onTurn(): void {
-    this.reset();
-  }
-
-  /** Full reset — same as onTurn (all upstream state is per-user-turn). */
-  reset(): void {
-    this.streak = null;
-    this.callIndex = 0;
-  }
-
-  /** Ports is_stall_guard_repeatable (:101-105): allowlisted background-job
-   *  pollers (:68-72) plus vendor poller suffixes (:77-80). Exempt from
-   *  warn/stub verdicts; NOT exempt from result dedup (:562-567). */
-  private isRepeatable(tool: string): boolean {
-    if (this.opts.repeatableTools.has(tool)) return true;
-    return this.opts.repeatableSuffixes.some((suffix) => tool.endsWith(suffix));
-  }
-
-  /** Ports _build_result_reference_stub (:629-657): tool name + pointer to the
-   *  first occurrence + canonical-args preview so the model still knows WHAT
-   *  the call was if compression later evicts the referenced result (:96-98).
-   *  Deviations: per-turn call ordinal instead of tool_call_id (:644-645) and
-   *  the original length is noted (task requirement; upstream omits it). */
-  private buildDedupStub(tool: string, args: unknown, originalLen: number, firstCallIndex: number): string {
-    let preview = canonicalJson(coerceArgs(args));
-    if (preview.length > this.opts.argsPreviewChars) {
-      preview = preview.slice(0, this.opts.argsPreviewChars) + "…"; // (:642-643)
-    }
-    return (
-      `[rovecode note: this result is byte-identical to the ${tool} result of call ` +
-      `#${firstCallIndex} earlier this turn (original ${originalLen} chars). ` +
-      `Refer to that result; it has not changed. Args: ${preview}]`
-    );
-  }
-}