agentfootprint 2.10.2 → 2.11.1

package/dist/types/reliability/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Reliability — public types for the v2.11.1 rules-based reliability subsystem.
+ *
+ * Mental model: reliability is a SUBFLOW PATTERN expressed as `decide()`
+ * rules at PRE-call and POST-call boundaries around the LLM invocation.
+ * Each rule is `{when, then, kind, label?}`. The gate stage evaluates
+ * rules in order; the first match drives behaviour. Three channels carry
+ * the outcome:
+ *
+ *  • SCOPE STATE   — runtime data (`failKind`, `failPayload`) read by
+ *    `Agent.run()` at the API boundary to construct `ReliabilityFailFastError`.
+ *  • $emit         — passive observability for external consumers
+ *    (CloudWatch, X-Ray, OTel). NOT read by runtime logic.
+ *  • $break(reason)— control flow + human-readable narrative reason.
+ *
+ * See `buildReliabilityGate.ts` for the gate stage that consumes these
+ * types and `Agent.create().reliability()` for the consumer-facing API.
+ */
+import type { LLMProvider, LLMRequest, LLMResponse } from '../adapters/types.js';
+/**
+ * The set of verbs a `ReliabilityRule.then` can specify.
+ *
+ *   • `continue`    — pre-check only; no issues, proceed to the LLM call.
+ *   • `ok`          — post-decide only; call succeeded, exit the gate
+ *                     loop and let the agent's next stage run.
+ *   • `retry`       — post-decide only; bump attempt counter and re-run
+ *                     the same provider via the gate's `loopTo`.
+ *   • `retry-other` — post-decide only; advance `providerIdx` to the
+ *                     next provider in the failover list, then loop.
+ *   • `fallback`    — post-decide only; invoke the configured
+ *                     `fallback(req, lastError)` to repair the response;
+ *                     exit on success.
+ *   • `fail-fast`   — both phases; write `failKind`/`failPayload` to
+ *                     scope, $emit observability event, $break(reason).
+ *                     `Agent.run()` translates the propagated break into
+ *                     a typed `ReliabilityFailFastError` at the API
+ *                     boundary.
+ */
+export type ReliabilityDecision = 'continue' | 'ok' | 'retry' | 'retry-other' | 'fallback' | 'fail-fast';
+/**
+ * A single reliability rule. Evaluated by `decide()` from the gate
+ * stage; first-match-wins. Function-form `when` predicates are the
+ * common case; the filter-DSL form supported by `decide()` also works
+ * if your rule reads scope keys with simple comparisons.
+ */
+export interface ReliabilityRule {
+    /**
+     * Predicate over the gate's scope. Return `true` to fire this rule.
+     * Pure function — no side effects, no async. The gate evaluates
+     * predicates in sequence and stops on the first match.
+     */
+    readonly when: (scope: ReliabilityScope) => boolean;
+    /** What to do when this rule matches. See `ReliabilityDecision`. */
+    readonly then: ReliabilityDecision;
+    /**
+     * Machine-readable label used to construct `ReliabilityFailFastError.kind`
+     * when `then === 'fail-fast'`. Also surfaces in narrative + emit payload.
+     * Must be a stable identifier — consumers branch on it programmatically.
+     * Example: `'cost-cap-exceeded'`, `'circuit-open-no-fallback'`,
+     * `'transient-5xx-retry'`.
+     */
+    readonly kind: string;
+    /**
+     * Human-readable narrative reason. Falls back to `kind` if omitted.
+     * Surfaces in `$break(reason)` and the auto-narrative.
+     */
+    readonly label?: string;
+}
+/**
+ * One entry in the optional provider failover list. The gate's
+ * `'retry-other'` decision advances through this array via `providerIdx`.
+ * If omitted, the gate operates against the agent's single configured
+ * provider with no failover.
+ */
+export interface ReliabilityProvider {
+    /** Display name — also the key used in `breakerStates` and
+     *  `attemptsPerProvider` maps. Convention: lowercase vendor name. */
+    readonly name: string;
+    /** The actual provider instance to call. */
+    readonly provider: LLMProvider;
+    /** The model identifier passed to `provider.complete({ model, ... })`. */
+    readonly model: string;
+}
+/**
+ * Per-provider circuit breaker tuning. State is per-instance (per pod);
+ * see CHANGELOG note in v2.11.1 about distributed state limitations.
+ */
+export interface CircuitBreakerConfig {
+    /** Consecutive failures before the breaker OPENS. Default 5. */
+    readonly failureThreshold?: number;
+    /** How long the breaker stays OPEN before probing. Default 30_000 ms. */
+    readonly cooldownMs?: number;
+    /** Probe successes required in HALF-OPEN to fully CLOSE. Default 2. */
+    readonly halfOpenSuccessThreshold?: number;
+    /**
+     * Predicate — does this error count toward the failure threshold?
+     * Default: everything except AbortError counts. Override to ignore
+     * 4xx so a malformed request doesn't trip the breaker for everyone.
+     */
+    readonly shouldCount?: (error: unknown) => boolean;
+}
+/**
+ * Consumer-supplied fallback that runs when a `'fallback'` rule fires.
+ * Receives the original request and the most recent error; returns a
+ * synthesized response that the gate writes back to scope. Throwing
+ * from the fallback re-enters the gate's post-decide rule set with
+ * the new error captured — typically the next rule routes to
+ * `'fail-fast'` (or a canned response if you've layered that pattern).
+ */
+export type ReliabilityFallbackFn = (request: LLMRequest, lastError: Error | undefined) => Promise<LLMResponse>;
+/**
+ * The full reliability configuration passed to
+ * `Agent.create({...}).reliability(config)`. All fields optional — the
+ * gate stage is mounted only if at least one of `preCheck`/`postDecide`
+ * has rules OR `circuitBreaker` is configured. Otherwise the agent
+ * chart collapses to a plain `CallLLM` stage with no reliability
+ * overhead.
+ */
+export interface ReliabilityConfig {
+    /** Rules evaluated BEFORE the LLM call. Common uses: cost-cap pre-check,
+     *  cumulative-budget gate, prompt-size guard. The gate routes on
+     *  `'continue'` (proceed to call) or `'fail-fast'` (skip call, $break). */
+    readonly preCheck?: readonly ReliabilityRule[];
+    /** Rules evaluated AFTER the LLM call returns or throws. The gate
+     *  routes on `'ok'` (success exit), `'retry'` (loop), `'retry-other'`
+     *  (advance provider, loop), `'fallback'` (invoke fallback fn, exit),
+     *  or `'fail-fast'` ($break with reason). */
+    readonly postDecide?: readonly ReliabilityRule[];
+    /** Optional ordered failover list. The first entry is the primary;
+     *  `'retry-other'` decisions walk through this array. If omitted,
+     *  reliability runs with no failover. */
+    readonly providers?: readonly ReliabilityProvider[];
+    /** Per-provider circuit-breaker config. Applied to every provider in
+     *  `providers[]` (or to the agent's single provider if no failover
+     *  list). Omit to disable circuit-breaking entirely. */
+    readonly circuitBreaker?: CircuitBreakerConfig;
+    /** Optional fallback function invoked on `'fallback'` decisions.
+     *  Typical use: reformat a malformed schema response, repair JSON,
+     *  or synthesize a safe default. Throwing re-enters the rule set. */
+    readonly fallback?: ReliabilityFallbackFn;
+}
+/**
+ * The scope that reliability rules read. Populated by the gate stage
+ * each iteration. Consumer rules `(s: ReliabilityScope) => boolean`
+ * close over this shape; do NOT cast to `any` — the typed scope is the
+ * stable contract between gate state and rule predicates.
+ *
+ * Mutable scalars (attempt, providerIdx, error, errorKind, latencyMs,
+ * response) are OVERWRITTEN each iteration. Loop history is preserved
+ * by footprintjs's commitLog (one CommitBundle per stage execution),
+ * so time-travel scrubbing shows each attempt's snapshot independently.
+ */
+export interface ReliabilityScope {
+    /** The LLM request being processed by this gate execution. */
+    readonly request: LLMRequest;
+    /** Number of providers in the failover list — derived from the
+     *  closure-held config; mirrored into scope so rules can compare
+     *  against `providerIdx`. (Provider OBJECTS live in the gate chart's
+     *  closure, not in scope, because functions can't structuredClone
+     *  across subflow boundaries.) */
+    readonly providersCount: number;
+    /** True if a `fallback` function is configured. Lets rules check
+     *  `s.hasFallback` to decide between `fallback` and `fail-fast`. */
+    readonly hasFallback: boolean;
+    /** 1-indexed attempt counter. Incremented after each LLM call,
+     *  whether it succeeded or threw. Rules typically check
+     *  `s.attempt < maxAttempts` before routing to `'retry'`. */
+    attempt: number;
+    /** Index into the gate's providers list (held in closure) for the
+     *  currently-selected provider. */
+    providerIdx: number;
+    /** Convenience: `providers[providerIdx].name`. Updated alongside
+     *  `providerIdx` on `'retry-other'`. */
+    currentProvider: string;
+    /** True if `providerIdx < providersCount - 1`. Lets rules check
+     *  `s.canSwitchProvider` before routing to `'retry-other'`. */
+    canSwitchProvider: boolean;
+    /** The LLM response from the most recent successful call.
+     *  `undefined` after a throw or before the first call completes. */
+    response?: LLMResponse;
+    /** The error from the most recent failed call. `undefined` after
+     *  a successful call. */
+    error?: Error;
+    /** Coarse classification of `error` for rule matching. See
+     *  `classifyError.ts` for the taxonomy. `'ok'` after success. */
+    errorKind: 'ok' | '5xx-transient' | 'rate-limit' | 'circuit-open' | 'schema-fail' | 'unknown';
+    /** Wall-clock latency of the most recent call attempt, in ms. */
+    latencyMs: number;
+    /** Per-provider attempt counts within this gate execution.
+     *  Rules use this for "max-attempts-per-provider" semantics. */
+    attemptsPerProvider: Record<string, number>;
+    /** Per-provider breaker state. Full state record (counters,
+     *  openedAt, lastErrorMessage) — NOT just the state enum — so the
+     *  state machine round-trips across gate invocations via
+     *  inputMapper/outputMapper. Rules typically check
+     *  `s.breakerStates[provider]?.state === 'open'`. */
+    breakerStates: Record<string, import('./CircuitBreaker.js').BreakerState>;
+    /** Cumulative cost across the whole agent run, set by the agent
+     *  via `inputMapper`. `undefined` if cost tracking is off.
+     *  Kept here for `preCheck` rules like
+     *  `s.cumulativeCostUsd >= s.costCapUsd → fail-fast`. */
+    cumulativeCostUsd?: number;
+    /** Cumulative input/output tokens, mirrored from agent state. */
+    cumulativeInputTokens?: number;
+    cumulativeOutputTokens?: number;
+    /** The matched rule's `kind` when a `'fail-fast'` rule fired.
+     *  `Agent.run()` reads this to construct `ReliabilityFailFastError.kind`. */
+    failKind?: string;
+    /** Structured payload describing the fail-fast event. Shape:
+     *  `{ phase, attempt, providerUsed, errorKind, errorMessage }`. */
+    failPayload?: {
+        readonly phase: 'pre-check' | 'post-decide';
+        readonly attempt: number;
+        readonly providerUsed: string;
+        readonly errorKind: ReliabilityScope['errorKind'];
+        readonly errorMessage?: string;
+    };
+}
+/**
+ * Thrown by `Agent.run()` when a reliability rule routes to `'fail-fast'`
+ * and the gate $breaks with a reason. Carries:
+ *
+ *   • `kind`     — machine-readable identifier from the matched rule's
+ *                  `kind` field. Stable across versions; consumers
+ *                  branch on this.
+ *   • `reason`   — human-readable narrative string from `$break(reason)`.
+ *                  Format: `'reliability-{phase}: {label}'` (e.g.,
+ *                  `'reliability-post-decide: cost-cap-exceeded'`).
+ *   • `cause`    — the originating error from the LLM call, when one
+ *                  drove the fail-fast decision (e.g., the underlying
+ *                  HTTP error that tripped a circuit breaker).
+ *   • `snapshot` — the full `executor.getSnapshot()` at fail-fast time
+ *                  for forensics. Consumers persist this for postmortem
+ *                  analysis (commitLog, narrative, scope state, etc.).
+ *
+ * Three-channel discipline: `kind`/`payload` came from scope state,
+ * `reason` came from $break, `snapshot` is the engine's own audit trail.
+ * Emit events flowed independently to any attached observability adapter
+ * (this error is the RUNTIME signal; emit is the OBSERVABILITY signal).
+ */
+export declare class ReliabilityFailFastError extends Error {
+    readonly code: "ERR_RELIABILITY_FAIL_FAST";
+    readonly kind: string;
+    readonly reason: string;
+    readonly cause?: Error;
+    readonly snapshot?: unknown;
+    readonly payload?: ReliabilityScope['failPayload'];
+    constructor(opts: {
+        kind: string;
+        reason: string;
+        cause?: Error;
+        snapshot?: unknown;
+        payload?: ReliabilityScope['failPayload'];
+    });
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/reliability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/reliability/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.10.2",
+  "version": "2.11.1",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",