agentfootprint/dist/esm/reliability/buildReliabilityGateChart.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * buildReliabilityGateChart — produces a footprintjs FlowChart that wraps
 * an LLM call with rules-based reliability semantics, using the native
 * `decide()` DSL via `addDeciderFunction` decider stages.
 *
 * ⚠ NOT REACHABLE FROM ANY SHIPPED PATH (verified 2026-07-28). This header
 * used to say the chart "is mounted as a subflow in the agent's chart at
 * Agent.build() time (only when reliability is configured)". It is not:
 * `buildReliabilityGateChart` is exported from no barrel, and its only
 * consumer in the repository is its own test
 * (`test/reliability/gate-chart-7pattern.test.ts`). The live
 * `.reliability()` path is `executeWithReliability`
 * (`core/agent/stages/reliabilityExecution.ts`) driving
 * `singleProviderCall` inline in `core/agent/stages/callLLM.ts` — which
 * trades this chart's subflow visibility for streaming support. Keep this
 * file honest rather than deleting it: it is the only implementation that
 * honours the `providers` failover list (see MENTAL_MODEL §14 item 3).
 *
 * Inside the subflow, when something does mount it:
 *
 *   PreCheck (decider) → CallProvider (function) → PostDecide (decider)
 *                                                       │
 *                                       ┌───────────────┘
 *                                       ▼ loopTo('pre-check')
 *
 * Branch outcomes (escape via $break() to stop the gate's loop;
 * fall-through via no-$break to trigger loopTo back to PreCheck):
 *
 *   PreCheck:
 *     'continue'   → no-op   → falls through to CallProvider
 *     'fail-fast'  → set failKind, $emit, $break(reason)
 *
 *   PostDecide:
 *     'ok'          → $break() (subflow exits normally; agent continues)
 *     'retry'       → bump attempt; falls through to loopTo
 *     'retry-other' → bump providerIdx; falls through to loopTo
 *     'fallback'    → call config.fallback(); $break() on success
 *     'fail-fast'   → set failKind, $emit, $break(reason)
 *
 * The design intends the subflow to be mounted WITHOUT `propagateBreak:
 * true`, so subflow `$break` stays local and an agent-level
 * `TranslateFailFast` stage reads `scope.reliabilityFailKind` and converts
 * it into an agent-level `$break(reason)` — letting normal subflow exits
 * (`ok`/`fallback`) leave the agent running while fail-fast stops it. That
 * stage was never built (`grep TranslateFailFast` finds only comments), which
 * is part of why nothing mounts this chart; the live path throws
 * `ReliabilityFailFastError` from `Agent.run` instead.
 *
 * Three-channel discipline preserved:
 *   • SCOPE STATE  — failKind/failPayload/failReason mapped to parent via
 *                    outputMapper; for the intended TranslateFailFast.
 *   • $emit        — passive observability for external consumers.
 *   • $break(reason)— control flow + human reason for narrative.
 */
import type { FlowChart } from 'footprintjs';
import type { ReliabilityConfig } from './types.js';
/**
 * Build the reliability gate FlowChart from a config. Mount via
 * `addSubFlowChartNext` in the agent's chart — see `Agent.build()`.
 *
 * Closure state captured by stage functions:
 *   • `breakers` — Map<providerName, CircuitBreaker>; per-instance state
 *     persists across gate invocations within ONE agent process.
 *   • `preRules` / `postRules` — frozen rule arrays.
 *   • `fallbackFn` — consumer's fallback function, if configured.
 */
export declare function buildReliabilityGateChart(config: ReliabilityConfig): FlowChart;