agentfootprint 2.11.0 → 2.11.2

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

@@ -0,0 +1,54 @@
+/**
+ * seed — initial stage of the agent's chart. Initializes every mutable
+ * field of `AgentState` from the consumer's input.
+ *
+ * Runs once per `agent.run({ input })`. The chart is built once at
+ * Agent construction, so seed has access to BOTH:
+ *
+ *   • CHART-BUILD-TIME constants (maxIterations, cachingDisabled,
+ *     toolSchemas) — passed as direct values to the factory.
+ *   • PER-RUN MUTABLE state (pendingResumeHistory from
+ *     resumeOnError(), currentRunContext.runId set per run) —
+ *     passed as accessor closures over the Agent instance, since
+ *     these change between consecutive `agent.run()` invocations.
+ *
+ * The accessor pattern keeps `seed` decoupled from the Agent class
+ * while preserving the per-run mutability the resume + identity
+ * features need.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMMessage, LLMToolSchema } from '../../../adapters/types.js';
+import type { AgentState } from '../types.js';
+export interface SeedStageDeps {
+    /** Resolved `clampIterations(opts.maxIterations ?? 10)`. Frozen at
+     *  chart-build time. */
+    readonly maxIterations: number;
+    /** Resolved cache kill switch from `Agent.create({ caching: 'off' })`. */
+    readonly cachingDisabled: boolean;
+    /** Static tool schemas resolved at chart-build time. The tools slot
+     *  subflow can OVERRIDE this per-iteration via `dynamicToolSchemas`,
+     *  but seed populates the initial value so iter 1 has it. */
+    readonly toolSchemas: readonly LLMToolSchema[];
+    /**
+     * Read-AND-CLEAR accessor for the resume side-channel. Called exactly
+     * once per `agent.run()` from inside seed. If `resumeOnError(checkpoint)`
+     * was invoked before `run()`, this returns the checkpointed history
+     * and clears the field so the NEXT `run()` starts fresh. Returns
+     * `undefined` for the normal (non-resume) path.
+     */
+    readonly consumePendingResumeHistory: () => readonly LLMMessage[] | undefined;
+    /**
+     * Accessor for the current run's id, used to default the memory
+     * identity when consumer didn't pass `agent.run({ identity })`. Set
+     * by RunnerBase on every `agent.run()` call before the chart starts.
+     * Returns `undefined` only in degenerate (test) cases.
+     */
+    readonly getCurrentRunId: () => string | undefined;
+}
+/**
+ * Build the seed stage function for an Agent instance. Captures both
+ * the chart-build-time constants and the per-run mutable accessors
+ * via the deps object.
+ */
+export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void;
+//# sourceMappingURL=seed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B;4BACwB;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;iEAE6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,2BAA2B,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IAC9E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAmE3F"}

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

@@ -0,0 +1,50 @@
+/**
+ * toolCalls — pausable handler for executing the LLM-requested tool
+ * calls in the agent's ReAct loop.
+ *
+ *   • `execute` iterates `scope.llmLatestToolCalls`, dispatches each
+ *     tool, appends results to scope.history, and increments
+ *     `scope.iteration`. If a tool throws `PauseRequest` (via
+ *     `pauseHere()`), commits partial state and returns the pause
+ *     payload so footprintjs captures a checkpoint.
+ *   • `resume` runs after the consumer supplies the human's answer.
+ *     Treats that answer as the paused tool's result, appends to
+ *     history, then continues the ReAct iteration loop.
+ *
+ * Dispatch resolution order:
+ *   1. Static registry built at chart-build time (registryByName).
+ *   2. External `ToolProvider.list(ctx).find(...)` if a `.toolProvider()`
+ *      was wired and the tool isn't in the static registry.
+ *
+ * Permission gate (when `permissionChecker` is configured) runs BEFORE
+ * `tool.execute`. Deny → tool not executed; result is a synthetic
+ * denial string. Allow / gate_open → execution proceeds.
+ *
+ * `read_skill` is the auto-attached activation tool — when the LLM
+ * calls it with a valid Skill id, the next InjectionEngine pass
+ * activates that Skill (lifetime: turn).
+ */
+import type { PausableHandler, TypedScope } from 'footprintjs';
+import type { PermissionChecker } from '../../../adapters/types.js';
+import type { ToolProvider } from '../../../tool-providers/types.js';
+import type { Tool } from '../../tools.js';
+import type { AgentState } from '../types.js';
+export interface ToolCallsHandlerDeps {
+    /** Map from tool name → Tool instance, built from the augmented
+     *  registry (static .tool() entries + read_skill if any skills +
+     *  shared skill tools). The dispatch primary lookup. */
+    readonly registryByName: ReadonlyMap<string, Tool>;
+    /** Optional external `.toolProvider()` for per-iteration dynamic
+     *  tools (skill-scoped, multi-tenant, etc.). Consulted only when
+     *  the static registry doesn't have the tool. */
+    readonly externalToolProvider?: ToolProvider;
+    /** Optional permission gate. When present, every tool dispatch
+     *  awaits `check({capability: 'tool_call', ...})` BEFORE executing.
+     *  Throwing checkers are treated as deny-by-default. */
+    readonly permissionChecker?: PermissionChecker;
+}
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+export declare function buildToolCallsHandler(deps: ToolCallsHandlerDeps): PausableHandler<TypedScope<AgentState>>;
+//# sourceMappingURL=toolCalls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolCalls.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/toolCalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGhF,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAE1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC;;4DAEwD;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnD;;qDAEiD;IACjD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,CAAC;IAC7C;;4DAEwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CA2NzC"}

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

@@ -0,0 +1,154 @@
+/**
+ * Agent type definitions — both PUBLIC types (AgentOptions, AgentInput,
+ * AgentOutput) consumed by `Agent.create({...}).run({...})` callers AND
+ * the INTERNAL `AgentState` shape used by stage functions.
+ *
+ * These were originally inline in `core/Agent.ts`; extracted here as
+ * part of the v2.11.1 decomposition. `core/Agent.ts` re-exports them
+ * for back-compat (the 28+ existing import sites continue to work).
+ */
+import type { LLMMessage, LLMProvider, LLMToolSchema, PermissionChecker, PricingTable } from '../../adapters/types.js';
+import type { CacheMarker, CacheStrategy } from '../../cache/types.js';
+import type { ActiveInjection } from '../../lib/injection-engine/types.js';
+import type { InjectionRecord } from '../../recorders/core/types.js';
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+export interface AgentOptions {
+    readonly provider: LLMProvider;
+    /** Human-friendly name shown in events/metrics. Default: 'Agent'. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default: 'agent'. */
+    readonly id?: string;
+    readonly model: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /** Hard budget on ReAct iterations. Default: 10. Hard cap: 50. */
+    readonly maxIterations?: number;
+    /**
+     * Pricing adapter. When set, Agent emits `agentfootprint.cost.tick`
+     * after every LLM response (once per ReAct iteration) with per-call
+     * and cumulative USD. Run-scoped — the cumulative resets each `.run()`.
+     */
+    readonly pricingTable?: PricingTable;
+    /**
+     * Cumulative USD budget per run. With `pricingTable`, Agent emits a
+     * one-shot `agentfootprint.cost.limit_hit` (`action: 'warn'`) when
+     * cumulative USD crosses this budget. Execution continues — consumers
+     * choose whether to abort by listening to the event.
+     */
+    readonly costBudget?: number;
+    /**
+     * Permission adapter. When set, the Agent calls
+     * `permissionChecker.check({capability: 'tool_call', ...})` BEFORE every
+     * `tool.execute()`. Emits `agentfootprint.permission.check` with the
+     * decision. On `deny`, the tool is skipped and its result is a
+     * synthetic denial string; on `allow` / `gate_open`, execution proceeds
+     * normally.
+     */
+    readonly permissionChecker?: PermissionChecker;
+    /**
+     * Global cache kill switch (v2.6+). `'off'` disables the cache
+     * layer entirely — the CacheGate decider routes to `'no-markers'`
+     * every iteration regardless of other rules. Default: caching
+     * enabled (auto-resolved per provider via the strategy registry).
+     *
+     * Use `'off'` for low-frequency agents (cron jobs running once per
+     * hour) where the cache TTL guarantees zero cache hits and the
+     * cache-write penalty isn't worth paying.
+     */
+    readonly caching?: 'off';
+    /**
+     * Optional explicit CacheStrategy override (v2.6+). Defaults to
+     * `getDefaultCacheStrategy(provider.name)` — so Anthropic/OpenAI/
+     * Bedrock/Mock providers auto-resolve to their respective strategies
+     * once those land in Phase 7+.
+     */
+    readonly cacheStrategy?: CacheStrategy;
+}
+export interface AgentInput {
+    readonly message: string;
+    /**
+     * Multi-tenant memory scope. Populated to `scope.identity` so memory
+     * subflows registered via `.memory()` can isolate reads/writes per
+     * tenant + principal + conversation.
+     *
+     * Defaults to `{ conversationId: '<runId>' }` when omitted, so agents
+     * without memory work unchanged.
+     */
+    readonly identity?: MemoryIdentity;
+}
+export type AgentOutput = string;
+/**
+ * Internal scope state for the Agent's flowchart. Recorders never read
+ * this directly — they read the InjectionRecord convention keys + emit
+ * events. Each stage function under `./stages/` receives a TypedScope
+ * over this shape and reads/writes via typed properties.
+ *
+ * Mutability conventions (followed by every Agent stage):
+ *   • Per-iteration scalars (iteration, finalContent, llmLatestContent,
+ *     etc.) are OVERWRITTEN each pass; commitLog preserves history.
+ *   • Cumulative scalars (cumTokensInput, totalInputTokens, turnNumber)
+ *     accumulate monotonically across the run.
+ *   • Arrays from slot subflows (systemPromptInjections,
+ *     messagesInjections, toolsInjections, dynamicToolSchemas,
+ *     cacheMarkers) use `arrayMerge: ArrayMergeMode.Replace` semantics —
+ *     each iteration's value REPLACES the prior iteration's, not
+ *     appends.
+ */
+export interface AgentState {
+    userMessage: string;
+    history: readonly LLMMessage[];
+    iteration: number;
+    maxIterations: number;
+    finalContent: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    turnStartMs: number;
+    runIdentity: MemoryIdentity;
+    newMessages: readonly LLMMessage[];
+    turnNumber: number;
+    contextTokensRemaining: number;
+    systemPromptInjections: readonly InjectionRecord[];
+    messagesInjections: readonly InjectionRecord[];
+    toolsInjections: readonly InjectionRecord[];
+    llmLatestContent: string;
+    llmLatestToolCalls: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }[];
+    pausedToolCallId: string;
+    pausedToolName: string;
+    pausedToolStartMs: number;
+    cumTokensInput: number;
+    cumTokensOutput: number;
+    cumEstimatedUsd: number;
+    costBudgetHit: boolean;
+    /** Active set output by InjectionEngine subflow each iteration —
+     *  POJO projections (no functions) suitable for scope round-trip. */
+    activeInjections: readonly ActiveInjection[];
+    /** IDs of LLM-activated Skills the LLM has activated this turn
+     *  (via the `read_skill` tool). InjectionEngine matches by id. */
+    activatedInjectionIds: readonly string[];
+    /** Most recent tool result — drives `on-tool-return` triggers. */
+    lastToolResult?: {
+        toolName: string;
+        result: string;
+    };
+    /** Tool schemas resolved by the tools slot subflow each iteration
+     *  (registry + injection-supplied). Used by callLLM. */
+    dynamicToolSchemas: readonly LLMToolSchema[];
+    /** Provider-agnostic cache markers emitted by CacheDecision subflow.
+     *  Cleared each iteration by the SkipCaching branch when the
+     *  CacheGate decides to skip (kill switch / hit-rate / churn). */
+    cacheMarkers: readonly CacheMarker[];
+    /** Global cache kill switch from `Agent.create({ caching: 'off' })`. */
+    cachingDisabled: boolean;
+    /** Running cache hit rate from recent iterations (0..1). Computed
+     *  by cacheRecorder (Phase 9); `undefined` until first metrics. */
+    recentHitRate: number | undefined;
+    /** Rolling window of active-skill IDs across recent iterations.
+     *  Maintained by the UpdateSkillHistory function stage; consumed
+     *  by CacheGate's skill-churn rule. */
+    skillHistory: readonly (string | undefined)[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,48 @@
+/**
+ * Agent validators — pure helper functions extracted from Agent.ts.
+ *
+ * These run at Agent construction time (eagerly, so misconfiguration
+ * fails fast at `.build()`) and during stage execution (safeStringify
+ * for tool-result formatting).
+ *
+ * Pure functions, no class state — extracted for readability and
+ * isolated testability. The Agent class imports + invokes these in
+ * its constructor and stage handlers.
+ */
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { Injection } from '../../lib/injection-engine/types.js';
+import type { ToolRegistryEntry } from '../tools.js';
+/**
+ * Validate that every memory definition has a unique id. Each memory
+ * writes to its own scope key (`memoryInjection_${id}`); duplicates
+ * silently overwrite, leading to data loss that's hard to debug.
+ *
+ * Throws on collision so `Agent.build()` fails fast at construction.
+ */
+export declare function validateMemoryIdUniqueness(memories: readonly MemoryDefinition[]): void;
+/**
+ * Clamp `maxIterations` to a safe range. The lower bound (1) prevents
+ * a 0-iteration agent (no LLM calls = no work); the upper bound (50)
+ * prevents runaway loops in misconfigured agents.
+ */
+export declare function clampIterations(n: number): number;
+/**
+ * Validate tool-name uniqueness across `.tool()`-registered tools +
+ * every Skill's `inject.tools[]`. The LLM dispatches by `tool.schema.name`
+ * (the wire format), so any collision silently shadows execution.
+ *
+ * Called eagerly in the Agent constructor so `Agent.build()` throws
+ * immediately, not on first `run()`.
+ *
+ * `read_skill` is reserved when ≥1 Skill is registered — collisions
+ * with consumer tools throw.
+ */
+export declare function validateToolNameUniqueness(registry: readonly ToolRegistryEntry[], injections: readonly Injection[]): void;
+/**
+ * JSON.stringify with circular-ref protection. Tool results are untrusted —
+ * a hostile/buggy tool returning a cyclic object must not crash the run.
+ * Falls back to '[unstringifiable: <reason>]' so the LLM still sees that
+ * the tool ran and produced something unusable.
+ */
+export declare function safeStringify(value: unknown): string;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAAQ,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAWtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAoEN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOpD"}

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

@@ -0,0 +1,76 @@
+/**
+ * CircuitBreaker — pure state-machine functions for the Nygard breaker
+ * pattern.
+ *
+ * Refactored from a class-with-instance-state to PURE FUNCTIONS that
+ * take a state record and return a new one. Reasons:
+ *
+ *   1. **No hidden runtime state.** Breaker state lives in scope where
+ *      it's visible to commitLog, narrative, and rules — the footprintjs
+ *      "everything in scope" principle. The closure used to be the
+ *      source of truth and scope held only a projection; now scope IS
+ *      the source of truth.
+ *
+ *   2. **Round-trippable across gate invocations.** Because state is a
+ *      plain record, gate's outputMapper writes it back to agent scope;
+ *      agent scope persists across the ReAct loop's many LLM-call gate
+ *      invocations; gate's inputMapper reads it back in for the next
+ *      call. Per-process persistence comes from the agent scope, not
+ *      from a closure that hides between runs.
+ *
+ *   3. **Distributable later.** A future v2.12 `BreakerStateStore`
+ *      adapter (Redis/DynamoDB) just needs to serialize/deserialize the
+ *      state record. No class instances to reconstruct.
+ *
+ *   4. **Testable in isolation.** Pure functions; no instance setup.
+ *
+ * Pattern: Nygard *Release It!* — three states (CLOSED → OPEN →
+ *          HALF-OPEN) with cooldown and probe-success thresholds.
+ */
+import type { CircuitBreakerConfig } from './types.js';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Plain serializable record holding one breaker's full state. */
+export interface BreakerState {
+    state: CircuitState;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    openedAt: number;
+    lastErrorMessage?: string;
+}
+/**
+ * Thrown by `assertAdmit()` when the breaker is OPEN and the cooldown
+ * window has not elapsed. The reliability gate stage catches this,
+ * classifies via `classifyError` → `'circuit-open'`, and lets the
+ * post-decide rules route on it.
+ */
+export declare class CircuitOpenError extends Error {
+    readonly code: "ERR_CIRCUIT_OPEN";
+    readonly cause: unknown;
+    readonly retryAfter: number;
+    constructor(providerName: string, lastErrorMessage: string | undefined, retryAfter: number);
+}
+/** Initial state for a freshly-CLOSED breaker. */
+export declare function initialBreakerState(): BreakerState;
+/**
+ * Decide whether to admit a call. Returns the (possibly-updated) state
+ * AND whether to admit. If OPEN and cooldown elapsed, transitions to
+ * HALF-OPEN and admits. Pure: caller must use the returned state.
+ *
+ * Usage in the gate stage:
+ * ```ts
+ * const { admitted, nextState } = admitCall(scope.breakerStates[name], config);
+ * scope.breakerStates[name] = nextState;
+ * if (!admitted) throw new CircuitOpenError(name, nextState.lastErrorMessage, ...);
+ * ```
+ */
+export declare function admitCall(state: BreakerState, config: CircuitBreakerConfig | undefined): {
+    admitted: boolean;
+    nextState: BreakerState;
+};
+/** Record a successful call. Returns the (possibly-updated) state. */
+export declare function recordSuccess(state: BreakerState, config: CircuitBreakerConfig | undefined): BreakerState;
+/** Record a failed call. Returns the (possibly-updated) state. */
+export declare function recordFailure(state: BreakerState, err: unknown, config: CircuitBreakerConfig | undefined): BreakerState;
+/** Compute the next probe time given a state + config. */
+export declare function nextProbeTime(state: BreakerState, config: CircuitBreakerConfig | undefined): number;
+//# sourceMappingURL=CircuitBreaker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/reliability/CircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,qBAA+B;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM;CAU3F;AAkBD,kDAAkD;AAClD,wBAAgB,mBAAmB,IAAI,YAAY,CAOlD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAchD;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,YAAY,CAsBd;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,YAAY,CAgCd;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,MAAM,CAER"}

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

@@ -0,0 +1,54 @@
+/**
+ * buildReliabilityGateChart — produces a footprintjs FlowChart that wraps
+ * an LLM call with rules-based reliability semantics, using the native
+ * `decide()` DSL via `addDeciderFunction` decider stages.
+ *
+ * The returned chart is mounted as a subflow in the agent's chart at
+ * Agent.build() time (only when reliability is configured). Inside the
+ * subflow:
+ *
+ *   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 subflow is mounted WITHOUT `propagateBreak: true`. Subflow $break is
+ * local — agent.ts adds a `TranslateFailFast` agent-level stage AFTER the
+ * subflow that reads scope.reliabilityFailKind and converts it into an
+ * agent-level `$break(reason)`. This split lets normal subflow exits
+ * (`ok`/`fallback`) leave the agent running while fail-fast stops it.
+ *
+ * Three-channel discipline preserved:
+ *   • SCOPE STATE  — failKind/failPayload/failReason mapped to parent via
+ *                    outputMapper; consumed by agent's 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;
+//# sourceMappingURL=buildReliabilityGateChart.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildReliabilityGateChart.d.ts","sourceRoot":"","sources":["../../../src/reliability/buildReliabilityGateChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAWzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,YAAY,CAAC;AAkFvF;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CA4S9E"}

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

@@ -0,0 +1,29 @@
+/**
+ * classifyError — pure function mapping a thrown error to one of the
+ * coarse `ReliabilityScope.errorKind` categories used by reliability rules.
+ *
+ * Centralized so rules read structured `errorKind` instead of doing
+ * regex on `error.message` themselves. Add new categories ONLY when a
+ * new rule needs to discriminate them — keep the taxonomy small.
+ *
+ * Categories:
+ *   • 'ok'             — no error (caller should pass `undefined` or omit)
+ *   • 'circuit-open'   — `CircuitOpenError` from the breaker layer
+ *   • 'rate-limit'     — HTTP 429 or vendor rate-limit signal
+ *   • '5xx-transient'  — HTTP 5xx, ETIMEDOUT, ECONNRESET, ECONNREFUSED
+ *   • 'schema-fail'    — `OutputSchemaError` from the schema validator
+ *   • 'unknown'        — anything else (default; still routable but
+ *                        consumers usually `'fail-fast'` on this)
+ */
+import type { ReliabilityScope } from './types.js';
+type ErrorKind = ReliabilityScope['errorKind'];
+/**
+ * Classify an error into a `ReliabilityScope['errorKind']` category.
+ *
+ * @param err - The thrown value. May be an Error, a vendor SDK error
+ *   shape with `.status`/`.code`, or anything else (`unknown` defaults).
+ * @returns the matching coarse category string.
+ */
+export declare function classifyError(err: unknown): ErrorKind;
+export {};
+//# sourceMappingURL=classifyError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classifyError.d.ts","sourceRoot":"","sources":["../../../src/reliability/classifyError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,KAAK,SAAS,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAU/C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CA8BrD"}

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

@@ -0,0 +1,34 @@
+/**
+ * Reliability — public surface for the v2.11.1 rules-based reliability
+ * subsystem. Internal-only helpers (CircuitBreaker class, classifyError,
+ * buildReliabilityGate) live in their own files; this barrel exports
+ * the consumer-facing types and the typed error.
+ *
+ * Consumer use:
+ * ```ts
+ * import { Agent } from 'agentfootprint';
+ * import type { ReliabilityRule, ReliabilityScope } from 'agentfootprint/reliability';
+ * import { ReliabilityFailFastError } from 'agentfootprint/reliability';
+ *
+ * const agent = Agent.create({...}).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' },
+ *   ],
+ * }).build();
+ *
+ * try {
+ *   await agent.run({ message: '...' });
+ * } catch (e) {
+ *   if (e instanceof ReliabilityFailFastError) {
+ *     console.log(e.kind, e.reason);
+ *   }
+ * }
+ * ```
+ */
+export type { CircuitBreakerConfig, ReliabilityConfig, ReliabilityDecision, ReliabilityFallbackFn, ReliabilityProvider, ReliabilityRule, ReliabilityScope, } from './types.js';
+export { ReliabilityFailFastError } from './types.js';
+export { CircuitOpenError, initialBreakerState, type BreakerState, type CircuitState, } from './CircuitBreaker.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/reliability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAKtD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC"}