agentfootprint 6.43.0 → 6.45.0

package/dist/esm/adapters/types.d.ts

@@ -0,0 +1,378 @@
+/**
+ * adapters/types — the Ports of the hexagonal architecture.
+ *
+ * Pattern: Adapter (GoF, Design Patterns ch. 4) + Ports-and-Adapters
+ *          (Cockburn, 2005).
+ * Role:    Contracts for every external dependency the library reaches for:
+ *          LLM providers, memory stores, context sources, embeddings,
+ *          guardrails, policy engines, pricing tables.
+ * Emits:   N/A (interfaces only).
+ *
+ * Concrete adapters (AnthropicProvider, PineconeStore, LlamaGuardDetector,
+ * ...) implement these contracts. `core/` and `core-flow/` depend only on
+ * these interfaces — never on concrete adapters.
+ */
+import type { ContextRole, ContextSlot, ContextSource } from '../events/types.js';
+import type { ThinkingBlock } from '../thinking/types.js';
+export interface LLMMessage {
+    readonly role: ContextRole;
+    readonly content: string;
+    /** For `role: 'tool'` — the tool_use id this result corresponds to. */
+    readonly toolCallId?: string;
+    /** For `role: 'tool'` — the tool name this result corresponds to. */
+    readonly toolName?: string;
+    /**
+     * For `role: 'assistant'` only — the tool calls the LLM requested in this
+     * turn. Required for providers (Anthropic, OpenAI) that need to round-trip
+     * tool_use blocks across iterations: when the next `complete()` includes
+     * a `role: 'tool'` message, the provider reconstructs the matching
+     * `tool_use` block on the previous assistant turn from this field.
+     * Empty array on text-only turns; undefined for non-assistant roles.
+     */
+    readonly toolCalls?: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }[];
+    /**
+     * v2.14 — Thinking blocks emitted by the LLM on assistant turns.
+     *
+     * Required for Anthropic extended-thinking + tool-use flows: signed
+     * blocks MUST be echoed BYTE-EXACT in subsequent assistant turns or
+     * Anthropic's API rejects with 400. The framework persists blocks
+     * here so the AnthropicProvider's serializer (Phase 4b) can restore
+     * them on the next request.
+     *
+     * **Persistence model — DIFFERENT from `ephemeral`:**
+     *   - `ephemeral` messages: NOT persisted to scope.history
+     *   - `thinkingBlocks`: PERSISTED (required for signature round-trip)
+     *
+     * Visible to recorders + audit by default. Use
+     * `RedactionPolicy.thinkingPatterns` (Phase 3) to scrub sensitive
+     * reasoning content before audit-log adapters fire.
+     *
+     * Empty array OR undefined when no thinking is present (most calls).
+     */
+    readonly thinkingBlocks?: readonly ThinkingBlock[];
+    /**
+     * v2.13 — PERSISTENCE flag (NOT a visibility flag). When `true`:
+     *   • The message IS sent to the LLM as part of the next request
+     *     (visible to the model, counts toward its context window).
+     *   • The message is OBSERVABLE via narrative/recorders/audit log
+     *     (visible to humans for debugging + forensics).
+     *   • The message is NOT persisted to `scope.history` after the gate
+     *     loop that produced it completes — long-term memory writes,
+     *     `getNarrative()` snapshots, and downstream consumers see only
+     *     non-ephemeral messages.
+     *
+     * Use case: Instructor-style schema retry. The reliability gate
+     * appends `{ role: 'user', content: feedbackForLLM, ephemeral: true }`
+     * before retry — the LLM sees the validation feedback for the next
+     * call, but the conversation history (and any memory persistence
+     * downstream) sees only the final accepted exchange.
+     *
+     * Audit-trail safety: ephemeral DOES NOT mean invisible to security
+     * review. `getNarrative()`, recorders, and the typed-event stream all
+     * see ephemeral messages; only the persistent conversation log filters
+     * them out. An attacker cannot use the ephemeral marker to construct
+     * audit-invisible prompts.
+     */
+    readonly ephemeral?: boolean;
+}
+export interface LLMToolSchema {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+export interface LLMRequest {
+    readonly systemPrompt?: string;
+    readonly messages: readonly LLMMessage[];
+    readonly tools?: readonly LLMToolSchema[];
+    readonly model: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly stop?: readonly string[];
+    readonly signal?: AbortSignal;
+    /**
+     * Cache markers (v2.6+) — provider-agnostic prefix-cache hints
+     * populated by `CacheStrategy.prepareRequest` after the agent's
+     * CacheGate decider routes to `apply-markers`. Each marker
+     * identifies a cacheable prefix in `system` / `tools` / `messages`.
+     *
+     * Providers that support caching (Anthropic, Bedrock-Claude) read
+     * this field and translate to their wire format. Providers without
+     * cache support (OpenAI auto-cache, Mock, NoOp) ignore it.
+     */
+    readonly cacheMarkers?: readonly import('../cache/types.js').CacheMarker[];
+    /**
+     * v2.14 — request the LLM emit reasoning/thinking content on this call.
+     *
+     * Activation: presence of this field tells the provider to ASK for
+     * thinking. Anthropic translates to `thinking: { type: 'enabled',
+     * budget_tokens: budget }` on the wire. OpenAI ignores (o1/o3
+     * thinking is selected at the model id level, not per-request).
+     *
+     * `budget` is the maximum reasoning tokens the model may spend.
+     * Anthropic requires it; recommended range 1024-32000 for
+     * claude-sonnet-4-5 / opus-4-5. Models that don't support extended
+     * thinking will reject the request with HTTP 400 — pick a supported
+     * model when setting this field.
+     *
+     * Independent from `LLMMessage.thinkingBlocks` (the response side):
+     *   - `request.thinking` = activation (consumer ASKS for thinking)
+     *   - `message.thinkingBlocks` = round-trip (consumer ECHOES prior
+     *     assistant turn's signed blocks back to the model)
+     *
+     * Set via `AgentBuilder.thinking({ budget })` — applied to every
+     * LLM call the agent makes. Leave undefined to call without thinking
+     * (the v2.13 default).
+     */
+    readonly thinking?: {
+        readonly budget: number;
+    };
+}
+export interface LLMResponse {
+    readonly content: string;
+    readonly toolCalls: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }[];
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+        /**
+         * v2.14 — count of reasoning/thinking tokens used by the model.
+         * Distinct from `output` (which is visible-content tokens).
+         *
+         * Semantics:
+         *   - `undefined` — provider doesn't expose / no thinking enabled
+         *                   on this call / call without extended thinking
+         *   - `0`         — thinking enabled but model produced no
+         *                   thinking tokens this call
+         *   - `>0`        — actual reasoning token count (billing-relevant
+         *                   for both Anthropic extended thinking and
+         *                   OpenAI o1/o3 reasoning_tokens)
+         *
+         * Cost dashboards reading `cost.tick` events should track this
+         * separately from `output` — pricing differs (Anthropic charges
+         * extended thinking at output rates; OpenAI o1/o3 reasoning tokens
+         * are billed as a separate line item).
+         */
+        readonly thinking?: number;
+    };
+    readonly stopReason: string;
+    readonly providerRef?: string;
+    /**
+     * v2.14 — Provider-specific raw thinking data, opaque to the
+     * framework. Providers that support extended thinking populate this
+     * with their native shape (Anthropic: array of `{type, thinking,
+     * signature}` blocks; OpenAI: `reasoning_summary` value; custom:
+     * whatever the provider emits). The framework hands this to a
+     * configured `ThinkingHandler.normalize(rawThinking)` to produce
+     * the normalized `ThinkingBlock[]` that lands on
+     * `LLMMessage.thinkingBlocks`.
+     *
+     * Undefined when the provider has no thinking content for this call
+     * — most calls (gpt-4o, claude without extended thinking enabled,
+     * etc.). The thinking subflow's stage early-returns in this case.
+     */
+    readonly rawThinking?: unknown;
+}
+export interface LLMChunk {
+    readonly tokenIndex: number;
+    /** Token text. Empty for the terminal chunk (`done: true`). */
+    readonly content: string;
+    /** True only for the final chunk in a stream. */
+    readonly done: boolean;
+    /**
+     * Authoritative response payload, populated ONLY on the final chunk
+     * (`done: true`). Carries `toolCalls`, `usage`, `stopReason` — the
+     * fields that drive the ReAct loop. The `content` mirrors the
+     * concatenation of all non-terminal chunks; consumers can use
+     * either source.
+     *
+     * Streaming providers SHOULD populate this. Older providers that
+     * yield only text and end with `done: true` (no `response`) are
+     * still supported — Agent falls back to `complete()` for the
+     * authoritative payload in that case.
+     */
+    readonly response?: LLMResponse;
+    /**
+     * v2.14 — streaming thinking-content tokens. Parallel to `content`
+     * but for the model's reasoning chain rather than visible output.
+     * Set on chunks that carry thinking deltas (Anthropic emits these
+     * via `content_block_delta` events with `delta.type === 'thinking_delta'`);
+     * undefined or empty on chunks that carry only visible-content tokens.
+     *
+     * Frameworks: this field drives `agentfootprint.stream.thinking_delta`
+     * events when a `ThinkingHandler.parseChunk()` returns one. Consumers
+     * who want to render thinking-as-it-streams subscribe to that event.
+     *
+     * Default consumer behavior: thinking tokens are not surfaced to end
+     * users unless a consumer explicitly subscribes to the
+     * `agentfootprint.stream.thinking_delta` event (or renders it through a
+     * live-status strategy).
+     */
+    readonly thinkingDelta?: string;
+}
+export interface LLMProvider {
+    readonly name: string;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream?(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export interface ResolveCtx {
+    readonly userMessage: string;
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+    readonly availableBudgetTokens: number;
+    readonly signal?: AbortSignal;
+}
+export interface ContextContribution {
+    readonly contentSummary: string;
+    readonly rawContent?: string;
+    readonly score?: number;
+    readonly rank?: number;
+    readonly asRole?: ContextRole;
+    readonly sectionTag?: string;
+    readonly reason: string;
+}
+export interface ContextSourceAdapter {
+    readonly id: string;
+    readonly targetSlot: ContextSlot;
+    readonly source: ContextSource;
+    resolve(ctx: ResolveCtx): Promise<readonly ContextContribution[]>;
+}
+export interface EmbeddingProvider {
+    readonly name: string;
+    readonly dimension: number;
+    embed(inputs: readonly string[], kind: 'query' | 'document'): Promise<number[][]>;
+}
+export interface RiskContext {
+    readonly slot?: ContextSlot;
+    readonly source?: ContextSource;
+    readonly turnIndex?: number;
+    readonly iterIndex?: number;
+}
+export interface RiskResult {
+    readonly flagged: boolean;
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly category: 'pii' | 'prompt_injection' | 'runaway_loop' | 'cost_overrun' | 'hallucination_flag';
+    readonly evidence: Readonly<Record<string, unknown>>;
+    readonly suggestedAction: 'warn' | 'redact' | 'abort';
+}
+export interface RiskDetector {
+    readonly name: string;
+    check(content: string, context: RiskContext): Promise<RiskResult>;
+}
+/**
+ * One entry in the in-flight tool-call sequence delivered to
+ * `PermissionChecker.check()` since v2.12. Lets sequence-aware
+ * policies (exfil chain detection, idempotency limits, cost guards)
+ * inspect what the agent has already dispatched this run.
+ *
+ * Derived from `scope.history` at check time — single source of truth,
+ * survives `agent.resumeOnError(checkpoint)` correctly.
+ */
+export interface ToolCallEntry {
+    /** Tool name dispatched. */
+    readonly name: string;
+    /** Tool args passed to `tool.execute(args, ctx)`. */
+    readonly args: Readonly<Record<string, unknown>> | undefined;
+    /** ReAct iteration the call was dispatched on. */
+    readonly iteration: number;
+    /**
+     * Optional source identifier — `'local'` for tools registered via
+     * `.tool(...)` / `staticTools(...)`, or the `ToolProvider.id` for
+     * tools resolved through a `discoveryProvider`. Lets cross-hub
+     * exfil rules match on origin, not just name.
+     */
+    readonly providerId?: string;
+}
+export interface PermissionRequest {
+    readonly capability: 'tool_call' | 'memory_read' | 'memory_write' | 'external_net' | 'user_data';
+    readonly actor: string;
+    readonly target?: string;
+    readonly context?: Readonly<Record<string, unknown>>;
+    /**
+     * v2.12 — Sequence of tool calls already dispatched this run, in
+     * call order. EMPTY for non-`tool_call` capabilities. Sequence-aware
+     * policies (forbidden chains, idempotency limits) read this to make
+     * decisions that single-call governance cannot.
+     */
+    readonly sequence?: readonly ToolCallEntry[];
+    /**
+     * v2.12 — Full conversation history at check time. Lets policies
+     * inspect prior assistant content / tool results without maintaining
+     * parallel state via event subscription.
+     */
+    readonly history?: readonly LLMMessage[];
+    /**
+     * v2.12 — Current ReAct iteration (1-based). Lets policies fire
+     * different rules per iteration without external counters.
+     */
+    readonly iteration?: number;
+    /**
+     * v2.12 — Caller identity from `agent.run({ identity })`. Permission
+     * predicates can role-check on `identity.principal` / `identity.tenant`.
+     */
+    readonly identity?: {
+        readonly tenant?: string;
+        readonly principal?: string;
+        readonly conversationId: string;
+    };
+    /**
+     * v2.12 — Optional abort signal propagated from `agent.run({ env: { signal } })`.
+     * Async checkers (Redis lookups, hub-backed allowlists) MUST honor this
+     * — when the agent run is cancelled, in-flight checks should abort.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * v2.12 — content shape mirroring `LLMMessage.content`. Future-compatible
+ * with multi-modal `tool_result` blocks once `LLMMessage` widens.
+ */
+export type ToolResultContent = string;
+export interface PermissionDecision {
+    /**
+     * v2.12 — `'halt'` is NEW. Terminates the run cleanly with a typed
+     * `PolicyHaltError`. The framework writes a synthetic `tool_result`
+     * (using `tellLLM`) to `scope.history` BEFORE throwing, so:
+     *   • Anthropic / OpenAI tool_use ↔ tool_result pairing is satisfied
+     *   • The conversation history is consistent for `resumeOnError`
+     *   • Lens / `getNarrative()` shows what the LLM was told
+     *
+     * `'deny'` keeps existing semantics: synthetic tool_result + LLM
+     * continues and can pick differently.
+     */
+    readonly result: 'allow' | 'deny' | 'halt' | 'gate_open';
+    readonly policyRuleId?: string;
+    readonly rationale?: string;
+    readonly gateId?: string;
+    /**
+     * v2.12 — telemetry tag (machine-readable, stable across versions).
+     * Surfaces on `agentfootprint.permission.halt.reason` for routing
+     * alerts (e.g. `'security:exfiltration'` → PagerDuty,
+     * `'cost:context-bloat'` → Slack channel).
+     */
+    readonly reason?: string;
+    /**
+     * v2.12 — content delivered to the LLM as the synthetic `tool_result`
+     * on `'deny'` and `'halt'`. When omitted, defaults to a deliberately
+     * generic `"Tool '${name}' is not available in this context."` —
+     * NEVER falls back to `reason` (which is telemetry, not user-facing).
+     */
+    readonly tellLLM?: ToolResultContent;
+}
+export interface PermissionChecker {
+    readonly name: string;
+    check(request: PermissionRequest): Promise<PermissionDecision> | PermissionDecision;
+}
+export type TokenKind = 'input' | 'output' | 'cacheRead' | 'cacheWrite';
+export interface PricingTable {
+    readonly name: string;
+    /** USD per ONE token for the given model+kind. */
+    pricePerToken(model: string, kind: TokenKind): number;
+}

package/dist/esm/bridge/eventMeta.d.ts

@@ -0,0 +1,59 @@
+/**
+ * eventMeta — build EventMeta from a footprintjs TraversalContext.
+ *
+ * Pattern: Adapter (GoF) — translates footprintjs's per-stage context into
+ *          agentfootprint's per-event metadata shape.
+ * Role:    Used by every core recorder to attach meta to emitted events.
+ * Emits:   N/A (helper only).
+ */
+import type { TraversalContext } from 'footprintjs';
+import type { EventMeta } from '../events/types.js';
+/**
+ * Minimal "stage origin" shape — the common subset of footprintjs's
+ * TraversalContext (from FlowRecorder events), RecorderContext (from
+ * Recorder data-flow events), and EmitEvent (from EmitRecorder).
+ *
+ * Note: `subflowPath` type varies across footprintjs event shapes:
+ *   - TraversalContext.subflowPath → `string | undefined` (/-separated)
+ *   - EmitEvent.subflowPath        → `readonly string[]`
+ *   - RecorderContext              → N/A (derived from runtimeStageId)
+ *
+ * We accept both shapes and normalize inside `buildEventMeta`.
+ */
+export interface StageOrigin {
+    readonly runtimeStageId?: string;
+    readonly subflowPath?: string | readonly string[];
+}
+export interface RunContext {
+    /** Millisecond wall-clock timestamp when the run started. */
+    readonly runStartMs: number;
+    /** Unique run id (demultiplex concurrent runs sharing one dispatcher). */
+    readonly runId: string;
+    /** Optional OTEL trace id forwarded from executor.run({ env: { traceId } }). */
+    readonly traceId?: string;
+    /** Optional correlation id for cross-event tying (retrieval→injection→LLM). */
+    readonly correlationId?: string;
+    /** Composition ancestry path (e.g. ['Sequence:bot', 'Agent:classify']). */
+    readonly compositionPath: readonly string[];
+    /** Optional turn/iter indices from agent runtime. */
+    readonly turnIndex?: number;
+    readonly iterIndex?: number;
+}
+/**
+ * Build an EventMeta from a stage origin + run-level context.
+ *
+ * Accepts footprintjs's TraversalContext (FlowRecorder events), RecorderContext
+ * (WriteEvent / CommitEvent / etc.), or a bare StageOrigin. When the origin
+ * has no runtimeStageId (rare — manual emit during tests), the meta degrades
+ * gracefully to 'unknown#0'.
+ */
+export declare function buildEventMeta(origin: StageOrigin | TraversalContext | undefined, run: RunContext): EventMeta;
+/**
+ * Parse footprintjs's `/`-separated subflow path into a readonly array.
+ *
+ * The source of truth for runtimeStageId parsing lives in footprintjs at
+ * `footprintjs/trace::parseRuntimeStageId`. We only need the path-split
+ * convenience here; the `/` separator is stable across footprintjs
+ * versions (covered by their `parseRuntimeStageId` tests).
+ */
+export declare function parseSubflowPath(raw: string | undefined): readonly string[];

package/dist/esm/cache/CacheDecisionSubflow.d.ts

@@ -0,0 +1,85 @@
+/**
+ * CacheDecision subflow — provider-agnostic translation from
+ * `activeInjections + DSL directives` → `CacheMarker[]`.
+ *
+ * This is the core "policy → markers" Lego layer. It runs every
+ * iteration (after slot subflows produce their output, before the
+ * CacheGate decider). Pure transform: no IO, no LLM calls, no
+ * provider knowledge.
+ *
+ * Algorithm:
+ *   1. Build a `CachePolicyContext` from agent state
+ *   2. For each injection in `activeInjections`, evaluate its
+ *      `metadata.cache` directive against the context → cacheable boolean
+ *   3. For each slot (system / tools / messages):
+ *      a. Walk the slot's contributions in order
+ *      b. Find the LAST index that's contiguous-from-start cacheable
+ *      c. Emit one CacheMarker at that boundary if any cacheable
+ *
+ * Each marker is provider-agnostic. Provider strategy translates
+ * to wire format in Phase 6+.
+ *
+ * Special case — base system prompt: the agent's
+ * `agent.getSystemPromptCachePolicy()` value is folded in at index 0
+ * of the system slot. Always-on injections (Steering / Fact /
+ * always-active rules) follow.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { CacheMarker, CachePolicy, CachePolicyContext } from './types.js';
+import type { Injection } from '../lib/injection-engine/types.js';
+/**
+ * Subflow scope state. Set via inputMapper from the agent's parent
+ * scope; produces `cacheMarkers` consumed by the BuildLLMRequest stage.
+ */
+export interface CacheDecisionState {
+    readonly activeInjections: readonly Injection[];
+    readonly iteration: number;
+    readonly maxIterations: number;
+    readonly userMessage: string;
+    readonly lastToolName?: string;
+    /**
+     * Cumulative input tokens spent across all LLM calls in THIS
+     * `agent.run()` invocation only. Resets at the start of each turn
+     * (each `agent.run()` call). Predicates can use this for budget-
+     * aware cache invalidation (e.g., "flush cache after 50K tokens").
+     */
+    readonly cumulativeInputTokens: number;
+    /**
+     * Base system prompt's cache policy (from
+     * `agent.getSystemPromptCachePolicy()`). Folded in at index 0 of
+     * the system slot's cache evaluation, ahead of any always-on
+     * injections.
+     */
+    readonly systemPromptCachePolicy: CachePolicy;
+    /** Global kill switch. When `true`, subflow emits zero markers. */
+    readonly cachingDisabled: boolean;
+    cacheMarkers: readonly CacheMarker[];
+}
+/**
+ * Evaluate a `CachePolicy` against the current context.
+ * Returns `true` if the policy says THIS iteration's content is cacheable.
+ */
+export declare function evaluateCachePolicy(policy: CachePolicy, ctx: CachePolicyContext): boolean;
+/**
+ * Identify which slots an injection contributes to. An injection can
+ * target multiple slots simultaneously (Skills target both system +
+ * tools); we visit each contributing slot independently.
+ */
+export declare function injectionTargetSlots(injection: Injection): ReadonlyArray<'system' | 'tools' | 'messages'>;
+/**
+ * Pure transform: state → markers. Exported so tests can exercise
+ * the algorithm directly without the FlowChartExecutor ceremony of
+ * mounting the subflow as a child of a parent chart.
+ *
+ * The subflow body (`decide` below) is a thin wrapper that pulls
+ * state from scope and delegates here.
+ */
+export declare function computeCacheMarkers(state: Omit<CacheDecisionState, 'cacheMarkers'>): readonly CacheMarker[];
+/**
+ * The decision stage function. Thin scope-binding wrapper around
+ * `computeCacheMarkers`. Exported so it can serve as the ROOT stage of
+ * the `sf-cache` subflow (a chart cannot start with a nested subflow),
+ * while `cacheDecisionSubflow` below still wraps the SAME function for
+ * standalone use — no logic duplication.
+ */
+export declare function decideCacheMarkers(scope: TypedScope<CacheDecisionState>): void;

package/dist/esm/cache/CacheGateDecider.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CacheGate — runtime decider that gates cache-marker application.
+ *
+ * Runs every iteration AFTER the CacheDecision subflow produces
+ * `scope.cacheMarkers` and BEFORE the BuildLLMRequest stage applies
+ * them. Three rules can fall through to "no-markers" (skip caching);
+ * default branch is "apply-markers" (proceed with caching).
+ *
+ * Why a decider stage and not a function: footprintjs's `decide()`
+ * captures evidence on `FlowRecorder.onDecision` natively. The
+ * `cacheRecorder()` (Phase 9) reads
+ * `event.evidence.rules.find(r => r.matched).inputs[]` to surface
+ * WHY caching was applied or skipped each iter. Same channel
+ * footprintjs uses for every other decision; same renderer in Lens.
+ *
+ * Three rules (evaluated top-down; first match wins):
+ *   1. Kill switch — `Agent.create({ caching: 'off' })` was set
+ *   2. Hit-rate floor — recent hit rate < 30%; cache writes outpacing
+ *      reads, auto-disable to avoid the cache-write penalty
+ *   3. Skill churn — active skills changing too rapidly for caching
+ *      to amortize (Anthropic LLM expert's concern from Phase 4 review)
+ *
+ * Default branch (no rule matches): `'apply-markers'`.
+ */
+import { type DecisionResult, type TypedScope } from 'footprintjs';
+/**
+ * Subset of agent scope state the CacheGate decider reads.
+ * Phase 6 wires these keys into the agent's main chart.
+ */
+export interface CacheGateState {
+    /**
+     * Global kill switch. When `true`, decider skips caching
+     * unconditionally. Set via `Agent.create({ caching: 'off' })`.
+     */
+    readonly cachingDisabled: boolean;
+    /**
+     * Running cache hit rate from the last N iterations (0..1).
+     * `undefined` when no cache events have fired yet (e.g., iter 1 of
+     * the first turn — no history). The cacheRecorder (Phase 9)
+     * computes this from `CacheMetrics` events.
+     */
+    readonly recentHitRate: number | undefined;
+    /**
+     * Rolling window of active-skill IDs across recent iterations,
+     * one per iteration (latest LAST). Maintained by the
+     * UpdateSkillHistory function stage (Phase 6 mount).
+     *
+     * `undefined` entry = no skill active that iteration.
+     */
+    readonly skillHistory: readonly (string | undefined)[];
+}
+/**
+ * Hit-rate floor below which we auto-disable caching. The 30% number
+ * is calibrated for Anthropic's pricing: cache write costs +25%
+ * premium, cache read costs 90% off. Break-even at ~25% hit rate.
+ * 30% gives a buffer; below that we're losing money on writes that
+ * never recoup.
+ *
+ * Reasoning: if hit rate is X, cost-per-token vs no caching is
+ *   (1 - X) * 1.0 + X * 0.1                                    // baseline
+ *   minus
+ *   write_iters * 1.25 + read_iters * 0.1                       // with caching
+ * Solving for break-even gives X ≈ 0.25 for typical agent shapes.
+ */
+export declare const HIT_RATE_FLOOR = 0.3;
+/**
+ * Window size for skill-churn detection. Last 5 iterations of
+ * active skill IDs are inspected.
+ */
+export declare const SKILL_CHURN_WINDOW = 5;
+/**
+ * Threshold above which skill churn is considered detected: this many
+ * UNIQUE skills in the rolling window. With window=5 and threshold=3,
+ * the pattern A → B → A → C still triggers (3 unique skills in 4 iters).
+ */
+export declare const SKILL_CHURN_THRESHOLD = 3;
+/**
+ * Pure helper: detect skill churn given a rolling history.
+ * Exported for direct testing without decider/scope ceremony.
+ */
+export declare function detectSkillChurn(history: readonly (string | undefined)[], windowSize?: number, threshold?: number): boolean;
+/**
+ * Branch routing keys for the CacheGate decider. Two outcomes:
+ * apply markers (proceed with cache) or skip (no markers this iter).
+ */
+export type CacheGateBranch = 'apply-markers' | 'no-markers';
+/**
+ * The decider function. Mounted via `addDeciderFunction` in the
+ * agent's main chart in Phase 6.
+ *
+ * Returns a `DecisionResult` (footprintjs's `decide()` helper output)
+ * which the engine unwraps via `.branch` for routing AND publishes
+ * `evidence.rules[matched].inputs[]` to FlowRecorder.onDecision.
+ * cacheRecorder (Phase 9) subscribes to that channel for the audit trail.
+ *
+ * For non-routing consumers (testing the decision in isolation), read
+ * the `.branch` field of the returned DecisionResult.
+ */
+export declare function cacheGateDecide(scope: TypedScope<CacheGateState>): DecisionResult;
+/**
+ * Update the skill-history rolling window. Called as a function
+ * stage BEFORE the CacheGate decider. Reads the current iteration's
+ * active skill (the MOST-RECENTLY activated one — the TAIL of
+ * `activatedInjectionIds`) and appends it to the `skillHistory` array.
+ *
+ * WHY THE TAIL, NOT THE HEAD: `read_skill` APPENDS each newly-activated
+ * skill to the end of `activatedInjectionIds`, and the list is cumulative
+ * + deduped per turn (reset only at seed). So the HEAD is frozen at the
+ * FIRST skill activated and never changes mid-turn — sampling it made the
+ * window record one constant value, so `detectSkillChurn` could never fire
+ * (the skill-churn cache rule was effectively dead). The tail tracks what
+ * the agent just switched to, which is the churn signal we actually want.
+ *
+ * KNOWN LIMITATION: if several skills are activated in the SAME iteration,
+ * only the last (tail) is recorded for that iteration — churn can
+ * under-count a multi-skill burst. A fully order-independent signal would
+ * read `activatedInjectionIds.length` directly in the gate; that is a
+ * larger change deferred for now.
+ *
+ * Window length is bounded at `SKILL_CHURN_WINDOW * 2` so the array
+ * doesn't grow unboundedly across long agent runs. Old entries
+ * fall off the front naturally.
+ */
+export declare function updateSkillHistory(scope: TypedScope<{
+    activatedInjectionIds?: readonly string[];
+    skillHistory: readonly (string | undefined)[];
+}>): void;