agentfootprint/dist/esm/strategies/attach.d.ts

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

/**
 * Wire each grouped strategy to its data source on the dispatcher /
 * recorder substrate. These are the 4 `enable.*` facades' actual
 * implementations; `RunnerBase.enable` calls them with the right
 * dispatcher / attach handle.
 *
 * Pattern: every facade follows the same shape:
 *
 *   1. Resolve strategy (consumer-supplied OR default)
 *   2. Run `strategy.validate?()` — early-fail on misconfig (New Relic
 *      panel review)
 *   3. Set up subscription / projection
 *   4. Apply per-strategy event-type filter (`relevantEventTypes`)
 *   5. Apply per-call sample rate
 *   6. Wrap calls in try/catch — route errors to `_onError` (passive
 *      recorder rule: never throw to caller)
 *   7. Return Unsubscribe (or handle for lens)
 */
import type { EventDispatcher } from '../events/dispatcher.js';
import type { ObservabilityStrategy, CostStrategy, LiveStatusStrategy, CommonStrategyOptions, ObservabilityHandle, ObservabilityTier, StrategyHandle } from './types.js';
import { type StatusTemplates } from '../recorders/observability/status/statusTemplates.js';
export interface ObservabilityEnableOptions extends CommonStrategyOptions {
    /** Cost-of-on knob: how many events reach the sink. `'minimal'` -> agent
     *  lifecycle + errors. `'standard'` -> everything except per-token streams.
     *  `'firehose'` -> every event. Default `'standard'`.
     *
     *  **This is not a privacy control.** No tier redacts anything, and a lower
     *  tier is not a safer one: `'minimal'` still ships `agent.turn_start`
     *  (`userPrompt`), `agent.turn_end` (`finalContent`) and `agent.iteration_end`
     *  (the full conversation `history[]`), so it delivers fewer events but a
     *  higher share of content-bearing ones. `'standard'` adds raw tool arguments
     *  and results (`stream.tool_start` / `tool_end`), retrieved text
     *  (`context.injected.rawContent`) and raw reasoning
     *  (`stream.thinking_delta`).
     *
     *  If prompts or documents must not leave the process, choose a strategy that
     *  bounds payloads — `auditExport()` bounds by default, `otelObservability()`
     *  omits `userPrompt` — or bound them yourself in your own `exportEvent`.
     *  `redactContent` does NOT apply here: it operates on the offline
     *  `serializeTrace` / `localObservability` channel, not on this one. */
    readonly tier?: ObservabilityTier;
    readonly strategy?: ObservabilityStrategy;
}
export declare function attachObservabilityStrategy(dispatcher: EventDispatcher, opts?: ObservabilityEnableOptions): ObservabilityHandle;
export interface CostEnableOptions extends CommonStrategyOptions {
    readonly strategy?: CostStrategy;
}
/**
 * Subscribe to `agentfootprint.cost.tick` events, project payload into
 * the canonical `CostTick` shape, hand to strategy.
 *
 * **The projection reads `CostTickPayload`, which is not spelled like
 * `CostTick`.** It never was: the wire payload `emitCostTick` produces carries
 * `tokensInput` / `tokensOutput` / `estimatedUsd` for the call just billed and
 * a nested `cumulative` for the run so far, while the strategy-facing
 * {@link CostTick} says `recent*` / `cumulative*`. This projection used to read
 * the strategy names off the payload, so every field resolved to `?? 0` and
 * every attached cost strategy — billing sinks, budget breakers, dashboards —
 * was handed a tick of zeros. A tick of zeros is worse than no tick: it looks
 * like a run that cost nothing.
 *
 * The `?? p.recent*` / `?? p.cumulative*` fallbacks below are NOT that bug left
 * in place. They cover an event hand-constructed from the public `CostTick`
 * shape rather than emitted by the library — the same allowance the X-Ray and
 * OTel exporters already make for this one event type (`xray.ts`, `otel.ts`),
 * and the real shape is what wins when both are present.
 */
export declare function attachCostStrategy(dispatcher: EventDispatcher, opts?: CostEnableOptions): StrategyHandle;
export interface LiveStatusEnableOptions extends CommonStrategyOptions {
    readonly strategy: LiveStatusStrategy;
    /** Override the bundled English thinking templates with locale /
     *  per-tool / per-skill overrides. Same shape as
     *  `agent.thinkingTemplates(...)`. */
    readonly templates?: StatusTemplates;
    /** App name woven into `{{appName}}` template var. */
    readonly appName?: string;
}
export declare function attachLiveStatusStrategy(dispatcher: EventDispatcher, opts: LiveStatusEnableOptions): StrategyHandle;