agentfootprint 2.11.4 → 2.11.5

package/dist/esm/core/agent/stages/reliabilityExecution.js

@@ -0,0 +1,287 @@
+/**
+ * reliabilityExecution — the retry-loop helper invoked by `callLLM`
+ * when `Agent.create(...).reliability(config)` is configured.
+ *
+ * Wraps a single-shot LLM call with rules-based reliability semantics:
+ *
+ *   PreCheck rules    → continue / fail-fast
+ *     ↓
+ *   provider call     → response | error
+ *     ↓
+ *   PostDecide rules  → ok / retry / retry-other / fallback / fail-fast
+ *     ↓
+ *   loop or commit
+ *
+ * The loop runs in JS within a SINGLE footprintjs stage execution. The
+ * trace shows one CallLLM stage that internally retried N times. Richer
+ * "every retry as a separate stage" tracing is the v2.11.6+ work via
+ * `buildReliabilityGateChart` (which trades streaming support for
+ * stage-level granularity).
+ *
+ * Streaming + reliability semantics — first-chunk arbitration:
+ *   • Pre-first-chunk failures (connection, headers, breaker-open):
+ *     full rule set fires (retry / retry-other / fallback / fail-fast).
+ *   • Post-first-chunk failures (mid-stream): rules can ONLY emit
+ *     `ok` (commit what we have) or `fail-fast`. Retry / retry-other /
+ *     fallback are escalated to fail-fast with kind
+ *     `'mid-stream-not-retryable'`. Matches LangChain's
+ *     `RunnableWithFallbacks` first-chunk arbitration pattern.
+ *
+ * On fail-fast: writes `failKind` + `failPayload` to agent scope and
+ * calls `$break(reason)`. The agent's main chart catches the break;
+ * `Agent.run()` translates it into a typed `ReliabilityFailFastError`
+ * at the API boundary (via `TranslateFailFast` stage).
+ *
+ * Closure-local state (NOT scope):
+ *   • `attempt`         — 1-indexed attempt counter
+ *   • `providerIdx`     — index into the failover list
+ *   • `breakerStates`   — per-provider breaker state (Map)
+ *   • `attemptsPerProvider` — per-provider counter
+ *
+ * Why closure-local: this is one footprintjs stage execution. Putting
+ * counters into scope would commit them across iterations of the
+ * agent's outer ReAct loop, which is not the intent.
+ */
+import { CircuitOpenError, admitCall, initialBreakerState, nextProbeTime, recordFailure, recordSuccess, } from '../../../reliability/CircuitBreaker.js';
+import { classifyError } from '../../../reliability/classifyError.js';
+/** Sentinel kind written to scope on a mid-stream failure that the
+ *  rules wanted to retry. Surfaces in `ReliabilityFailFastError.kind`. */
+export const MID_STREAM_KIND = 'mid-stream-not-retryable';
+/**
+ * Run the reliability retry loop. Returns the committed `LLMResponse`
+ * on success; calls `scope.$break(reason)` and returns `undefined` on
+ * fail-fast (caller short-circuits when undefined is returned).
+ */
+export async function executeWithReliability(scope, request, config, defaultProvider, defaultProviderName, defaultModel, callFn) {
+    const preRules = config.preCheck ?? [];
+    const postRules = config.postDecide ?? [];
+    const providers = config.providers ?? [];
+    const breakerConfig = config.circuitBreaker;
+    const fallbackFn = config.fallback;
+    // Closure-local state — see header comment for rationale.
+    let attempt = 0;
+    let providerIdx = 0;
+    let firstChunkSeen = false;
+    const breakerStates = {};
+    const attemptsPerProvider = {};
+    // Helper: build the reliability scope view rules read.
+    const reliabilityScope = () => {
+        const currentProvider = providerEntry().name;
+        return {
+            request,
+            providersCount: providers.length,
+            hasFallback: fallbackFn !== undefined,
+            attempt,
+            providerIdx,
+            currentProvider,
+            canSwitchProvider: providerIdx < providers.length - 1,
+            response: lastResponse,
+            error: lastError,
+            errorKind: lastErrorKind,
+            latencyMs: lastLatencyMs,
+            attemptsPerProvider,
+            breakerStates,
+        };
+    };
+    // Pick provider for current attempt — failover list if configured,
+    // else the agent's default provider.
+    const providerEntry = () => {
+        if (providers.length > 0) {
+            const entry = providers[providerIdx];
+            if (entry)
+                return entry;
+        }
+        return { name: defaultProviderName, provider: defaultProvider, model: defaultModel };
+    };
+    // Helper: build failPayload + write scope + emit + break.
+    const failFast = (phase, kind, label) => {
+        const cur = providerEntry();
+        const payload = {
+            phase,
+            attempt,
+            providerUsed: cur.name,
+            errorKind: lastErrorKind,
+            ...(lastError?.message !== undefined && { errorMessage: lastError.message }),
+        };
+        const reason = `reliability-${phase}: ${label}`;
+        scope.reliabilityFailKind = kind;
+        scope.reliabilityFailPayload =
+            payload;
+        scope.reliabilityFailReason = reason;
+        if (lastError !== undefined) {
+            // Store the originating error as plain strings — Error instances
+            // don't round-trip cleanly through scope's structuredClone. The
+            // Agent.run() boundary reconstructs a new Error from these for
+            // ReliabilityFailFastError.cause; consumer's `instanceof` checks
+            // get a stable Error subclass without us needing to preserve the
+            // exact prototype.
+            scope.reliabilityFailCauseMessage =
+                lastError.message;
+            scope.reliabilityFailCauseName =
+                lastError.name;
+        }
+        scope.$emit('agentfootprint.reliability.fail_fast', {
+            phase,
+            kind,
+            label,
+            attempt,
+            providerUsed: cur.name,
+            errorKind: lastErrorKind,
+            ...(lastError?.message !== undefined && { errorMessage: lastError.message }),
+        });
+        scope.$break(reason);
+        return undefined;
+    };
+    // Mutable per-attempt state. Outside the loop so reliabilityScope() can read.
+    let lastResponse;
+    let lastError;
+    let lastErrorKind = 'ok';
+    let lastLatencyMs = 0;
+    // We DON'T use footprintjs `decide()` here — its predicates bind
+    // to the active agent scope via TypedScope, but our `ReliabilityRule`
+    // predicates take the synthesized `ReliabilityScope` view (a closure-
+    // local projection over the retry-loop's mutable state). Iterate
+    // rules manually instead. The `decide()` import is kept available
+    // for `buildReliabilityGateChart` which DOES use it via subflows.
+    const evalRules = (rules, fallback) => {
+        const sv = reliabilityScope();
+        for (const rule of rules) {
+            try {
+                if (rule.when(sv))
+                    return { branch: rule.then, matched: rule };
+            }
+            catch {
+                // Predicate threw — skip this rule. Per ReliabilityRule
+                // contract predicates should be pure; treat throws as no-match.
+            }
+        }
+        return { branch: fallback };
+    };
+    if (preRules.length > 0) {
+        const pre = evalRules(preRules, 'continue');
+        if (pre.branch === 'fail-fast') {
+            const kind = pre.matched?.kind ?? 'pre-check-failed';
+            const label = pre.matched?.label ?? kind;
+            return failFast('pre-check', kind, label);
+        }
+    }
+    // ─── Retry loop ─────────────────────────────────────────────────
+    // Hard upper bound prevents pathological rule sets from looping forever.
+    // Most consumer rules cap retry at 3-5 via `attempt < N` predicates;
+    // this is just a safety net.
+    const MAX_LOOP = 50;
+    for (let loop = 0; loop < MAX_LOOP; loop++) {
+        const cur = providerEntry();
+        // Breaker check (pure): admit + transition based on cooldown.
+        if (breakerConfig !== undefined) {
+            const current = breakerStates[cur.name] ?? initialBreakerState();
+            const { admitted, nextState } = admitCall(current, breakerConfig);
+            breakerStates[cur.name] = nextState;
+            if (!admitted) {
+                lastError = new CircuitOpenError(cur.name, nextState.lastErrorMessage, nextProbeTime(nextState, breakerConfig));
+                lastErrorKind = 'circuit-open';
+                lastResponse = undefined;
+                // Skip the call; jump straight to PostDecide so rules can
+                // route on errorKind === 'circuit-open'.
+            }
+        }
+        // Fire the actual call (unless breaker pre-emptied above).
+        if (lastErrorKind !== 'circuit-open') {
+            const t0 = Date.now();
+            try {
+                const response = await callFn(request, {
+                    onFirstChunk: () => {
+                        firstChunkSeen = true;
+                    },
+                });
+                lastResponse = response;
+                lastError = undefined;
+                lastErrorKind = 'ok';
+                if (breakerConfig !== undefined) {
+                    breakerStates[cur.name] = recordSuccess(breakerStates[cur.name] ?? initialBreakerState(), breakerConfig);
+                }
+            }
+            catch (err) {
+                lastResponse = undefined;
+                lastError = err instanceof Error ? err : new Error(String(err));
+                lastErrorKind = classifyError(err);
+                if (breakerConfig !== undefined && !(err instanceof CircuitOpenError)) {
+                    breakerStates[cur.name] = recordFailure(breakerStates[cur.name] ?? initialBreakerState(), err, breakerConfig);
+                }
+            }
+            finally {
+                lastLatencyMs = Date.now() - t0;
+                attemptsPerProvider[cur.name] = (attemptsPerProvider[cur.name] ?? 0) + 1;
+                attempt += 1;
+            }
+        }
+        // PostDecide
+        let postBranch = 'ok';
+        let matchedRule;
+        if (postRules.length > 0) {
+            const post = evalRules(postRules, lastError === undefined ? 'ok' : 'fail-fast');
+            postBranch = post.branch;
+            matchedRule = post.matched;
+        }
+        else if (lastError !== undefined) {
+            // No postDecide rules + error → default fail-fast.
+            postBranch = 'fail-fast';
+        }
+        // First-chunk arbitration: post-first-chunk only `ok` and
+        // `fail-fast` are honored. Other decisions escalate to fail-fast
+        // with the mid-stream-not-retryable kind. This matches the
+        // LangChain RunnableWithFallbacks pattern documented in the
+        // streaming-vs-reliability design memo.
+        if (firstChunkSeen && postBranch !== 'ok' && postBranch !== 'fail-fast') {
+            return failFast('post-decide', MID_STREAM_KIND, `mid-stream failure not retryable (rule wanted '${postBranch}')`);
+        }
+        if (postBranch === 'ok') {
+            // Success exit. lastResponse is the committed value.
+            if (lastResponse !== undefined)
+                return lastResponse;
+            // 'ok' with no response is misconfiguration; fall through to
+            // fail-fast as a defensive default.
+            return failFast('post-decide', 'no-response', 'rule said ok but no response captured');
+        }
+        if (postBranch === 'fail-fast') {
+            const kind = matchedRule?.kind ?? lastErrorKind;
+            const label = matchedRule?.label ?? matchedRule?.kind ?? lastErrorKind;
+            return failFast('post-decide', kind, label);
+        }
+        if (postBranch === 'retry') {
+            // Loop continues; attempt was already bumped in finally.
+            continue;
+        }
+        if (postBranch === 'retry-other') {
+            providerIdx += 1;
+            if (providerIdx >= Math.max(providers.length, 1)) {
+                // Walked past the last provider — convert to fail-fast.
+                return failFast('post-decide', 'no-more-providers', 'retry-other requested but no more providers');
+            }
+            continue;
+        }
+        if (postBranch === 'fallback') {
+            if (!fallbackFn) {
+                return failFast('post-decide', 'fallback-not-configured', 'rule wanted fallback but no fallback fn provided');
+            }
+            try {
+                const repaired = await fallbackFn(request, lastError);
+                // Successful fallback — commit and exit.
+                return repaired;
+            }
+            catch (fallbackErr) {
+                // Fallback threw — re-classify and let next iteration's
+                // post-decide rules route on the new error.
+                lastError = fallbackErr instanceof Error ? fallbackErr : new Error(String(fallbackErr));
+                lastErrorKind = classifyError(fallbackErr);
+                lastResponse = undefined;
+                continue;
+            }
+        }
+        // Unknown branch — fail-fast as a defensive default.
+        return failFast('post-decide', 'unknown-branch', `unknown decision '${postBranch}'`);
+    }
+    // Hit the safety cap.
+    return failFast('post-decide', 'max-loop-exceeded', `reliability loop exceeded ${MAX_LOOP} iterations`);
+}
+//# sourceMappingURL=reliabilityExecution.js.map

package/dist/esm/core/agent/stages/reliabilityExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliabilityExecution.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/reliabilityExecution.ts"],"names":[],"mappings":"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"}

package/dist/types/core/Agent.d.ts

@@ -15,6 +15,7 @@
  */
 import { type CombinedNarrativeEntry, type FlowChart, type FlowchartCheckpoint, type RunOptions, type RuntimeSnapshot } from 'footprintjs';
 import type { CachePolicy, CacheStrategy } from '../cache/types.js';
+import type { ReliabilityConfig } from '../reliability/types.js';
 import { type RunnerPauseOutcome } from './pause.js';
 import type { MemoryDefinition } from '../memory/define.types.js';
 import type { Injection } from '../lib/injection-engine/types.js';
@@ -129,11 +130,18 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * dispatch correctly when their visible-set changes mid-turn.
      */
     private readonly externalToolProvider?;
+    /**
+     * Optional rules-based reliability config (v2.11.5+). Set via the
+     * builder's `.reliability({...})`. When present, every CallLLM
+     * execution is wrapped in a retry/fallback/fail-fast loop driven
+     * by `preCheck` and `postDecide` rules. Consumed by `buildCallLLMStage`.
+     */
+    private readonly reliabilityConfig?;
     constructor(opts: AgentOptions, systemPromptValue: string, registry: readonly ToolRegistryEntry[], voice: {
         readonly appName: string;
         readonly commentaryTemplates: Readonly<Record<string, string>>;
         readonly thinkingTemplates: Readonly<Record<string, string>>;
-    }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy, outputFallbackCfg?: ResolvedOutputFallback<unknown>);
+    }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy, outputFallbackCfg?: ResolvedOutputFallback<unknown>, reliabilityConfig?: ReliabilityConfig);
     static create(opts: AgentOptions): AgentBuilder;
     toFlowChart(): FlowChart;
     /**

package/dist/types/core/Agent.d.ts.map

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

package/dist/types/core/agent/AgentBuilder.d.ts

@@ -11,6 +11,7 @@ import { type OutputFallbackOptions } from '../outputFallback.js';
 import type { CachePolicy } from '../../cache/types.js';
 import type { Injection } from '../../lib/injection-engine/types.js';
 import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { ReliabilityConfig } from '../../reliability/types.js';
 import type { Tool } from '../tools.js';
 import type { ToolProvider } from '../../tool-providers/types.js';
 import { Agent } from '../Agent.js';
@@ -74,6 +75,13 @@ export declare class AgentBuilder {
     private appNameValue;
     private commentaryOverrides;
     private thinkingOverrides;
+    /**
+     * Optional rules-based reliability config (v2.11.5+). Set via
+     * `.reliability({...})`. Wraps every `CallLLM` execution in a
+     * retry/fallback/fail-fast loop driven by `preCheck` and `postDecide`
+     * rules. See `ReliabilityConfig` for the rule shape.
+     */
+    private reliabilityConfig?;
     constructor(opts: AgentOptions);
     /**
      * Set the base system prompt.
@@ -343,6 +351,59 @@ export declare class AgentBuilder {
      * ```
      */
     outputFallback<T>(options: OutputFallbackOptions<T>): this;
+    /**
+     * Wire rules-based reliability around every `CallLLM` execution.
+     * The framework wraps the LLM call in a retry/fallback/fail-fast
+     * loop driven by `preCheck` and `postDecide` rules.
+     *
+     * Decision verbs the rules can emit (see `ReliabilityDecision` for
+     * the full list):
+     *
+     *   • `continue`    — pre-check OK, proceed to the call
+     *   • `ok`          — post-call OK, commit and return
+     *   • `retry`       — re-call same provider (bumps `attempt`)
+     *   • `retry-other` — advance to next provider in `providers[]`
+     *   • `fallback`    — invoke `config.fallback(req, lastError)`
+     *   • `fail-fast`   — throw `ReliabilityFailFastError` at `agent.run()`
+     *
+     * **Streaming + reliability semantics — first-chunk arbitration:**
+     * Pre-first-chunk failures (connection/headers/breaker-open) honor
+     * the full rule set (retry, retry-other, fallback, fail-fast).
+     * Post-first-chunk failures (mid-stream) honor only `ok` and
+     * `fail-fast`; rules wanting `retry`/`retry-other`/`fallback` are
+     * escalated to fail-fast with kind `'mid-stream-not-retryable'`.
+     * This matches LangChain's `RunnableWithFallbacks` pattern and
+     * the prevailing industry default — see the streaming + reliability
+     * design memo for the full discussion.
+     *
+     * Throws if called more than once on the same builder.
+     *
+     * @example
+     *   import { Agent } from 'agentfootprint';
+     *   import { ReliabilityFailFastError } from 'agentfootprint/reliability';
+     *
+     *   const agent = Agent.create({ provider, model: 'mock' })
+     *     .system('Triage support tickets.')
+     *     .reliability({
+     *       postDecide: [
+     *         { when: (s) => s.errorKind === '5xx-transient' && s.attempt < 3,
+     *           then: 'retry', kind: 'transient-retry' },
+     *         { when: (s) => s.error !== undefined,
+     *           then: 'fail-fast', kind: 'unrecoverable' },
+     *       ],
+     *       circuitBreaker: { failureThreshold: 3 },
+     *     })
+     *     .build();
+     *
+     *   try {
+     *     await agent.run({ message: 'help' });
+     *   } catch (e) {
+     *     if (e instanceof ReliabilityFailFastError) {
+     *       console.log(e.kind, e.reason);
+     *     }
+     *   }
+     */
+    reliability(config: ReliabilityConfig): this;
     build(): Agent;
 }
 //# sourceMappingURL=AgentBuilder.d.ts.map

package/dist/types/core/agent/AgentBuilder.d.ts.map

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

package/dist/types/core/agent/stages/callLLM.d.ts

@@ -21,6 +21,7 @@
 import type { TypedScope } from 'footprintjs';
 import type { LLMProvider, LLMToolSchema, PricingTable } from '../../../adapters/types.js';
 import type { CacheStrategy } from '../../../cache/types.js';
+import type { ReliabilityConfig } from '../../../reliability/types.js';
 import type { AgentState } from '../types.js';
 export interface CallLLMStageDeps {
     /** The LLM provider to invoke. */
@@ -44,6 +45,13 @@ export interface CallLLMStageDeps {
      *  pattern — toolSchemas is computed AFTER stage factories are
      *  built). The getter resolves the eventual value at run time. */
     readonly toolSchemas: readonly LLMToolSchema[];
+    /** Optional rules-based reliability config (v2.11.5+). When set,
+     *  the call is wrapped in a retry/fallback/fail-fast loop driven
+     *  by `config.preCheck` and `config.postDecide` rules. Streaming
+     *  is preserved; mid-stream failures use first-chunk arbitration —
+     *  see `reliabilityExecution.ts` and the streaming + reliability
+     *  design memo. */
+    readonly reliability?: ReliabilityConfig;
 }
 /**
  * Build the callLLM stage function. Captures the LLM provider + model

package/dist/types/core/agent/stages/callLLM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,WAAW,EAEX,aAAa,EACb,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;qDACiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;sEAEkE;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,GACrB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAyGlD"}
+{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,WAAW,EAGX,aAAa,EACb,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;qDACiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;sEAEkE;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;uBAKmB;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,GACrB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CA8IlD"}

package/dist/types/core/agent/stages/reliabilityExecution.d.ts

@@ -0,0 +1,66 @@
+/**
+ * reliabilityExecution — the retry-loop helper invoked by `callLLM`
+ * when `Agent.create(...).reliability(config)` is configured.
+ *
+ * Wraps a single-shot LLM call with rules-based reliability semantics:
+ *
+ *   PreCheck rules    → continue / fail-fast
+ *     ↓
+ *   provider call     → response | error
+ *     ↓
+ *   PostDecide rules  → ok / retry / retry-other / fallback / fail-fast
+ *     ↓
+ *   loop or commit
+ *
+ * The loop runs in JS within a SINGLE footprintjs stage execution. The
+ * trace shows one CallLLM stage that internally retried N times. Richer
+ * "every retry as a separate stage" tracing is the v2.11.6+ work via
+ * `buildReliabilityGateChart` (which trades streaming support for
+ * stage-level granularity).
+ *
+ * Streaming + reliability semantics — first-chunk arbitration:
+ *   • Pre-first-chunk failures (connection, headers, breaker-open):
+ *     full rule set fires (retry / retry-other / fallback / fail-fast).
+ *   • Post-first-chunk failures (mid-stream): rules can ONLY emit
+ *     `ok` (commit what we have) or `fail-fast`. Retry / retry-other /
+ *     fallback are escalated to fail-fast with kind
+ *     `'mid-stream-not-retryable'`. Matches LangChain's
+ *     `RunnableWithFallbacks` first-chunk arbitration pattern.
+ *
+ * On fail-fast: writes `failKind` + `failPayload` to agent scope and
+ * calls `$break(reason)`. The agent's main chart catches the break;
+ * `Agent.run()` translates it into a typed `ReliabilityFailFastError`
+ * at the API boundary (via `TranslateFailFast` stage).
+ *
+ * Closure-local state (NOT scope):
+ *   • `attempt`         — 1-indexed attempt counter
+ *   • `providerIdx`     — index into the failover list
+ *   • `breakerStates`   — per-provider breaker state (Map)
+ *   • `attemptsPerProvider` — per-provider counter
+ *
+ * Why closure-local: this is one footprintjs stage execution. Putting
+ * counters into scope would commit them across iterations of the
+ * agent's outer ReAct loop, which is not the intent.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMProvider, LLMRequest, LLMResponse } from '../../../adapters/types.js';
+import type { ReliabilityConfig } from '../../../reliability/types.js';
+import type { AgentState } from '../types.js';
+/** A single-shot LLM call function. Built once by `callLLM.ts` and
+ *  passed into this helper; we invoke it once per loop iteration. */
+export type LLMCallFn = (request: LLMRequest, hooks: {
+    /** Called the first time a streaming chunk yields content. After
+     *  this fires, mid-stream errors will escalate retry/fallback to
+     *  fail-fast. */
+    onFirstChunk?: () => void;
+}) => Promise<LLMResponse>;
+/** Sentinel kind written to scope on a mid-stream failure that the
+ *  rules wanted to retry. Surfaces in `ReliabilityFailFastError.kind`. */
+export declare const MID_STREAM_KIND = "mid-stream-not-retryable";
+/**
+ * Run the reliability retry loop. Returns the committed `LLMResponse`
+ * on success; calls `scope.$break(reason)` and returns `undefined` on
+ * fail-fast (caller short-circuits when undefined is returned).
+ */
+export declare function executeWithReliability(scope: TypedScope<AgentState>, request: LLMRequest, config: ReliabilityConfig, defaultProvider: LLMProvider, defaultProviderName: string, defaultModel: string, callFn: LLMCallFn): Promise<LLMResponse | undefined>;
+//# sourceMappingURL=reliabilityExecution.d.ts.map

package/dist/types/core/agent/stages/reliabilityExecution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliabilityExecution.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/reliabilityExecution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAWvF,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;qEACqE;AACrE,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE;IACL;;qBAEiB;IACjB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,KACE,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B;0EAC0E;AAC1E,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,EAC7B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,WAAW,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAgRlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.11.4",
+  "version": "2.11.5",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -154,6 +154,11 @@
       "import": "./dist/esm/security/index.js",
       "require": "./dist/security/index.js"
     },
+    "./reliability": {
+      "types": "./dist/types/reliability/index.d.ts",
+      "import": "./dist/esm/reliability/index.js",
+      "require": "./dist/reliability/index.js"
+    },
     "./locales": {
       "types": "./dist/types/locales/index.d.ts",
       "import": "./dist/esm/locales/index.js",