agentfootprint 2.11.0 → 2.11.2

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

@@ -0,0 +1,91 @@
+/**
+ * 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 { typedEmit } from '../../../recorders/core/typedEmit.js';
+/**
+ * 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 function buildSeedStage(deps) {
+    return (scope) => {
+        const args = scope.$getArgs();
+        scope.userMessage = args.message;
+        // If `resumeOnError(...)` set the side channel, restore the
+        // checkpointed conversation history. The next iteration sees
+        // the prior messages and continues from the failure point.
+        // Always clear the field after reading so subsequent runs
+        // (without resumeOnError) start fresh.
+        const resumeHistory = deps.consumePendingResumeHistory();
+        if (resumeHistory && resumeHistory.length > 0) {
+            scope.history = [...resumeHistory];
+        }
+        else {
+            scope.history = [{ role: 'user', content: args.message }];
+        }
+        // Default identity uses the runId so multi-run isolation works
+        // without consumer changes; explicit identity (multi-tenant)
+        // overrides via `agent.run({ identity })`.
+        scope.runIdentity = args.identity ?? {
+            conversationId: deps.getCurrentRunId() ?? 'default',
+        };
+        scope.newMessages = [];
+        scope.turnNumber = 1;
+        // Permissive default — explicit cap will land when PricingTable
+        // gets a context-window field. Memory pickByBudget treats anything
+        // ≥ minimumTokens as "fits", so this just enables the budget path.
+        scope.contextTokensRemaining = 32_000;
+        scope.iteration = 1;
+        scope.maxIterations = deps.maxIterations;
+        scope.finalContent = '';
+        scope.totalInputTokens = 0;
+        scope.totalOutputTokens = 0;
+        scope.turnStartMs = Date.now();
+        scope.systemPromptInjections = [];
+        scope.messagesInjections = [];
+        scope.toolsInjections = [];
+        scope.llmLatestContent = '';
+        scope.llmLatestToolCalls = [];
+        scope.pausedToolCallId = '';
+        scope.pausedToolName = '';
+        scope.pausedToolStartMs = 0;
+        scope.cumTokensInput = 0;
+        scope.cumTokensOutput = 0;
+        scope.cumEstimatedUsd = 0;
+        scope.costBudgetHit = false;
+        scope.activeInjections = [];
+        scope.activatedInjectionIds = [];
+        scope.dynamicToolSchemas = deps.toolSchemas;
+        // Cache layer state (v2.6) — initialized to inert defaults.
+        // CacheDecision subflow populates `cacheMarkers` per iteration;
+        // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
+        // `recentHitRate`, `skillHistory`. Empty defaults mean the
+        // CacheGate falls through to 'apply-markers' on iter 1 (no
+        // history yet → no churn detected; recentHitRate undefined →
+        // hit-rate floor doesn't fire).
+        scope.cacheMarkers = [];
+        scope.cachingDisabled = deps.cachingDisabled;
+        scope.recentHitRate = undefined;
+        scope.skillHistory = [];
+        typedEmit(scope, 'agentfootprint.agent.turn_start', {
+            turnIndex: 0,
+            userPrompt: args.message,
+        });
+    };
+}
+//# sourceMappingURL=seed.js.map

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

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

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

@@ -0,0 +1,246 @@
+/**
+ * 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 { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { isPauseRequest } from '../../pause.js';
+import { safeStringify } from '../validators.js';
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+export function buildToolCallsHandler(deps) {
+    const { registryByName, externalToolProvider, permissionChecker } = deps;
+    return {
+        execute: async (scope) => {
+            const toolCalls = scope.llmLatestToolCalls;
+            const iteration = scope.iteration;
+            const newHistory = [...scope.history];
+            // ALWAYS push the assistant turn when there are tool calls — even
+            // if the content was empty — so providers (Anthropic, OpenAI) can
+            // round-trip the tool_use blocks via `LLMMessage.toolCalls`.
+            // Without this, the next iteration's request lacks the assistant
+            // turn that initiated the tool call, and the API rejects the
+            // following tool_result with "preceding tool_use missing".
+            if (scope.llmLatestContent || toolCalls.length > 0) {
+                newHistory.push({
+                    role: 'assistant',
+                    content: scope.llmLatestContent ?? '',
+                    ...(toolCalls.length > 0 && { toolCalls }),
+                });
+            }
+            // Resolve a tool by name, consulting the external ToolProvider
+            // if one was wired via `.toolProvider()` and the static
+            // registry doesn't carry the tool. The provider sees the same
+            // ctx the Tools slot used, so dispatch + visibility stay
+            // consistent within the iteration.
+            const lookupTool = (toolName) => {
+                const fromRegistry = registryByName.get(toolName);
+                if (fromRegistry)
+                    return fromRegistry;
+                if (!externalToolProvider)
+                    return undefined;
+                const activatedIds = scope.activatedInjectionIds ?? [];
+                const identity = scope.runIdentity;
+                const ctx = {
+                    iteration: scope.iteration,
+                    ...(activatedIds.length > 0 && {
+                        activeSkillId: activatedIds[activatedIds.length - 1],
+                    }),
+                    ...(identity && { identity }),
+                };
+                const visible = externalToolProvider.list(ctx);
+                return visible.find((t) => t.schema.name === toolName);
+            };
+            for (const tc of toolCalls) {
+                const tool = lookupTool(tc.name);
+                typedEmit(scope, 'agentfootprint.stream.tool_start', {
+                    toolName: tc.name,
+                    toolCallId: tc.id,
+                    args: tc.args,
+                    ...(toolCalls.length > 1 && { parallelCount: toolCalls.length }),
+                });
+                const startMs = Date.now();
+                let result;
+                let error;
+                // Permission gate — when a checker is configured, evaluate BEFORE
+                // executing the tool. Emits `permission.check` with the decision.
+                // On 'deny', the tool is not executed and its result is a
+                // synthetic denial string; on 'allow'/'gate_open', execution
+                // proceeds normally (the gate is informational — the consumer's
+                // checker is responsible for any gate-open side effects).
+                let denied = false;
+                if (permissionChecker) {
+                    try {
+                        const decision = await permissionChecker.check({
+                            capability: 'tool_call',
+                            actor: 'agent',
+                            target: tc.name,
+                            context: tc.args,
+                        });
+                        typedEmit(scope, 'agentfootprint.permission.check', {
+                            capability: 'tool_call',
+                            actor: 'agent',
+                            target: tc.name,
+                            result: decision.result,
+                            ...(decision.policyRuleId !== undefined && { policyRuleId: decision.policyRuleId }),
+                            ...(decision.rationale !== undefined && { rationale: decision.rationale }),
+                        });
+                        if (decision.result === 'deny') {
+                            denied = true;
+                            result = `[permission denied: ${decision.rationale ?? 'policy'}]`;
+                        }
+                    }
+                    catch (permErr) {
+                        // A checker that throws is treated as deny-by-default. The
+                        // denial message records the thrown error so consumers can
+                        // debug policy-adapter failures without losing the run.
+                        denied = true;
+                        const msg = permErr instanceof Error ? permErr.message : String(permErr);
+                        typedEmit(scope, 'agentfootprint.permission.check', {
+                            capability: 'tool_call',
+                            actor: 'agent',
+                            target: tc.name,
+                            result: 'deny',
+                            rationale: `permission-checker threw: ${msg}`,
+                        });
+                        result = `[permission denied: checker error: ${msg}]`;
+                    }
+                }
+                if (!denied) {
+                    try {
+                        if (!tool)
+                            throw new Error(`Unknown tool: ${tc.name}`);
+                        result = await tool.execute(tc.args, {
+                            toolCallId: tc.id,
+                            iteration,
+                        });
+                    }
+                    catch (err) {
+                        if (isPauseRequest(err)) {
+                            // Commit partial state so resume() can find history intact.
+                            scope.history = newHistory;
+                            scope.pausedToolCallId = tc.id;
+                            scope.pausedToolName = tc.name;
+                            scope.pausedToolStartMs = startMs;
+                            // Returning a defined value triggers footprintjs pause —
+                            // the returned object becomes the checkpoint's pauseData.
+                            return {
+                                toolCallId: tc.id,
+                                toolName: tc.name,
+                                ...(typeof err.data === 'object' && err.data !== null
+                                    ? err.data
+                                    : { data: err.data }),
+                            };
+                        }
+                        error = true;
+                        result = err instanceof Error ? err.message : String(err);
+                    }
+                }
+                const durationMs = Date.now() - startMs;
+                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                    toolCallId: tc.id,
+                    result,
+                    durationMs,
+                    ...(error === true && { error: true }),
+                });
+                const resultStr = typeof result === 'string' ? result : safeStringify(result);
+                newHistory.push({
+                    role: 'tool',
+                    content: resultStr,
+                    toolCallId: tc.id,
+                    toolName: tc.name,
+                });
+                // ── Dynamic ReAct wiring ───────────────────────────────
+                //
+                // (1) `lastToolResult` drives `on-tool-return` Injection
+                //     triggers — the InjectionEngine's NEXT pass will see
+                //     this and activate any matching Instructions.
+                scope.lastToolResult = { toolName: tc.name, result: resultStr };
+                // (2) `read_skill` is the auto-attached activation tool.
+                //     When the LLM calls it with a valid Skill id, append
+                //     to `activatedInjectionIds` so the InjectionEngine's
+                //     NEXT pass activates that Skill (lifetime: turn — stays
+                //     active until the turn ends).
+                if (tc.name === 'read_skill' && !error && !denied) {
+                    const requestedId = tc.args.id;
+                    if (typeof requestedId === 'string' && requestedId.length > 0) {
+                        const current = scope.activatedInjectionIds;
+                        if (!current.includes(requestedId)) {
+                            scope.activatedInjectionIds = [...current, requestedId];
+                        }
+                    }
+                }
+            }
+            scope.history = newHistory;
+            typedEmit(scope, 'agentfootprint.agent.iteration_end', {
+                turnIndex: 0,
+                iterIndex: iteration,
+                toolCallCount: toolCalls.length,
+                history: scope.history,
+            });
+            scope.iteration = iteration + 1;
+            return undefined; // explicit: no pause, flow continues to loopTo
+        },
+        resume: (scope, input) => {
+            // Consumer-supplied resume input becomes the paused tool's result.
+            // The subflow's pre-pause scope is restored automatically by
+            // footprintjs 4.17.0 via `checkpoint.subflowStates`, so
+            // `scope.history` and `scope.pausedToolCallId` read back cleanly
+            // across same-executor AND cross-executor resume.
+            const toolCallId = scope.pausedToolCallId;
+            const toolName = scope.pausedToolName;
+            const startMs = scope.pausedToolStartMs;
+            const resultStr = typeof input === 'string' ? input : safeStringify(input);
+            const newHistory = [
+                ...scope.history,
+                {
+                    role: 'tool',
+                    content: resultStr,
+                    toolCallId,
+                    toolName,
+                },
+            ];
+            scope.history = newHistory;
+            typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                toolCallId,
+                result: input,
+                durationMs: Date.now() - startMs,
+            });
+            const iteration = scope.iteration;
+            typedEmit(scope, 'agentfootprint.agent.iteration_end', {
+                turnIndex: 0,
+                iterIndex: iteration,
+                toolCallCount: 1,
+                history: scope.history,
+            });
+            scope.iteration = iteration + 1;
+            // Clear pause checkpoint fields.
+            scope.pausedToolCallId = '';
+            scope.pausedToolName = '';
+            scope.pausedToolStartMs = 0;
+        },
+    };
+}
+//# sourceMappingURL=toolCalls.js.map

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

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

package/dist/esm/core/agent/types.js

@@ -0,0 +1,11 @@
+/**
+ * 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).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/esm/core/agent/validators.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function validateMemoryIdUniqueness(memories) {
+    const seen = new Set();
+    for (const m of memories) {
+        if (seen.has(m.id)) {
+            throw new Error(`Agent: duplicate memory id '${m.id}'. Each memory needs a unique id to keep ` +
+                'its scope key (`memoryInjection_${id}`) collision-free.');
+        }
+        seen.add(m.id);
+    }
+}
+/**
+ * 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 function clampIterations(n) {
+    if (!Number.isInteger(n) || n < 1)
+        return 1;
+    if (n > 50)
+        return 50;
+    return n;
+}
+/**
+ * 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 function validateToolNameUniqueness(registry, injections) {
+    // Static registry: unique within itself. The Agent.tool() builder
+    // method already throws on per-call duplicates; this is the
+    // belt-and-suspenders check at build time.
+    const staticNames = new Set();
+    for (const entry of registry) {
+        if (staticNames.has(entry.name)) {
+            throw new Error(`Agent: duplicate tool name '${entry.name}' in .tool() registry. ` +
+                `Tool names must be unique within the static registry.`);
+        }
+        staticNames.add(entry.name);
+    }
+    // `read_skill` is reserved when any Skill is registered. Collisions
+    // with consumer-supplied tools break the auto-attach path.
+    const skills = injections.filter((i) => i.flavor === 'skill');
+    if (skills.length > 0 && staticNames.has('read_skill')) {
+        throw new Error(`Agent: tool name 'read_skill' is reserved when ≥1 Skill is registered. ` +
+            `Rename your custom 'read_skill' tool or unregister it.`);
+    }
+    // Per-skill check: a skill's `inject.tools` array must be internally
+    // unique (no duplicate names within the same skill — that's a
+    // skill authoring bug). Across skills, sharing a Tool reference is
+    // EXPECTED and supported — common tools (e.g., a `flogi_lookup`
+    // used by multiple investigation skills) appear in multiple skills'
+    // tool arrays. Only one skill is active at a time (or, when several
+    // are active, deduped by name + reference at runtime). Sharing the
+    // same Tool object across skills is the supported pattern; sharing
+    // a Tool NAME with a DIFFERENT execute function is the actual bug —
+    // we detect that here too.
+    const seenByName = new Map();
+    for (const skill of skills) {
+        const intraSkill = new Set();
+        for (const tool of skill.inject.tools ?? []) {
+            const name = tool.schema.name;
+            if (intraSkill.has(name)) {
+                throw new Error(`Agent: skill '${skill.id}' lists tool '${name}' more than once in its ` +
+                    `inject.tools array. Each skill's tools must be unique within itself.`);
+            }
+            intraSkill.add(name);
+            // Skill tools collide with the static .tool() registry → ambiguous dispatch
+            if (staticNames.has(name)) {
+                throw new Error(`Agent: skill '${skill.id}' tool '${name}' collides with the static .tool() ` +
+                    `registry. Either rename the skill's tool or remove the static registration.`);
+            }
+            // Same name across skills with DIFFERENT Tool objects = ambiguous when
+            // both skills active. Same name + SAME Tool reference = supported sharing.
+            const prior = seenByName.get(name);
+            if (prior && prior !== tool) {
+                throw new Error(`Agent: tool name '${name}' is declared by multiple skills with different ` +
+                    `Tool implementations. Skills MAY share the SAME Tool reference across ` +
+                    `their inject.tools arrays (deduped at dispatch); they may NOT register ` +
+                    `different functions under the same name (ambiguous dispatch).`);
+            }
+            seenByName.set(name, tool);
+        }
+    }
+}
+/**
+ * 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 function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return `[unstringifiable: ${reason}]`;
+    }
+}
+//# sourceMappingURL=validators.js.map

package/dist/esm/core/agent/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../../../src/core/agent/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAqC;IAC9E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,+BAA+B,CAAC,CAAC,EAAE,2CAA2C;gBAC5E,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAsC,EACtC,UAAgC;IAEhC,kEAAkE;IAClE,4DAA4D;IAC5D,2CAA2C;IAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,+BAA+B,KAAK,CAAC,IAAI,yBAAyB;gBAChE,uDAAuD,CAC1D,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,oEAAoE;IACpE,2DAA2D;IAC3D,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,8DAA8D;IAC9D,mEAAmE;IACnE,gEAAgE;IAChE,oEAAoE;IACpE,oEAAoE;IACpE,mEAAmE;IACnE,mEAAmE;IACnE,oEAAoE;IACpE,2BAA2B;IAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAgB,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAC9B,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,iBAAiB,KAAK,CAAC,EAAE,iBAAiB,IAAI,0BAA0B;oBACtE,sEAAsE,CACzE,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrB,4EAA4E;YAC5E,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,iBAAiB,KAAK,CAAC,EAAE,WAAW,IAAI,qCAAqC;oBAC3E,6EAA6E,CAChF,CAAC;YACJ,CAAC;YACD,uEAAuE;YACvE,2EAA2E;YAC3E,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,IAAI,KAAK,KAAM,IAAwB,EAAE,CAAC;gBACjD,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,kDAAkD;oBACzE,wEAAwE;oBACxE,yEAAyE;oBACzE,+DAA+D,CAClE,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAuB,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,qBAAqB,MAAM,GAAG,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/esm/reliability/CircuitBreaker.js

@@ -0,0 +1,156 @@
+/**
+ * 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.
+ */
+/**
+ * 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 class CircuitOpenError extends Error {
+    code = 'ERR_CIRCUIT_OPEN';
+    cause;
+    retryAfter;
+    constructor(providerName, lastErrorMessage, retryAfter) {
+        super(`[${providerName}] circuit breaker is OPEN — failing fast (next probe at ${new Date(retryAfter).toISOString()}). Underlying error: ${lastErrorMessage ?? 'unknown'}`);
+        this.name = 'CircuitOpenError';
+        this.cause = lastErrorMessage;
+        this.retryAfter = retryAfter;
+    }
+}
+// ─── Defaults ────────────────────────────────────────────────────────
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_COOLDOWN_MS = 30_000;
+const DEFAULT_HALF_OPEN_SUCCESS_THRESHOLD = 2;
+function defaultShouldCount(error) {
+    // User cancellations don't indicate vendor health
+    const e = error;
+    if (e?.name === 'AbortError')
+        return false;
+    if (e?.code === 'ABORT_ERR')
+        return false;
+    return true;
+}
+// ─── Constructors ────────────────────────────────────────────────────
+/** Initial state for a freshly-CLOSED breaker. */
+export function initialBreakerState() {
+    return {
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        openedAt: 0,
+    };
+}
+// ─── Pure transitions ────────────────────────────────────────────────
+/**
+ * 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 function admitCall(state, config) {
+    const cooldownMs = config?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    if (state.state === 'closed' || state.state === 'half-open') {
+        return { admitted: true, nextState: state };
+    }
+    // OPEN — check cooldown
+    if (Date.now() - state.openedAt >= cooldownMs) {
+        return {
+            admitted: true,
+            nextState: { ...state, state: 'half-open', consecutiveSuccesses: 0 },
+        };
+    }
+    return { admitted: false, nextState: state };
+}
+/** Record a successful call. Returns the (possibly-updated) state. */
+export function recordSuccess(state, config) {
+    const halfOpenSuccessThreshold = config?.halfOpenSuccessThreshold ?? DEFAULT_HALF_OPEN_SUCCESS_THRESHOLD;
+    if (state.state === 'half-open') {
+        const consecutiveSuccesses = state.consecutiveSuccesses + 1;
+        if (consecutiveSuccesses >= halfOpenSuccessThreshold) {
+            // Probe successes met threshold → fully CLOSE
+            return {
+                state: 'closed',
+                consecutiveFailures: 0,
+                consecutiveSuccesses: 0,
+                openedAt: 0,
+            };
+        }
+        return { ...state, consecutiveSuccesses };
+    }
+    if (state.state === 'closed') {
+        // Reset failure counter on success
+        return state.consecutiveFailures === 0 ? state : { ...state, consecutiveFailures: 0 };
+    }
+    return state;
+}
+/** Record a failed call. Returns the (possibly-updated) state. */
+export function recordFailure(state, err, config) {
+    const shouldCount = config?.shouldCount ?? defaultShouldCount;
+    if (!shouldCount(err))
+        return state;
+    const failureThreshold = config?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+    const lastErrorMessage = err?.message ?? String(err);
+    if (state.state === 'half-open') {
+        // Probe failed → re-OPEN
+        return {
+            state: 'open',
+            consecutiveFailures: state.consecutiveFailures,
+            consecutiveSuccesses: 0,
+            openedAt: Date.now(),
+            lastErrorMessage,
+        };
+    }
+    if (state.state === 'closed') {
+        const consecutiveFailures = state.consecutiveFailures + 1;
+        if (consecutiveFailures >= failureThreshold) {
+            return {
+                state: 'open',
+                consecutiveFailures,
+                consecutiveSuccesses: 0,
+                openedAt: Date.now(),
+                lastErrorMessage,
+            };
+        }
+        return { ...state, consecutiveFailures, lastErrorMessage };
+    }
+    // OPEN: leave state unchanged (admitCall handles cooldown)
+    return state;
+}
+/** Compute the next probe time given a state + config. */
+export function nextProbeTime(state, config) {
+    return state.openedAt + (config?.cooldownMs ?? DEFAULT_COOLDOWN_MS);
+}
+//# sourceMappingURL=CircuitBreaker.js.map