@osama.ansar/agent-loopguard 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -42,24 +42,32 @@ interface GuardStep {
     /** When the step happened (epoch ms). Informational: recorded in history, not used by detectors. */
     timestamp?: number | undefined;
 }
-type StopReason = 'max-steps' | 'repeated-tool-call' | 'oscillation' | 'no-progress' | 'finish-reason' | 'budget' | 'custom';
+type StopReason = 'max-steps' | 'tool-limit' | 'repeated-tool-call' | 'oscillation' | 'no-progress' | 'finish-reason' | 'budget' | 'custom';
 type BudgetMetric = 'totalTokens' | 'inputTokens' | 'outputTokens' | 'costUsd' | 'durationMs';
 /** Stable machine-readable codes. Safe to switch on; new codes are only added in minor versions. */
-type BuiltinStopCode = 'MAX_STEPS' | 'REPEATED_TOOL_CALL' | 'OSCILLATION' | 'NO_PROGRESS' | 'FINISH_TERMINAL' | 'FINISH_OTHER' | 'FINISH_OTHER_TEXT_ONLY' | 'BUDGET_TOTAL_TOKENS' | 'BUDGET_INPUT_TOKENS' | 'BUDGET_OUTPUT_TOKENS' | 'BUDGET_COST_USD' | 'BUDGET_DURATION_MS';
+type BuiltinStopCode = 'MAX_STEPS' | 'TOOL_CALL_CAP' | 'REPEATED_TOOL_CALL' | 'OSCILLATION' | 'NO_PROGRESS' | 'FINISH_TERMINAL' | 'FINISH_OTHER' | 'FINISH_OTHER_TEXT_ONLY' | 'BUDGET_TOTAL_TOKENS' | 'BUDGET_INPUT_TOKENS' | 'BUDGET_OUTPUT_TOKENS' | 'BUDGET_COST_USD' | 'BUDGET_DURATION_MS';
 interface MaxStepsEvidence {
     steps: number;
     limit: number;
 }
+interface ToolLimitEvidence {
+    tool: string;
+    /** Calls to the tool in this run, counting the one that went over. */
+    calls: number;
+    /** The tool's `maxCalls`. */
+    limit: number;
+}
 interface RepeatedToolCallEvidence {
     tool: string;
     /** Canonical form of the arguments, truncated for display. */
     argsPreview: string;
     /** Length of the run of identical calls. */
     count: number;
+    /** The threshold that applied to this tool (the global one unless the tool's policy changes it). */
     threshold: number;
     /** Indexes (0-based) of the steps that contain the run; at most the last 10. */
     stepIndexes: number[];
-    /** True when the rule was configured to require identical results too. */
+    /** True when identical results were required too (the global option, or a `polling` tool). */
     identicalResults: boolean;
 }
 interface OscillationEvidence {
@@ -70,6 +78,8 @@ interface OscillationEvidence {
     threshold: number;
     /** One cycle, as `tool(args)` labels. */
     cycle: string[];
+    /** The tool name of each call in the cycle (no arguments), in the same order as `cycle`. */
+    tools: string[];
 }
 interface NoProgressEvidence {
     /** Consecutive stalled steps with identical text. */
@@ -101,10 +111,18 @@ interface StopBase<R extends StopReason, C extends string, E> {
     detail: string;
     /** Structured, JSON-serialisable facts behind the decision. */
     evidence: E;
+    /**
+     * Plain-English text meant to be pasted into the model's next turn or tool result, present on
+     * every stop that is a fault (see `isFault`). It names the tool but never repeats arguments or
+     * results, so it is safe to send to the model. Absent on a normal `stop` finish and, for a
+     * `custom` stop, unless the detector (or `options.feedback`) supplies it. See `feedbackFor`.
+     */
+    feedback?: string;
     /** Non-fatal warnings raised in the same step, if any. */
     warnings?: GuardWarning[];
 }
 type MaxStepsVerdict = StopBase<'max-steps', 'MAX_STEPS', MaxStepsEvidence>;
+type ToolLimitVerdict = StopBase<'tool-limit', 'TOOL_CALL_CAP', ToolLimitEvidence>;
 type RepeatedToolCallVerdict = StopBase<'repeated-tool-call', 'REPEATED_TOOL_CALL', RepeatedToolCallEvidence>;
 type OscillationVerdict = StopBase<'oscillation', 'OSCILLATION', OscillationEvidence>;
 type NoProgressVerdict = StopBase<'no-progress', 'NO_PROGRESS', NoProgressEvidence>;
@@ -112,7 +130,7 @@ type FinishReasonVerdict = StopBase<'finish-reason', 'FINISH_TERMINAL' | 'FINISH
 type BudgetVerdict = StopBase<'budget', 'BUDGET_TOTAL_TOKENS' | 'BUDGET_INPUT_TOKENS' | 'BUDGET_OUTPUT_TOKENS' | 'BUDGET_COST_USD' | 'BUDGET_DURATION_MS', BudgetEvidence>;
 /** Verdict produced by a user-supplied `custom` detector. */
 type CustomVerdict = StopBase<'custom', string, unknown>;
-type StopVerdict = MaxStepsVerdict | RepeatedToolCallVerdict | OscillationVerdict | NoProgressVerdict | FinishReasonVerdict | BudgetVerdict | CustomVerdict;
+type StopVerdict = MaxStepsVerdict | ToolLimitVerdict | RepeatedToolCallVerdict | OscillationVerdict | NoProgressVerdict | FinishReasonVerdict | BudgetVerdict | CustomVerdict;
 interface GuardWarning {
     code: 'BUDGET_WARNING';
     metric: BudgetMetric;
@@ -182,6 +200,8 @@ interface CustomStop {
     detail?: string;
     /** Anything JSON-serialisable that explains the decision. */
     evidence?: unknown;
+    /** Text for the model, becomes `verdict.feedback`. Default: none. Must not contain secrets. */
+    feedback?: string;
 }
 /**
  * User-supplied detector. Receives the full history (including `step`, last) and may return a
@@ -191,6 +211,35 @@ interface CustomStop {
 type CustomDetector = (history: readonly GuardStep[], step: GuardStep) => CustomStop | {
     stop: false;
 } | undefined;
+/**
+ * Rules for one tool, keyed by tool name in `GuardOptions.tools`. Every field is optional. See the
+ * README ("Per-tool policies") for how they combine with the global detectors.
+ */
+interface ToolPolicy {
+    /**
+     * Identical arguments are legitimate for this tool as long as the results keep changing (a job
+     * status poll, a paginated read). The repeated-call rule then applies only when the results are
+     * identical too, after `maxIdenticalResults` identical outcomes in a row (default: the tool's
+     * `repeatThreshold`, else the global threshold). `true` is the same as `{}`.
+     */
+    polling?: boolean | {
+        maxIdenticalResults?: number;
+    };
+    /**
+     * At most this many calls to the tool in one run (integer >= 0; `0` forbids the tool). The call
+     * after the limit stops the run with `TOOL_CALL_CAP` (and `guard.preflight` denies it before it runs).
+     */
+    maxCalls?: number;
+    /** Stop after this many identical calls in a row to this tool. Integer >= 2. Overrides the global threshold. */
+    repeatThreshold?: number;
+    /**
+     * Leave the tool out of repeat, oscillation and no-progress detection and out of `maxCalls`
+     * (for bookkeeping tools such as `think` or `todo`). Takes precedence over the other fields.
+     */
+    ignore?: boolean;
+}
+/** Where a piece of feedback is going: after a step was recorded, or in place of a call that was not run. */
+type FeedbackPhase = 'check' | 'preflight';
 interface GuardOptions {
     /** Stop after this many steps. Integer >= 1. Default 50. `false` disables. */
     maxSteps?: number | false;
@@ -204,8 +253,18 @@ interface GuardOptions {
     finishReason?: FinishReasonOptions | false;
     /** Default: no limits. */
     budget?: BudgetOptions | false;
+    /** Per-tool rules by tool name; tools that are not listed follow the global options. */
+    tools?: Readonly<Record<string, ToolPolicy>>;
     /** Extra detectors, run after the built-in ones. */
     custom?: CustomDetector | readonly CustomDetector[];
+    /**
+     * Replace the model-facing text of a fault verdict (and of a `preflight` denial). Return a string
+     * to use it, or `undefined` to keep the default (`feedbackFor`). Errors it throws propagate out of
+     * `guard.check` / `guard.preflight`. The text is yours to keep free of secrets.
+     */
+    feedback?: (verdict: StopVerdict, info: {
+        phase: FeedbackPhase;
+    }) => string | undefined;
     /** Clock used for wall-clock duration budgets. Default `Date.now`. */
     now?: () => number;
 }
@@ -229,6 +288,7 @@ interface GuardSummary {
             remaining: number;
         } | null;
         repeatedToolCall: {
+            /** The global threshold; tools with their own `repeatThreshold` or `polling` policy can differ. */
             threshold: number;
             currentRun: {
                 tool: string;
@@ -255,18 +315,175 @@ interface GuardSummary {
             limits: Partial<Record<BudgetMetric, number>>;
             used: Record<BudgetMetric, number>;
         } | null;
+        /** Calls so far against each tool's `maxCalls`. Present only when at least one tool has a cap. */
+        toolLimits?: Array<{
+            tool: string;
+            limit: number;
+            calls: number;
+        }>;
     };
     /** The verdict returned by the most recent `check`, or `null` before the first one. */
     lastVerdict: Verdict | null;
 }
+/** A tool call that has not run yet: all `preflight` needs is the name and the arguments. */
+interface PreflightCall {
+    name: string;
+    args?: unknown;
+}
+/** The call may go ahead (as far as the rules `preflight` can evaluate are concerned). */
+interface PreflightAllow {
+    allow: true;
+    /** Budget warnings that apply right now, if any. */
+    warnings?: GuardWarning[];
+}
+interface DenyBase<R extends StopReason, C extends string, E> {
+    allow: false;
+    /** Same vocabulary as `StopVerdict.reason`. */
+    reason: R;
+    /** Same vocabulary as `StopVerdict.code`. */
+    code: C;
+    /** One developer-facing sentence. May contain argument previews, like `StopVerdict.detail`. */
+    detail: string;
+    /** Structured, JSON-serialisable facts behind the decision. */
+    evidence: E;
+    /** Text to give the model in place of the tool's result. Never repeats arguments or results. */
+    feedback: string;
+}
+/**
+ * The call should not run. Only the rules that can be judged before a call runs appear here:
+ * `max-steps`, `budget`, `tool-limit`, `repeated-tool-call` and `oscillation`.
+ */
+type PreflightDeny = DenyBase<'max-steps', 'MAX_STEPS', MaxStepsEvidence> | DenyBase<'budget', BudgetVerdict['code'], BudgetEvidence> | DenyBase<'tool-limit', 'TOOL_CALL_CAP', ToolLimitEvidence> | DenyBase<'repeated-tool-call', 'REPEATED_TOOL_CALL', RepeatedToolCallEvidence> | DenyBase<'oscillation', 'OSCILLATION', OscillationEvidence>;
+type Preflight = PreflightAllow | PreflightDeny;
+/** The stop verdicts a `preflight` denial is made from. */
+type PreflightStopVerdict = MaxStepsVerdict | BudgetVerdict | ToolLimitVerdict | RepeatedToolCallVerdict | OscillationVerdict;
+/** The current snapshot format. A guard only reads snapshots of the version it knows. */
+type GuardSnapshotVersion = 1;
+/**
+ * One short fingerprint per group of options, so a snapshot can tell whether it is being restored
+ * under the options it was taken with. The options themselves are not stored.
+ */
+interface GuardOptionsFingerprint {
+    maxSteps: string;
+    repeatedToolCall: string;
+    oscillation: string;
+    noProgress: string;
+    finishReason: string;
+    budget: string;
+    tools: string;
+    /** Covers the number of custom detectors, not what they do. */
+    custom: string;
+}
+/** The run of identical calls that `repeatedToolCall` is currently counting. */
+interface RepeatedToolCallSnapshot {
+    /** Hash identifying the repeated call (or call and result); `null` when there is no run. */
+    key: string | null;
+    tool: string;
+    /** Truncated canonical arguments (at most 80 characters), kept so evidence reads the same after a restore. */
+    preview: string;
+    length: number;
+    /** Indexes of the newest steps in the run (at most 10). */
+    steps: number[];
+    longest: number;
+}
+/** The newest calls the oscillation rule compares against, as hashes plus short labels. */
+interface OscillationSnapshot {
+    sigs: string[];
+    /** `tool(argument preview)` for each call in `sigs`. */
+    labels: string[];
+    /** Tool name of each call in `sigs`. */
+    names: string[];
+    matches: number[];
+    current: {
+        period: number;
+        repeats: number;
+    } | null;
+}
+interface NoProgressSnapshot {
+    /** Hashes of the most recent distinct tool outcomes, oldest first. */
+    seen: string[];
+    streak: number;
+    /** Hash of the text the current streak shares; `null` when there is no streak. */
+    textKey: string | null;
+    /** Truncated text of the streak (at most 80 characters). */
+    textPreview: string;
+}
+/**
+ * Everything a guard needs to carry on a run in another process, as plain JSON-safe data.
+ *
+ * Contains: counters, running totals, elapsed wall-clock time (only when a duration budget exists),
+ * hashes of recent tool calls and outcomes, tool names, and a few truncated previews (at most 80
+ * characters each) of recent arguments and text, so that evidence and messages read the same after a
+ * restore. Does not contain: raw arguments, results, errors, model text, the step history, the
+ * options, or the last verdict. `snapshot({ redact: true })` also replaces the previews.
+ * Hashes are not cryptographic: a short, guessable value could be recovered by trying candidates.
+ */
+interface GuardSnapshot {
+    version: GuardSnapshotVersion;
+    steps: number;
+    toolCalls: number;
+    failedToolCalls: number;
+    totals: GuardTotals;
+    /** Milliseconds of wall-clock time elapsed when the snapshot was taken; `null` without a duration budget. */
+    wallClockMs: number | null;
+    options: GuardOptionsFingerprint;
+    /** `null` for a detector that is disabled. */
+    detectors: {
+        repeatedToolCall: RepeatedToolCallSnapshot | null;
+        oscillation: OscillationSnapshot | null;
+        noProgress: NoProgressSnapshot | null;
+        finishReason: {
+            lastFinishReason: string | null;
+        } | null;
+        /** Calls so far for each tool with a `maxCalls`, in configuration order; `null` when no tool has one. */
+        toolLimits: Array<{
+            tool: string;
+            calls: number;
+        }> | null;
+    };
+}
+interface SnapshotOptions {
+    /**
+     * Replace the argument and text previews in the snapshot with `[redacted]`. Stop decisions stay
+     * identical after a restore, but evidence and messages that quote those previews will say
+     * `[redacted]` for calls made before the snapshot. Default `false`.
+     */
+    redact?: boolean;
+}
+interface RestoreOptions {
+    /**
+     * Allow `maxSteps` and `budget` to differ from the options the snapshot was taken with, for
+     * example to give a run that hit its limit more room. Every other option must still match.
+     * Default `false`.
+     */
+    allowLimitChanges?: boolean;
+}
 interface Guard {
     /** Record a step and decide whether the run should continue. Never throws on odd step data. */
     check(step: GuardStep): Verdict;
+    /**
+     * Would this call (or these parallel calls) trip a rule if it ran now? Records nothing and does
+     * not change the guard: call it as often as you like, then still `check` the finished step.
+     * Evaluates only the rules that need no results, text, finish reason or usage; see the README
+     * ("Preflight") for the exact list. Never throws on odd call data.
+     */
+    preflight(call: PreflightCall | readonly PreflightCall[]): Preflight;
     /** Forget everything and start a fresh run (options are kept). */
     reset(): void;
+    /**
+     * Plain, JSON-safe state for carrying the run into another process; restore it with
+     * `createGuard.fromJSON`. Does not change the guard. Because it is called `toJSON`,
+     * `JSON.stringify(guard)` gives the same data. See `GuardSnapshot` for what it holds.
+     */
+    toJSON(): GuardSnapshot;
+    /** Same as `toJSON`, with options. */
+    snapshot(options?: SnapshotOptions): GuardSnapshot;
     /** Counts, totals and per-detector state. Contains nothing time-dependent. */
     summary(): GuardSummary;
-    /** Frozen shallow copy of the steps recorded so far. */
+    /**
+     * Frozen shallow copy of the steps recorded so far by this guard object. A guard restored from a
+     * snapshot starts with an empty history: the raw steps are not part of a snapshot.
+     */
     readonly history: readonly GuardStep[];
 }
 
@@ -276,19 +493,52 @@ declare const DEFAULT_MAX_STEPS = 50;
  * Create a guard. Feed it one step at a time with `check`; it answers `{ stop: false }` or a
  * typed verdict saying why the run should end.
  *
- * Detectors run in this order and the first stop wins: finish reason, budget, max steps,
- * repeated tool call, oscillation, no progress, then custom detectors. All of them see every step
- * even after one has stopped, so their state stays consistent.
+ * Detectors run in this order and the first stop wins: finish reason, budget, max steps, tool
+ * limit, repeated tool call, oscillation, no progress, then custom detectors. All of them see
+ * every step even after one has stopped, so their state stays consistent.
+ *
+ * Tools with `ignore: true` in `options.tools` are removed from the calls the tool-limit,
+ * repeated-call, oscillation and no-progress detectors see.
  *
  * Invalid options throw a `TypeError` here, never later from `check`.
+ *
+ * `createGuard.fromJSON(snapshot, options)` (also exported as `restoreGuard`) continues a run from
+ * `guard.toJSON()`.
  */
 declare function createGuard(options?: GuardOptions): Guard;
+declare namespace createGuard {
+    var fromJSON: typeof restoreGuard;
+}
+/**
+ * Rebuild a guard from a snapshot (`guard.toJSON()`), so that it goes on exactly where the original
+ * stopped: given the same steps, it gives the same verdicts.
+ *
+ * Pass the same `options` the snapshot was taken with. They are not stored (functions cannot
+ * be), only fingerprinted, so a mismatch throws a `TypeError` naming the option groups that differ
+ * instead of silently behaving differently. `restoreOptions.allowLimitChanges` relaxes that for
+ * `maxSteps` and `budget` only. `now`, `feedback` and the code of custom detectors are not checked.
+ *
+ * Anything wrong with the snapshot (unknown version, wrong shape, hostile values) throws a
+ * `TypeError` here, never later from `check`. `snapshot` may be the result of `JSON.parse`.
+ */
+declare function restoreGuard(snapshot: unknown, options?: GuardOptions, restoreOptions?: RestoreOptions): Guard;
 
 /** True for a stop verdict that is not just the model finishing normally (`finishReason: 'stop'`). */
 declare function isFault(verdict: Verdict): verdict is StopVerdict;
 /** Turn a verdict into readable text for logs and error messages. Never throws. */
 declare function explain(verdict: Verdict): string;
 
+/**
+ * The default model-facing text for a stop verdict, or `undefined` when there is none: a normal
+ * `stop` finish (not a fault), and a `custom` verdict that did not bring its own `feedback`.
+ *
+ * `phase` is `'check'` (the default) for a verdict returned by `guard.check`, where the step has
+ * already happened, and `'preflight'` for a call that `guard.preflight` refused to let run. The
+ * text is deterministic: the same verdict always produces the same string.
+ */
+declare function feedbackFor(verdict: PreflightStopVerdict, phase?: FeedbackPhase): string;
+declare function feedbackFor(verdict: StopVerdict, phase?: FeedbackPhase): string | undefined;
+
 /**
  * Canonicalisation: turn any JavaScript value into a deterministic string so that two
  * "equal" tool-call arguments compare equal regardless of key order, and so that nothing
@@ -438,4 +688,4 @@ interface GuardedSteps<S extends GuardStep> extends AsyncIterable<S> {
  */
 declare function withGuard<S extends GuardStep>(source: AsyncIterable<S> | Iterable<S>, guard: Guard): GuardedSteps<S>;
 
-export { type AbortSignalLike, type AiSdkStepLike, type AiSdkToolCallLike, type AiSdkToolResultLike, type BudgetEvidence, type BudgetLimit, type BudgetMetric, type BudgetOptions, type BudgetVerdict, type BuiltinStopCode, type ContinueVerdict, type CustomDetector, type CustomStop, type CustomVerdict, DEFAULT_MAX_STEPS, type FinishReasonEvidence, type FinishReasonOptions, type FinishReasonVerdict, type Guard, type GuardOptions, type GuardStep, type GuardSummary, type GuardToolCall, type GuardTotals, type GuardUsage, type GuardWarning, type GuardedSteps, type LoopResult, type LoopStep, type MaxStepsEvidence, type MaxStepsVerdict, type NoProgressEvidence, type NoProgressOptions, type NoProgressVerdict, type OscillationEvidence, type OscillationOptions, type OscillationVerdict, type OtherFinishPolicy, type RepeatedToolCallEvidence, type RepeatedToolCallOptions, type RepeatedToolCallVerdict, type RunAgentLoopOptions, type StopReason, type StopVerdict, type ToStopWhenOptions, type Verdict, canonicalize, createGuard, explain, isFault, runAgentLoop, stableHash, toGuardStep, toStopWhen, withGuard };
+export { type AbortSignalLike, type AiSdkStepLike, type AiSdkToolCallLike, type AiSdkToolResultLike, type BudgetEvidence, type BudgetLimit, type BudgetMetric, type BudgetOptions, type BudgetVerdict, type BuiltinStopCode, type ContinueVerdict, type CustomDetector, type CustomStop, type CustomVerdict, DEFAULT_MAX_STEPS, type FeedbackPhase, type FinishReasonEvidence, type FinishReasonOptions, type FinishReasonVerdict, type Guard, type GuardOptions, type GuardOptionsFingerprint, type GuardSnapshot, type GuardSnapshotVersion, type GuardStep, type GuardSummary, type GuardToolCall, type GuardTotals, type GuardUsage, type GuardWarning, type GuardedSteps, type LoopResult, type LoopStep, type MaxStepsEvidence, type MaxStepsVerdict, type NoProgressEvidence, type NoProgressOptions, type NoProgressSnapshot, type NoProgressVerdict, type OscillationEvidence, type OscillationOptions, type OscillationSnapshot, type OscillationVerdict, type OtherFinishPolicy, type Preflight, type PreflightAllow, type PreflightCall, type PreflightDeny, type PreflightStopVerdict, type RepeatedToolCallEvidence, type RepeatedToolCallOptions, type RepeatedToolCallSnapshot, type RepeatedToolCallVerdict, type RestoreOptions, type RunAgentLoopOptions, type SnapshotOptions, type StopReason, type StopVerdict, type ToStopWhenOptions, type ToolLimitEvidence, type ToolLimitVerdict, type ToolPolicy, type Verdict, canonicalize, createGuard, explain, feedbackFor, isFault, restoreGuard, runAgentLoop, stableHash, toGuardStep, toStopWhen, withGuard };