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

package/dist/index.d.ts

@@ -0,0 +1,441 @@
+/**
+ * Public types for agent-loopguard.
+ *
+ * Everything here is plain data: steps go in, serialisable verdicts come out.
+ */
+/** One tool invocation made during a step. */
+interface GuardToolCall {
+    /** Tool name as the model called it. */
+    name: string;
+    /** Arguments the model supplied. Any JSON-ish (or not-so-JSON-ish) value. */
+    args?: unknown;
+    /** Value the tool returned, if you have it. Used by result-aware rules. */
+    result?: unknown;
+    /** Error the tool raised, if any. A non-null `error` marks the call as failed. */
+    error?: unknown;
+}
+/** Token and cost numbers for one step. All supplied by the caller; nothing is estimated. */
+interface GuardUsage {
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    totalTokens?: number | undefined;
+    /** Cost in USD as computed by the caller. The package contains no price table. */
+    costUsd?: number | undefined;
+}
+/**
+ * One model step: what the model produced and what happened as a result.
+ * Every field is optional; supply what you have.
+ */
+interface GuardStep {
+    toolCalls?: readonly GuardToolCall[] | undefined;
+    /** Assistant text produced in this step. */
+    text?: string | undefined;
+    /**
+     * Why the model stopped generating. Provider-agnostic: `'stop' | 'length' | 'tool-calls' |
+     * 'content-filter' | 'error' | 'other' | 'unknown'` or any other string. Compared after
+     * lower-casing and turning `_` into `-`.
+     */
+    finishReason?: string | undefined;
+    usage?: GuardUsage | undefined;
+    /** How long the step took, in milliseconds. Summed by the `maxDurationMs` budget. */
+    durationMs?: number | undefined;
+    /** 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 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';
+interface MaxStepsEvidence {
+    steps: number;
+    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;
+    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. */
+    identicalResults: boolean;
+}
+interface OscillationEvidence {
+    /** Number of tool calls in one cycle. */
+    period: number;
+    /** How many consecutive times the cycle was observed. */
+    repeats: number;
+    threshold: number;
+    /** One cycle, as `tool(args)` labels. */
+    cycle: string[];
+}
+interface NoProgressEvidence {
+    /** Consecutive stalled steps with identical text. */
+    steps: number;
+    threshold: number;
+    /** The repeated text (normalised), truncated for display. */
+    textPreview: string;
+}
+interface FinishReasonEvidence {
+    /** The finish reason exactly as supplied. */
+    finishReason: string;
+    /** Lower-cased, `_` replaced by `-`. */
+    normalized: string;
+    policy: 'terminal' | 'other-stop' | 'other-text-only';
+    hasText: boolean;
+    toolCallCount: number;
+}
+interface BudgetEvidence {
+    metric: BudgetMetric;
+    value: number;
+    limit: number;
+}
+interface StopBase<R extends StopReason, C extends string, E> {
+    stop: true;
+    reason: R;
+    /** Stable machine-readable code. */
+    code: C;
+    /** One human-readable sentence. */
+    detail: string;
+    /** Structured, JSON-serialisable facts behind the decision. */
+    evidence: E;
+    /** Non-fatal warnings raised in the same step, if any. */
+    warnings?: GuardWarning[];
+}
+type MaxStepsVerdict = StopBase<'max-steps', 'MAX_STEPS', MaxStepsEvidence>;
+type RepeatedToolCallVerdict = StopBase<'repeated-tool-call', 'REPEATED_TOOL_CALL', RepeatedToolCallEvidence>;
+type OscillationVerdict = StopBase<'oscillation', 'OSCILLATION', OscillationEvidence>;
+type NoProgressVerdict = StopBase<'no-progress', 'NO_PROGRESS', NoProgressEvidence>;
+type FinishReasonVerdict = StopBase<'finish-reason', 'FINISH_TERMINAL' | 'FINISH_OTHER' | 'FINISH_OTHER_TEXT_ONLY', FinishReasonEvidence>;
+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;
+interface GuardWarning {
+    code: 'BUDGET_WARNING';
+    metric: BudgetMetric;
+    value: number;
+    limit: number;
+    /** `value / limit`. */
+    ratio: number;
+    detail: string;
+}
+interface ContinueVerdict {
+    stop: false;
+    /** Present only when at least one warning is active. */
+    warnings?: GuardWarning[];
+}
+type Verdict = ContinueVerdict | StopVerdict;
+interface RepeatedToolCallOptions {
+    /** Stop when the same call occurs this many times in a row. Integer >= 2. Default 3. */
+    threshold?: number;
+    /**
+     * Count a repeat only when the call also returned an identical result (calls without a result
+     * compare equal). Use for polling-style tools. Default false.
+     */
+    requireIdenticalResults?: boolean;
+    /** Drop failed calls (non-null `error`) from the sequence before counting. Default false. */
+    ignoreErrors?: boolean;
+}
+interface OscillationOptions {
+    /** Longest cycle to look for (cycles of length 2..maxPeriod). Integer >= 2. Default 3. */
+    maxPeriod?: number;
+    /** Stop when a cycle was seen this many times in a row. Integer >= 2. Default 3. */
+    repeats?: number;
+}
+interface NoProgressOptions {
+    /** Consecutive stalled steps with identical text. Integer >= 2. Default 3. */
+    threshold?: number;
+}
+type OtherFinishPolicy = 'stop' | 'continue' | 'stop-if-text-only';
+interface FinishReasonOptions {
+    /** Finish reasons that end the run. Default `['stop', 'length', 'content-filter', 'error']`. */
+    terminal?: readonly string[];
+    /**
+     * What to do with a finish reason that is neither terminal nor `tool-calls` (`other`, `unknown`,
+     * or anything unfamiliar). Default `'stop-if-text-only'`.
+     */
+    otherPolicy?: OtherFinishPolicy;
+}
+/** A limit, optionally with a warning threshold. */
+type BudgetLimit = number | {
+    limit: number;
+    warnAt?: number;
+};
+interface BudgetOptions {
+    maxTotalTokens?: BudgetLimit;
+    maxInputTokens?: BudgetLimit;
+    maxOutputTokens?: BudgetLimit;
+    maxCostUsd?: BudgetLimit;
+    maxDurationMs?: BudgetLimit;
+    /** Default warning ratio (0 < r < 1) for limits that do not set their own `warnAt`. */
+    warnAt?: number;
+}
+/** What a custom detector returns to stop the run. */
+interface CustomStop {
+    stop: true;
+    /** Stable machine-readable code of your own. Default `'CUSTOM'`. */
+    code?: string;
+    /** One human-readable sentence. */
+    detail?: string;
+    /** Anything JSON-serialisable that explains the decision. */
+    evidence?: unknown;
+}
+/**
+ * User-supplied detector. Receives the full history (including `step`, last) and may return a
+ * stop verdict. Return `undefined` (or `{ stop: false }`) to let the run continue. Errors it
+ * throws propagate out of `guard.check`.
+ */
+type CustomDetector = (history: readonly GuardStep[], step: GuardStep) => CustomStop | {
+    stop: false;
+} | undefined;
+interface GuardOptions {
+    /** Stop after this many steps. Integer >= 1. Default 50. `false` disables. */
+    maxSteps?: number | false;
+    /** Default: enabled with default options. `false` disables. */
+    repeatedToolCall?: RepeatedToolCallOptions | false;
+    /** Default: enabled with default options. `false` disables. */
+    oscillation?: OscillationOptions | false;
+    /** Default: enabled with default options. `false` disables. */
+    noProgress?: NoProgressOptions | false;
+    /** Default: enabled with default options. `false` disables. */
+    finishReason?: FinishReasonOptions | false;
+    /** Default: no limits. */
+    budget?: BudgetOptions | false;
+    /** Extra detectors, run after the built-in ones. */
+    custom?: CustomDetector | readonly CustomDetector[];
+    /** Clock used for wall-clock duration budgets. Default `Date.now`. */
+    now?: () => number;
+}
+interface GuardTotals {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    /** Sum of the `durationMs` values supplied on steps. */
+    durationMs: number;
+}
+interface GuardSummary {
+    steps: number;
+    toolCalls: number;
+    failedToolCalls: number;
+    totals: GuardTotals;
+    /** `null` for a detector that is disabled. */
+    detectors: {
+        maxSteps: {
+            limit: number;
+            remaining: number;
+        } | null;
+        repeatedToolCall: {
+            threshold: number;
+            currentRun: {
+                tool: string;
+                length: number;
+            } | null;
+            longestRun: number;
+        } | null;
+        oscillation: {
+            maxPeriod: number;
+            repeats: number;
+            current: {
+                period: number;
+                repeats: number;
+            } | null;
+        } | null;
+        noProgress: {
+            threshold: number;
+            streak: number;
+        } | null;
+        finishReason: {
+            lastFinishReason: string | null;
+        } | null;
+        budget: {
+            limits: Partial<Record<BudgetMetric, number>>;
+            used: Record<BudgetMetric, number>;
+        } | null;
+    };
+    /** The verdict returned by the most recent `check`, or `null` before the first one. */
+    lastVerdict: Verdict | null;
+}
+interface Guard {
+    /** Record a step and decide whether the run should continue. Never throws on odd step data. */
+    check(step: GuardStep): Verdict;
+    /** Forget everything and start a fresh run (options are kept). */
+    reset(): void;
+    /** Counts, totals and per-detector state. Contains nothing time-dependent. */
+    summary(): GuardSummary;
+    /** Frozen shallow copy of the steps recorded so far. */
+    readonly history: readonly GuardStep[];
+}
+
+/** Default for `maxSteps`: a backstop, not a tuned value. Raise it for long-running agents. */
+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.
+ *
+ * Invalid options throw a `TypeError` here, never later from `check`.
+ */
+declare function createGuard(options?: GuardOptions): 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;
+
+/**
+ * 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
+ * a model can send (NaN, bigint, circular objects, Maps...) can make the guard throw.
+ *
+ * This is NOT JSON. JSON loses too much (undefined, NaN, bigint, Map, Set, Date vs string,
+ * cycles). The output is only meant for equality checks and short human previews.
+ */
+/**
+ * Deterministic, key-order-insensitive string form of `value`. Never throws.
+ *
+ * Rules:
+ * - Object keys are sorted; properties whose value is `undefined` are omitted (like JSON).
+ * - Array items keep their order; `undefined` items are kept.
+ * - `NaN`, `Infinity`, `-Infinity` and bigint (`10n`) are distinct from strings and numbers
+ *   that print the same; `-0` is normalised to `0`.
+ * - Dates are written as ISO strings (or `invalid`); Maps and Sets are sorted by the canonical
+ *   form of their entries, so insertion order does not matter.
+ * - A reference back to an ancestor is written `[Circular:<depth of that ancestor>]`.
+ * - Objects with a `toJSON` method are written as the result of calling it.
+ * - If something throws while reading the value (hostile getters, revoked proxies) the result is
+ *   a unique placeholder, so such values are never considered equal to anything.
+ */
+declare function canonicalize(value: unknown): string;
+/**
+ * Stable, non-cryptographic hash of any value: two independent 53-bit hashes of its canonical
+ * form (28 hex characters). Equal values always hash equally; a collision between different values
+ * is possible in principle but not a practical concern for loop detection. Do not use it for
+ * anything security-related.
+ */
+declare function stableHash(value: unknown): string;
+
+interface AiSdkToolCallLike {
+    readonly toolCallId?: string | undefined;
+    readonly toolName: string;
+    readonly input?: unknown;
+    readonly args?: unknown;
+}
+interface AiSdkToolResultLike {
+    readonly toolCallId?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly output?: unknown;
+    readonly result?: unknown;
+}
+interface AiSdkStepLike {
+    readonly text?: string | undefined;
+    readonly finishReason?: string | undefined;
+    readonly toolCalls?: ReadonlyArray<AiSdkToolCallLike> | undefined;
+    readonly toolResults?: ReadonlyArray<AiSdkToolResultLike> | undefined;
+    /** Scanned for `{ type: 'tool-error', toolCallId, error }` parts. */
+    readonly content?: ReadonlyArray<{
+        readonly type: string;
+    }> | undefined;
+    readonly usage?: {
+        readonly inputTokens?: number | undefined;
+        readonly outputTokens?: number | undefined;
+        readonly totalTokens?: number | undefined;
+    } | undefined;
+    readonly performance?: {
+        readonly stepTimeMs?: number | undefined;
+    } | undefined;
+}
+/** Map one AI SDK step to a `GuardStep`. Tool results and errors are matched to calls by `toolCallId`. */
+declare function toGuardStep(step: AiSdkStepLike): GuardStep;
+interface ToStopWhenOptions {
+    /** Called when the guard decides to stop, so you can log or record why. May be called more than once for the same stop. */
+    onStop?: (verdict: StopVerdict) => void;
+}
+/**
+ * Build an AI SDK `stopWhen` condition from a guard.
+ *
+ * ```ts
+ * generateText({ model, tools, stopWhen: toStopWhen(() => createGuard()) });
+ * ```
+ *
+ * The condition is idempotent: on every call it creates a fresh guard from `guardFactory` and
+ * replays the whole `steps` array, so it gives the same answer for the same steps however often
+ * the SDK calls it, and it holds no state between calls or runs. Only the verdict for the latest
+ * step counts. Wall-clock budgets are meaningless in a replay, so use durations from the steps
+ * (`performance.stepTimeMs`, summed) rather than a `now()`-based limit here.
+ *
+ * You may pass `GuardOptions` instead of a factory.
+ */
+declare function toStopWhen<S extends AiSdkStepLike = AiSdkStepLike>(guardFactory?: (() => Guard) | GuardOptions, hooks?: ToStopWhenOptions): (options: {
+    steps: ReadonlyArray<S>;
+}) => boolean;
+
+/** The one thing we need from an `AbortSignal`; keeps the package free of DOM/Node type deps. */
+interface AbortSignalLike {
+    readonly aborted: boolean;
+}
+/** A step as returned by your `step` function: a `GuardStep` plus an optional end-of-run flag. */
+interface LoopStep extends GuardStep {
+    /**
+     * `true` when the agent has finished. `false` forces the loop to continue. When omitted, a step
+     * with no tool calls counts as final (there is nothing left to execute).
+     */
+    done?: boolean | undefined;
+}
+interface RunAgentLoopOptions<S extends LoopStep> {
+    /** Perform step `index` (call the model, run its tools) and describe what happened. */
+    step: (index: number) => S | Promise<S>;
+    /** Defaults to `createGuard()`. */
+    guard?: Guard;
+    /** Checked before every step and after a step that throws; an in-flight step is not cancelled. */
+    signal?: AbortSignalLike;
+    /** Called after every step with that step's verdict, including non-stopping ones with warnings. */
+    onVerdict?: (verdict: Verdict, step: S, index: number) => void;
+}
+interface LoopResult<S extends LoopStep> {
+    /** Every step that ran, in order. */
+    steps: S[];
+    /** The last verdict: the stop verdict that ended the loop, or `{ stop: false }`. */
+    verdict: Verdict;
+    /**
+     * True when the agent ended the run itself: the step was final and no fault was raised, or the
+     * finish reason was a normal `stop`. False when the guard cut it short, the finish reason
+     * was something like `length` or `error`, or the signal aborted.
+     */
+    completed: boolean;
+    /** True when the loop ended because the signal was aborted. */
+    aborted: boolean;
+}
+/**
+ * A tiny agent loop: call `step(0)`, `step(1)`, ... until the agent is done or the guard says stop.
+ * Throws whatever `step` throws (unless the signal was aborted, in which case it returns).
+ *
+ * If you disable `maxSteps` and your `step` never finishes, this loop never ends; that is on you.
+ */
+declare function runAgentLoop<S extends LoopStep>(options: RunAgentLoopOptions<S>): Promise<LoopResult<S>>;
+
+/** An async iterable of steps that ends itself when the guard says stop. */
+interface GuardedSteps<S extends GuardStep> extends AsyncIterable<S> {
+    /** The verdict for the most recent step yielded, or `undefined` before the first one. */
+    readonly verdict: Verdict | undefined;
+}
+/**
+ * Wrap a (sync or async) iterable of steps. Each step is passed to `guard.check` and then yielded
+ * to you; if the verdict says stop, the step that triggered it is still yielded (it already
+ * happened) and iteration ends right after, closing the source. Read `.verdict` afterwards to find out why:
+ *
+ * ```ts
+ * const steps = withGuard(agentSteps(), guard);
+ * for await (const step of steps) render(step);
+ * if (steps.verdict?.stop) console.log(explain(steps.verdict));
+ * ```
+ */
+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 };