@osama.ansar/agent-loopguard 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,932 @@
+'use strict';
+
+// src/detectors/budget.ts
+var SPEC = [
+  { option: "maxTotalTokens", metric: "totalTokens", code: "BUDGET_TOTAL_TOKENS", label: "total tokens" },
+  { option: "maxInputTokens", metric: "inputTokens", code: "BUDGET_INPUT_TOKENS", label: "input tokens" },
+  { option: "maxOutputTokens", metric: "outputTokens", code: "BUDGET_OUTPUT_TOKENS", label: "output tokens" },
+  { option: "maxCostUsd", metric: "costUsd", code: "BUDGET_COST_USD", label: "cost (USD)" },
+  { option: "maxDurationMs", metric: "durationMs", code: "BUDGET_DURATION_MS", label: "duration (ms)" }
+];
+function checkRatio(name, ratio) {
+  if (typeof ratio !== "number" || !(ratio > 0 && ratio < 1)) {
+    throw new TypeError(`agent-loopguard: ${name} must be a number strictly between 0 and 1, got ${String(ratio)}`);
+  }
+  return ratio;
+}
+var BudgetDetector = class {
+  constructor(options, now) {
+    this.now = now;
+    const defaultWarn = options.warnAt === void 0 ? void 0 : checkRatio("budget.warnAt", options.warnAt);
+    const limits = [];
+    for (const spec of SPEC) {
+      const raw = options[spec.option];
+      if (raw === void 0) continue;
+      const limit = typeof raw === "number" ? raw : raw.limit;
+      if (typeof limit !== "number" || !(limit > 0) || !Number.isFinite(limit)) {
+        throw new TypeError(`agent-loopguard: budget.${spec.option} must be a positive finite number, got ${String(limit)}`);
+      }
+      const ownWarn = typeof raw === "number" ? void 0 : raw.warnAt;
+      const warnAt = ownWarn === void 0 ? defaultWarn : checkRatio(`budget.${spec.option}.warnAt`, ownWarn);
+      limits.push({ metric: spec.metric, limit, warnAt, code: spec.code, label: spec.label });
+    }
+    this.limits = limits;
+    this.startedAt = now();
+  }
+  now;
+  limits;
+  startedAt;
+  lastUsed = zeroUsed();
+  observe(_record, ctx) {
+    const recorded = this.recorded(ctx);
+    this.lastUsed = recorded;
+    const used = this.withWallClock(recorded);
+    let stop;
+    const warnings = [];
+    for (const { metric, limit, warnAt, code, label } of this.limits) {
+      const value = used[metric];
+      if (value >= limit) {
+        if (stop === void 0) {
+          const evidence = { metric, value, limit };
+          stop = {
+            stop: true,
+            reason: "budget",
+            code,
+            detail: `Budget exhausted: ${label} reached ${value} of the ${limit} allowed.`,
+            evidence
+          };
+        }
+      } else if (warnAt !== void 0 && value >= warnAt * limit) {
+        const ratio = value / limit;
+        warnings.push({
+          code: "BUDGET_WARNING",
+          metric,
+          value,
+          limit,
+          ratio,
+          detail: `Budget warning: ${label} is at ${Math.round(ratio * 100)}% of the ${limit} allowed (${value} used).`
+        });
+      }
+    }
+    if (stop === void 0 && warnings.length === 0) return void 0;
+    const result = {};
+    if (stop !== void 0) result.stop = stop;
+    if (warnings.length > 0) result.warnings = warnings;
+    return result;
+  }
+  recorded(ctx) {
+    return {
+      totalTokens: ctx.totals.totalTokens,
+      inputTokens: ctx.totals.inputTokens,
+      outputTokens: ctx.totals.outputTokens,
+      costUsd: ctx.totals.costUsd,
+      durationMs: ctx.totals.durationMs
+    };
+  }
+  withWallClock(recorded) {
+    if (!this.limits.some((l) => l.metric === "durationMs")) return recorded;
+    const elapsed = this.now() - this.startedAt;
+    if (!Number.isFinite(elapsed) || elapsed <= recorded.durationMs) return recorded;
+    return { ...recorded, durationMs: elapsed };
+  }
+  state() {
+    const limits = {};
+    for (const l of this.limits) limits[l.metric] = l.limit;
+    return { limits, used: { ...this.lastUsed } };
+  }
+  reset() {
+    this.startedAt = this.now();
+    this.lastUsed = zeroUsed();
+  }
+};
+function zeroUsed() {
+  return { totalTokens: 0, inputTokens: 0, outputTokens: 0, costUsd: 0, durationMs: 0 };
+}
+
+// src/canonical.ts
+var MAX_DEPTH = 64;
+var MAX_NODES = 2e5;
+var fallbackCounter = 0;
+function canonicalize(value) {
+  try {
+    const out = [];
+    write(value, { nodes: 0, stack: [] }, out);
+    return out.join("");
+  } catch {
+    fallbackCounter += 1;
+    return `[Uncanonicalizable#${fallbackCounter}]`;
+  }
+}
+function write(value, walk, out) {
+  walk.nodes += 1;
+  if (walk.nodes > MAX_NODES) {
+    out.push("[Truncated]");
+    return;
+  }
+  switch (typeof value) {
+    case "undefined":
+      out.push("undefined");
+      return;
+    case "boolean":
+      out.push(value ? "true" : "false");
+      return;
+    case "number":
+      if (Number.isNaN(value)) out.push("NaN");
+      else if (Object.is(value, -0)) out.push("0");
+      else out.push(String(value));
+      return;
+    case "bigint":
+      out.push(`${value.toString()}n`);
+      return;
+    case "string":
+      out.push(JSON.stringify(value));
+      return;
+    case "symbol":
+      out.push(`Symbol(${String(value.description)})`);
+      return;
+    case "function":
+      out.push(`[Function ${String(value.name)}]`);
+      return;
+  }
+  if (value === null) {
+    out.push("null");
+    return;
+  }
+  const obj = value;
+  const ancestor = walk.stack.indexOf(obj);
+  if (ancestor !== -1) {
+    out.push(`[Circular:${ancestor}]`);
+    return;
+  }
+  if (walk.stack.length >= MAX_DEPTH) {
+    out.push("[MaxDepth]");
+    return;
+  }
+  walk.stack.push(obj);
+  try {
+    writeObject(obj, walk, out);
+  } finally {
+    walk.stack.pop();
+  }
+}
+function writeObject(obj, walk, out) {
+  if (obj instanceof Date) {
+    const time = obj.getTime();
+    out.push(Number.isNaN(time) ? "Date(invalid)" : `Date(${obj.toISOString()})`);
+    return;
+  }
+  if (obj instanceof RegExp) {
+    out.push(`RegExp(${String(obj)})`);
+    return;
+  }
+  if (Array.isArray(obj)) {
+    out.push("[");
+    for (let i = 0; i < obj.length; i += 1) {
+      if (i > 0) out.push(",");
+      write(obj[i], walk, out);
+    }
+    out.push("]");
+    return;
+  }
+  if (obj instanceof Map) {
+    const entries = [];
+    for (const [k, v] of obj) {
+      const part = [];
+      write(k, walk, part);
+      part.push("=>");
+      write(v, walk, part);
+      entries.push(part.join(""));
+    }
+    out.push(`Map{${entries.sort().join(",")}}`);
+    return;
+  }
+  if (obj instanceof Set) {
+    const items = [];
+    for (const v of obj) {
+      const part = [];
+      write(v, walk, part);
+      items.push(part.join(""));
+    }
+    out.push(`Set{${items.sort().join(",")}}`);
+    return;
+  }
+  if (ArrayBuffer.isView(obj)) {
+    const bytes = new Uint8Array(obj.buffer, obj.byteOffset, obj.byteLength);
+    out.push(`${constructorName(obj)}<${Array.prototype.join.call(bytes, ",")}>`);
+    return;
+  }
+  if (obj instanceof ArrayBuffer) {
+    out.push(`ArrayBuffer<${Array.prototype.join.call(new Uint8Array(obj), ",")}>`);
+    return;
+  }
+  if (obj instanceof Error) {
+    out.push(`Error(${String(obj.name)}: ${String(obj.message)})`);
+    return;
+  }
+  const toJSON = obj.toJSON;
+  if (typeof toJSON === "function") {
+    const json = toJSON.call(obj);
+    out.push("toJSON:");
+    write(json, walk, out);
+    return;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) out.push(constructorName(obj));
+  out.push("{");
+  let first = true;
+  for (const key of Object.keys(obj).sort()) {
+    let v;
+    try {
+      v = obj[key];
+    } catch {
+      v = "[Unreadable]";
+    }
+    if (v === void 0) continue;
+    if (!first) out.push(",");
+    first = false;
+    out.push(JSON.stringify(key), ":");
+    write(v, walk, out);
+  }
+  out.push("}");
+}
+function constructorName(obj) {
+  const ctor = obj.constructor;
+  return typeof ctor?.name === "string" && ctor.name !== "" ? ctor.name : "Object";
+}
+function cyrb53(input, seed) {
+  let h1 = 3735928559 ^ seed;
+  let h2 = 1103547991 ^ seed;
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+function stableHash(value) {
+  return hashString(canonicalize(value));
+}
+function hashString(text) {
+  const a = cyrb53(text, 0).toString(16).padStart(14, "0");
+  const b = cyrb53(text, 2654435769).toString(16).padStart(14, "0");
+  return a + b;
+}
+var INLINE_LIMIT = 256;
+var PREVIEW_LIMIT = 80;
+function describe(value) {
+  const canonical = canonicalize(value);
+  return {
+    signature: canonical.length <= INLINE_LIMIT ? canonical : `#${canonical.length}:${hashString(canonical)}`,
+    preview: truncate(canonical, PREVIEW_LIMIT)
+  };
+}
+function truncate(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
+}
+
+// src/record.ts
+function normalizeFinishReason(reason) {
+  return reason.trim().toLowerCase().replace(/_/g, "-");
+}
+function normalizeText(text) {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function get(obj, key) {
+  try {
+    return obj[key];
+  } catch {
+    return void 0;
+  }
+}
+function isArray(value) {
+  try {
+    return Array.isArray(value);
+  } catch {
+    return false;
+  }
+}
+function buildCall(raw) {
+  if (!isObject(raw)) return void 0;
+  const rawName = get(raw, "name");
+  const name = typeof rawName === "string" ? rawName : describe(rawName).signature;
+  const args = describe(get(raw, "args"));
+  const error = get(raw, "error");
+  const result = get(raw, "result");
+  const failed = error !== void 0 && error !== null;
+  const callSig = `${JSON.stringify(name)}(${args.signature})`;
+  let resultSig;
+  if (failed) resultSig = `error:${describe(error).signature}`;
+  else if (result !== void 0) resultSig = `ok:${describe(result).signature}`;
+  return {
+    name,
+    label: `${name}(${args.preview})`,
+    callSig,
+    resultSig,
+    // With no result supplied the call itself stands in as "the evidence".
+    outcomeSig: resultSig === void 0 ? callSig : `${callSig}=>${resultSig}`,
+    failed,
+    argsPreview: args.preview
+  };
+}
+function buildCalls(step) {
+  const calls = [];
+  try {
+    const raw = get(step, "toolCalls");
+    if (!isArray(raw)) return calls;
+    for (const item of raw) {
+      const call = buildCall(item);
+      if (call !== void 0) calls.push(call);
+    }
+  } catch {
+  }
+  return calls;
+}
+function buildRecord(step, index) {
+  const s = isObject(step) ? step : {};
+  const rawUsage = get(s, "usage");
+  const usage = isObject(rawUsage) ? rawUsage : {};
+  const inputTokens = num(get(usage, "inputTokens"));
+  const outputTokens = num(get(usage, "outputTokens"));
+  let totalTokens = num(get(usage, "totalTokens"));
+  if (totalTokens === void 0 && (inputTokens !== void 0 || outputTokens !== void 0)) {
+    totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
+  }
+  const rawFinish = get(s, "finishReason");
+  const finishReason = typeof rawFinish === "string" && rawFinish.trim() !== "" ? normalizeFinishReason(rawFinish) : void 0;
+  const rawText = get(s, "text");
+  return {
+    index,
+    calls: buildCalls(s),
+    text: typeof rawText === "string" ? normalizeText(rawText) : "",
+    finishReason,
+    rawFinishReason: typeof rawFinish === "string" && finishReason !== void 0 ? rawFinish : void 0,
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    costUsd: num(get(usage, "costUsd")),
+    durationMs: num(get(s, "durationMs"))
+  };
+}
+
+// src/detectors/finishReason.ts
+var DEFAULT_TERMINAL_FINISH_REASONS = ["stop", "length", "content-filter", "error"];
+var OTHER_POLICIES = ["stop", "continue", "stop-if-text-only"];
+var FinishReasonDetector = class {
+  terminal;
+  otherPolicy;
+  last = null;
+  constructor(options = {}) {
+    this.terminal = new Set((options.terminal ?? DEFAULT_TERMINAL_FINISH_REASONS).map(normalizeFinishReason));
+    const policy = options.otherPolicy ?? "stop-if-text-only";
+    if (!OTHER_POLICIES.includes(policy)) {
+      throw new TypeError(
+        `agent-loopguard: finishReason.otherPolicy must be one of ${OTHER_POLICIES.join(", ")}, got ${String(policy)}`
+      );
+    }
+    this.otherPolicy = policy;
+  }
+  observe(record) {
+    const normalized = record.finishReason;
+    if (normalized === void 0) return void 0;
+    this.last = normalized;
+    const raw = record.rawFinishReason ?? normalized;
+    const hasText = record.text !== "";
+    const toolCallCount = record.calls.length;
+    const evidence = (policy) => ({
+      finishReason: raw,
+      normalized,
+      policy,
+      hasText,
+      toolCallCount
+    });
+    if (this.terminal.has(normalized)) {
+      return {
+        stop: {
+          stop: true,
+          reason: "finish-reason",
+          code: "FINISH_TERMINAL",
+          detail: `The model finished with "${raw}", which ends the run.`,
+          evidence: evidence("terminal")
+        }
+      };
+    }
+    if (normalized === "tool-calls") return void 0;
+    if (this.otherPolicy === "stop") {
+      return {
+        stop: {
+          stop: true,
+          reason: "finish-reason",
+          code: "FINISH_OTHER",
+          detail: `The model finished with the unfamiliar reason "${raw}" and the policy is to stop on those.`,
+          evidence: evidence("other-stop")
+        }
+      };
+    }
+    if (this.otherPolicy === "stop-if-text-only" && hasText && toolCallCount === 0) {
+      return {
+        stop: {
+          stop: true,
+          reason: "finish-reason",
+          code: "FINISH_OTHER_TEXT_ONLY",
+          detail: `The model returned text with no tool calls and the unfamiliar finish reason "${raw}"; re-sending would likely repeat the same answer.`,
+          evidence: evidence("other-text-only")
+        }
+      };
+    }
+    return void 0;
+  }
+  state() {
+    return { lastFinishReason: this.last };
+  }
+  reset() {
+    this.last = null;
+  }
+};
+
+// src/detectors/types.ts
+function assertInteger(name, value, min) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+    throw new TypeError(`agent-loopguard: ${name} must be an integer >= ${min}, got ${String(value)}`);
+  }
+  return value;
+}
+
+// src/detectors/maxSteps.ts
+var MaxStepsDetector = class {
+  limit;
+  steps = 0;
+  constructor(limit) {
+    this.limit = assertInteger("maxSteps", limit, 1);
+  }
+  observe(_record) {
+    this.steps += 1;
+    if (this.steps < this.limit) return void 0;
+    return {
+      stop: {
+        stop: true,
+        reason: "max-steps",
+        code: "MAX_STEPS",
+        detail: `Reached the limit of ${this.limit} steps.`,
+        evidence: { steps: this.steps, limit: this.limit }
+      }
+    };
+  }
+  remaining() {
+    return Math.max(0, this.limit - this.steps);
+  }
+  reset() {
+    this.steps = 0;
+  }
+};
+
+// src/detectors/noProgress.ts
+var NoProgressDetector = class {
+  threshold;
+  seen = /* @__PURE__ */ new Set();
+  streak = 0;
+  streakText = "";
+  constructor(options = {}) {
+    this.threshold = assertInteger("noProgress.threshold", options.threshold ?? 3, 2);
+  }
+  observe(record) {
+    let hasNew = false;
+    for (const call of record.calls) {
+      if (!this.seen.has(call.outcomeSig)) {
+        hasNew = true;
+        this.seen.add(call.outcomeSig);
+      }
+    }
+    if (hasNew) {
+      this.streak = 0;
+    } else if (this.streak > 0 && record.text === this.streakText) {
+      this.streak += 1;
+    } else {
+      this.streak = 1;
+      this.streakText = record.text;
+    }
+    if (this.streak < this.threshold) return void 0;
+    const preview = truncate(this.streakText, 80);
+    return {
+      stop: {
+        stop: true,
+        reason: "no-progress",
+        code: "NO_PROGRESS",
+        detail: this.streakText === "" ? `No progress: ${this.streak} consecutive steps produced no new tool results and no text.` : `No progress: ${this.streak} consecutive steps repeated the same text and produced no new tool results ("${preview}").`,
+        evidence: { steps: this.streak, threshold: this.threshold, textPreview: preview }
+      }
+    };
+  }
+  state() {
+    return { threshold: this.threshold, streak: this.streak };
+  }
+  reset() {
+    this.seen.clear();
+    this.streak = 0;
+    this.streakText = "";
+  }
+};
+
+// src/detectors/oscillation.ts
+var WINDOW = 4096;
+var OscillationDetector = class {
+  maxPeriod;
+  repeats;
+  sigs = [];
+  labels = [];
+  current = null;
+  constructor(options = {}) {
+    this.maxPeriod = assertInteger("oscillation.maxPeriod", options.maxPeriod ?? 3, 2);
+    this.repeats = assertInteger("oscillation.repeats", options.repeats ?? 3, 2);
+  }
+  observe(record) {
+    let found;
+    for (const call of record.calls) {
+      this.sigs.push(call.callSig);
+      this.labels.push(call.label);
+      if (this.sigs.length > WINDOW) {
+        this.sigs.splice(0, WINDOW / 2);
+        this.labels.splice(0, WINDOW / 2);
+      }
+      found = this.detect() ?? found;
+    }
+    this.current = found ? { period: found.period, repeats: found.repeats } : null;
+    if (!found) return void 0;
+    return {
+      stop: {
+        stop: true,
+        reason: "oscillation",
+        code: "OSCILLATION",
+        detail: `The agent is oscillating: a cycle of ${found.period} calls (${found.cycle.join(" -> ")}) repeated ${found.repeats} times in a row.`,
+        evidence: found
+      }
+    };
+  }
+  /** Look for a repeating cycle at the very end of the sequence. */
+  detect() {
+    const n = this.sigs.length;
+    for (let period = 2; period <= this.maxPeriod; period += 1) {
+      if (n < period * this.repeats) continue;
+      let matching = 0;
+      for (let i = n - 1; i >= period && this.sigs[i] === this.sigs[i - period]; i -= 1) matching += 1;
+      const cycles = Math.floor(matching / period) + 1;
+      if (cycles < this.repeats) continue;
+      const cycle = this.sigs.slice(n - period);
+      if (new Set(cycle).size < 2) continue;
+      return {
+        period,
+        repeats: cycles,
+        threshold: this.repeats,
+        cycle: this.labels.slice(n - period)
+      };
+    }
+    return void 0;
+  }
+  state() {
+    return { maxPeriod: this.maxPeriod, repeats: this.repeats, current: this.current };
+  }
+  reset() {
+    this.sigs = [];
+    this.labels = [];
+    this.current = null;
+  }
+};
+var RepeatedToolCallDetector = class {
+  threshold;
+  requireIdenticalResults;
+  ignoreErrors;
+  runKey;
+  runTool = "";
+  runPreview = "";
+  runLength = 0;
+  runSteps = [];
+  longest = 0;
+  constructor(options = {}) {
+    this.threshold = assertInteger("repeatedToolCall.threshold", options.threshold ?? 3, 2);
+    this.requireIdenticalResults = options.requireIdenticalResults ?? false;
+    this.ignoreErrors = options.ignoreErrors ?? false;
+  }
+  observe(record) {
+    let hit;
+    for (const call of record.calls) {
+      if (this.ignoreErrors && call.failed) continue;
+      this.extendRun(call, record.index);
+      if (this.runLength >= this.threshold) hit = this.evidence();
+    }
+    if (hit === void 0) return void 0;
+    const results = hit.identicalResults ? " and identical results" : "";
+    return {
+      stop: {
+        stop: true,
+        reason: "repeated-tool-call",
+        code: "REPEATED_TOOL_CALL",
+        detail: `Tool "${hit.tool}" was called ${hit.count} times in a row with identical arguments${results}: ${hit.tool}(${hit.argsPreview}).`,
+        evidence: hit
+      }
+    };
+  }
+  extendRun(call, stepIndex) {
+    const key = this.requireIdenticalResults ? call.outcomeSig : call.callSig;
+    if (key === this.runKey) {
+      this.runLength += 1;
+      if (this.runSteps[this.runSteps.length - 1] !== stepIndex) this.runSteps.push(stepIndex);
+    } else {
+      this.runKey = key;
+      this.runTool = call.name;
+      this.runPreview = call.argsPreview;
+      this.runLength = 1;
+      this.runSteps = [stepIndex];
+    }
+    if (this.runLength > this.longest) this.longest = this.runLength;
+  }
+  evidence() {
+    return {
+      tool: this.runTool,
+      argsPreview: this.runPreview,
+      count: this.runLength,
+      threshold: this.threshold,
+      stepIndexes: this.runSteps.slice(-10),
+      identicalResults: this.requireIdenticalResults
+    };
+  }
+  state() {
+    return {
+      threshold: this.threshold,
+      currentRun: this.runLength > 0 ? { tool: this.runTool, length: this.runLength } : null,
+      longestRun: this.longest
+    };
+  }
+  reset() {
+    this.runKey = void 0;
+    this.runTool = "";
+    this.runPreview = "";
+    this.runLength = 0;
+    this.runSteps = [];
+    this.longest = 0;
+  }
+};
+
+// src/guard.ts
+var DEFAULT_MAX_STEPS = 50;
+var CustomRunner = class {
+  constructor(fn) {
+    this.fn = fn;
+  }
+  fn;
+  observe(_record, ctx) {
+    const out = this.fn(ctx.history, ctx.step);
+    if (out === void 0 || out === null || out.stop !== true) return void 0;
+    const stop = {
+      stop: true,
+      reason: "custom",
+      code: typeof out.code === "string" && out.code !== "" ? out.code : "CUSTOM",
+      detail: typeof out.detail === "string" ? out.detail : "Stopped by a custom detector.",
+      evidence: out.evidence === void 0 ? null : out.evidence
+    };
+    return { stop };
+  }
+  reset() {
+  }
+};
+function zeroTotals() {
+  return { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0, durationMs: 0 };
+}
+function createGuard(options = {}) {
+  const now = options.now ?? Date.now;
+  const maxSteps = options.maxSteps === false ? void 0 : new MaxStepsDetector(options.maxSteps ?? DEFAULT_MAX_STEPS);
+  const repeated = options.repeatedToolCall === false ? void 0 : new RepeatedToolCallDetector(options.repeatedToolCall);
+  const oscillation = options.oscillation === false ? void 0 : new OscillationDetector(options.oscillation);
+  const noProgress = options.noProgress === false ? void 0 : new NoProgressDetector(options.noProgress);
+  const finish = options.finishReason === false ? void 0 : new FinishReasonDetector(options.finishReason);
+  const budget = options.budget === void 0 || options.budget === false ? void 0 : new BudgetDetector(options.budget, now);
+  const customFns = options.custom === void 0 ? [] : typeof options.custom === "function" ? [options.custom] : options.custom;
+  const custom = customFns.map((fn) => new CustomRunner(fn));
+  const optional = [finish, budget, maxSteps, repeated, oscillation, noProgress, ...custom];
+  const detectors = optional.filter((d) => d !== void 0);
+  let history = [];
+  let totals = zeroTotals();
+  let toolCalls = 0;
+  let failedToolCalls = 0;
+  let lastVerdict = null;
+  function check(step) {
+    const safe = typeof step === "object" && step !== null ? step : {};
+    const record = buildRecord(safe, history.length);
+    history.push(safe);
+    totals.inputTokens += record.inputTokens ?? 0;
+    totals.outputTokens += record.outputTokens ?? 0;
+    totals.totalTokens += record.totalTokens ?? 0;
+    totals.costUsd += record.costUsd ?? 0;
+    totals.durationMs += record.durationMs ?? 0;
+    toolCalls += record.calls.length;
+    failedToolCalls += record.calls.filter((c) => c.failed).length;
+    const ctx = { totals, step: safe, history };
+    let stop;
+    const warnings = [];
+    for (const detector of detectors) {
+      const result = detector.observe(record, ctx);
+      if (result === void 0) continue;
+      if (result.stop !== void 0 && stop === void 0) stop = result.stop;
+      if (result.warnings !== void 0) warnings.push(...result.warnings);
+    }
+    let verdict;
+    if (stop !== void 0) verdict = warnings.length > 0 ? { ...stop, warnings } : stop;
+    else verdict = warnings.length > 0 ? { stop: false, warnings } : { stop: false };
+    lastVerdict = verdict;
+    return verdict;
+  }
+  function reset() {
+    history = [];
+    totals = zeroTotals();
+    toolCalls = 0;
+    failedToolCalls = 0;
+    lastVerdict = null;
+    for (const detector of detectors) detector.reset();
+  }
+  function summary() {
+    return {
+      steps: history.length,
+      toolCalls,
+      failedToolCalls,
+      totals: { ...totals },
+      detectors: {
+        maxSteps: maxSteps ? { limit: maxSteps.limit, remaining: maxSteps.remaining() } : null,
+        repeatedToolCall: repeated ? repeated.state() : null,
+        oscillation: oscillation ? oscillation.state() : null,
+        noProgress: noProgress ? noProgress.state() : null,
+        finishReason: finish ? finish.state() : null,
+        budget: budget ? budget.state() : null
+      },
+      lastVerdict
+    };
+  }
+  return {
+    check,
+    reset,
+    summary,
+    get history() {
+      return Object.freeze([...history]);
+    }
+  };
+}
+
+// src/explain.ts
+function hint(verdict) {
+  switch (verdict.reason) {
+    case "max-steps":
+      return "Raise maxSteps if the task really needs more steps; otherwise find out why the agent is not converging.";
+    case "repeated-tool-call":
+      return "The model keeps issuing the same call. Check that the tool result gives it something to act on, and that the prompt says what to do when a tool fails.";
+    case "oscillation":
+      return "The model is flipping between the same calls. Look for two tools whose results send the model back to each other.";
+    case "no-progress":
+      return "Nothing new is coming back and the model is not saying anything new. Retrying the same request will not help.";
+    case "finish-reason":
+      return verdict.evidence.normalized === "stop" ? "This is the normal end of a run, not a fault." : 'The provider ended this step in a way the loop does not treat as "keep going". Inspect the raw response.';
+    case "budget":
+      return "Raise the limit, shorten the context, or split the task.";
+    case "custom":
+      return "Stopped by a custom detector.";
+  }
+}
+function isFault(verdict) {
+  if (!verdict.stop) return false;
+  return !(verdict.reason === "finish-reason" && verdict.evidence.normalized === "stop");
+}
+function explain(verdict) {
+  const lines = [];
+  if (verdict.stop) {
+    lines.push(`Stop [${verdict.code}] ${verdict.detail}`);
+    lines.push(`Hint: ${hint(verdict)}`);
+  } else {
+    lines.push("Continue.");
+  }
+  for (const warning of verdict.warnings ?? []) lines.push(`Warning [${warning.code}] ${warning.detail}`);
+  return lines.join("\n");
+}
+
+// src/adapters/aiSdk.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function toGuardStep(step) {
+  const results = /* @__PURE__ */ new Map();
+  const errors = /* @__PURE__ */ new Map();
+  const positionalResults = [];
+  for (const r of step.toolResults ?? []) {
+    if (typeof r.toolCallId === "string") results.set(r.toolCallId, "output" in r ? r.output : r.result);
+    else positionalResults.push(r);
+  }
+  for (const part of step.content ?? []) {
+    const p = part;
+    if (isRecord(p) && p["type"] === "tool-error" && typeof p["toolCallId"] === "string") {
+      errors.set(p["toolCallId"], p["error"] ?? "tool-error");
+    }
+  }
+  const toolCalls = (step.toolCalls ?? []).map((call, i) => {
+    const out = { name: call.toolName, args: "input" in call ? call.input : call.args };
+    const id = call.toolCallId;
+    if (typeof id === "string") {
+      if (results.has(id)) out.result = results.get(id);
+      if (errors.has(id)) out.error = errors.get(id);
+    } else {
+      const positional = positionalResults[i];
+      if (positional !== void 0) out.result = "output" in positional ? positional.output : positional.result;
+    }
+    return out;
+  });
+  const guardStep = { toolCalls };
+  if (step.text !== void 0) guardStep.text = step.text;
+  if (step.finishReason !== void 0) guardStep.finishReason = step.finishReason;
+  if (step.usage !== void 0) guardStep.usage = { ...step.usage };
+  const duration = step.performance?.stepTimeMs;
+  if (typeof duration === "number") guardStep.durationMs = duration;
+  return guardStep;
+}
+function toStopWhen(guardFactory = {}, hooks = {}) {
+  const makeGuard = typeof guardFactory === "function" ? guardFactory : () => createGuard(guardFactory);
+  const converted = /* @__PURE__ */ new WeakMap();
+  return ({ steps }) => {
+    const guard = makeGuard();
+    let stopped;
+    for (const step of steps) {
+      let guardStep = converted.get(step);
+      if (guardStep === void 0) {
+        guardStep = toGuardStep(step);
+        converted.set(step, guardStep);
+      }
+      const verdict = guard.check(guardStep);
+      stopped = verdict.stop ? verdict : void 0;
+    }
+    if (stopped === void 0) return false;
+    hooks.onStop?.(stopped);
+    return true;
+  };
+}
+
+// src/adapters/loop.ts
+function isFinal(step) {
+  if (step.done !== void 0) return step.done;
+  return !Array.isArray(step.toolCalls) || step.toolCalls.length === 0;
+}
+async function runAgentLoop(options) {
+  const guard = options.guard ?? createGuard();
+  const { signal } = options;
+  const steps = [];
+  let verdict = { stop: false };
+  for (let index = 0; ; index += 1) {
+    if (signal?.aborted) return { steps, verdict, completed: false, aborted: true };
+    let result;
+    try {
+      result = await options.step(index);
+    } catch (error) {
+      if (signal?.aborted) return { steps, verdict, completed: false, aborted: true };
+      throw error;
+    }
+    steps.push(result);
+    verdict = guard.check(result);
+    options.onVerdict?.(verdict, result, index);
+    if (verdict.stop) {
+      return { steps, verdict, completed: !isFault(verdict), aborted: false };
+    }
+    if (isFinal(result)) return { steps, verdict, completed: true, aborted: false };
+  }
+}
+
+// src/adapters/iterable.ts
+function withGuard(source, guard) {
+  let verdict;
+  async function* run() {
+    for await (const step of source) {
+      verdict = guard.check(step);
+      yield step;
+      if (verdict.stop) return;
+    }
+  }
+  return {
+    [Symbol.asyncIterator]() {
+      verdict = void 0;
+      return run();
+    },
+    get verdict() {
+      return verdict;
+    }
+  };
+}
+
+exports.DEFAULT_MAX_STEPS = DEFAULT_MAX_STEPS;
+exports.canonicalize = canonicalize;
+exports.createGuard = createGuard;
+exports.explain = explain;
+exports.isFault = isFault;
+exports.runAgentLoop = runAgentLoop;
+exports.stableHash = stableHash;
+exports.toGuardStep = toGuardStep;
+exports.toStopWhen = toStopWhen;
+exports.withGuard = withGuard;