risicare 0.2.2 → 0.4.0

package/dist/index.d.cts

@@ -371,9 +371,10 @@ declare function getMetrics(): {
     queueUtilization: number;
 };
 /**
- * Report a caught exception to the self-healing pipeline.
+ * Report a caught exception to the error diagnosis pipeline.
  *
  * Creates an error span that triggers diagnosis and fix generation.
+ * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).
  * This function never throws and is non-blocking.
  *
  * @param error - The caught exception (Error object or string)
@@ -429,6 +430,17 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * Wraps a function to execute within an agent context. All spans created
  * inside will be tagged with the agent's identity.
  *
+ * Two equivalent calling forms are supported:
+ *
+ *   // 2-arg form
+ *   const research = agent({ name: 'researcher' }, async (q) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const research = agent({ name: 'researcher' })(async (q) => { ... });
+ *
+ * Both return a wrapped function — call it to actually run the body inside
+ * the agent context.
+ *
  * @example
  * const research = agent({ name: 'researcher', role: 'worker' }, async (query: string) => {
  *   const result = await openai.chat.completions.create({ ... });
@@ -438,10 +450,8 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * const answer = await research('What is quantum computing?');
  */
 
-/**
- * Wrap a function with agent context and an automatic span.
- */
 declare function agent<TArgs extends unknown[], TReturn>(options: AgentOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function agent(options: AgentOptions): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
 
 /**
  * Session context — groups multiple traces from the same user interaction.
@@ -482,10 +492,19 @@ declare function withSession<T>(options: SessionOptions, fn: () => T): T;
 /**
  * Wrap a function with session context.
  *
+ * Two equivalent calling forms are supported (F-54 ergonomics):
+ *
+ *   // 2-arg form
+ *   const handle = session({ sessionId: 's1' }, async (req) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const handle = session({ sessionId: 's1' })(async (req) => { ... });
+ *
  * @param optionsOrResolver - Static session options, or a function that derives them from args
- * @param fn - The function to wrap
+ * @param fn - The function to wrap. If omitted, returns a decorator factory.
  */
 declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
 
 /**
  * Phase decorators — decision phase tracking (Tier 4).
@@ -638,6 +657,11 @@ interface TraceContext {
 }
 /**
  * Get the current trace context as a serializable object.
+ *
+ * When called inside a span context, returns the active span's IDs.
+ * When called outside a span (e.g. inside session() but before agent()),
+ * pre-allocates a trace ID and stores it in context so the next
+ * startSpan() call inherits it — preventing trace ID mismatch.
  */
 declare function getTraceContext(): TraceContext;
 /**
@@ -728,4 +752,571 @@ declare function suppressProviderInstrumentation<T>(fn: () => T): T;
  */
 declare function isProviderInstrumentationSuppressed(): boolean;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, withAgent, withPhase, withSession };
+/**
+ * Fix Runtime Configuration.
+ *
+ * Settings for the fix runtime including caching, refresh intervals,
+ * A/B testing, and fix application behavior.
+ *
+ * Port of Python SDK's runtime/config.py adapted for Node.js patterns.
+ */
+interface FixRuntimeConfig {
+    /** API endpoint URL (e.g., "https://app.risicare.ai") */
+    apiEndpoint: string;
+    /** API key for authentication (format: "rsk-{random}") */
+    apiKey: string;
+    /** Whether the fix runtime is enabled (default: true) */
+    enabled?: boolean;
+    /** Whether caching is enabled (default: true) */
+    cacheEnabled?: boolean;
+    /** Cache entry TTL in milliseconds (default: 300_000 = 5 min) */
+    cacheTtlMs?: number;
+    /** Maximum number of cache entries (default: 1000) */
+    cacheMaxEntries?: number;
+    /** Whether to auto-refresh fixes in background (default: true) */
+    autoRefresh?: boolean;
+    /** Background refresh interval in milliseconds (default: 60_000 = 1 min) */
+    refreshIntervalMs?: number;
+    /** Log but don't apply fixes (default: false) */
+    dryRun?: boolean;
+    /** Whether A/B testing bucketing is active (default: true) */
+    abTestingEnabled?: boolean;
+    /** Timeout for API requests in milliseconds (default: 1000) */
+    timeoutMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+type FixType = 'prompt' | 'parameter' | 'retry' | 'fallback' | 'guard' | 'routing' | 'tool';
+interface ActiveFix {
+    fixId: string;
+    deploymentId?: string;
+    errorCode: string;
+    fixType: FixType;
+    config: Record<string, unknown>;
+    trafficPercentage: number;
+    version: number;
+}
+
+/**
+ * Fix Cache — Local cache for active fixes with TTL eviction.
+ *
+ * Provides fast lookup of fixes keyed by error code with exact match
+ * and wildcard fallback. No locks needed — JS is single-threaded.
+ *
+ * Port of Python SDK's runtime/cache.py.
+ */
+
+interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    lastRefresh: number | null;
+}
+declare class FixCache {
+    private readonly _ttlMs;
+    private readonly _maxEntries;
+    private readonly _enabled;
+    private _cache;
+    private _stats;
+    constructor(config?: Pick<FixRuntimeConfig, 'cacheEnabled' | 'cacheTtlMs' | 'cacheMaxEntries'>);
+    /** Whether caching is enabled. */
+    get enabled(): boolean;
+    /**
+     * Get a fix by error code.
+     *
+     * Checks exact match first, then scans for wildcard matches.
+     * Expired entries are evicted on access.
+     */
+    get(errorCode: string): ActiveFix | null;
+    /**
+     * Add a single fix to the cache.
+     *
+     * Evicts the oldest entry if at capacity.
+     */
+    set(fix: ActiveFix): void;
+    /**
+     * Replace all cached fixes (bulk refresh).
+     *
+     * Clears the cache and populates with the given fixes.
+     */
+    setAll(fixes: ActiveFix[]): void;
+    /**
+     * Get all non-expired fixes.
+     */
+    getAll(): ActiveFix[];
+    /** Clear all cache entries. Returns the number of entries cleared. */
+    clear(): number;
+    /** Get cache statistics. */
+    get stats(): CacheStats;
+    /** Evict the oldest cache entry. */
+    private _evictOldest;
+}
+
+/**
+ * Fix Applier — Applies fixes to agent operations.
+ *
+ * Handles different fix types:
+ * - PromptFix:     Modify system/user prompts (prepend, append, replace, few_shot)
+ * - ParameterFix:  Adjust LLM parameters (temperature, model, etc.)
+ * - RetryFix:      Retry with exponential backoff + jitter
+ * - FallbackFix:   Switch to fallback model or default response
+ * - GuardFix:      Input/output validation (content filter, format check, length)
+ *
+ * Port of Python SDK's runtime/applier.py adapted for Node.js.
+ */
+
+interface ApplyResult {
+    applied: boolean;
+    fixId?: string;
+    deploymentId?: string;
+    fixType?: string;
+    modifications: Record<string, unknown>;
+    error?: string;
+}
+declare class FixApplier {
+    private readonly _config;
+    private readonly _cache;
+    private _applicationLog;
+    constructor(config: FixRuntimeConfig, cache: FixCache);
+    /**
+     * Get applicable fix for an error code.
+     *
+     * Considers A/B testing bucket if sessionId is provided. Uses
+     * crypto.createHash('md5') for deterministic bucketing across restarts.
+     */
+    getFixForError(errorCode: string, sessionId?: string): ActiveFix | null;
+    /**
+     * Apply a prompt fix to messages.
+     *
+     * Supports 4 modification types:
+     * - prepend: Add content before first system message
+     * - append:  Add content after first system message
+     * - replace: Regex replace across all messages
+     * - few_shot: Insert user/assistant example pairs after system message
+     */
+    applyPromptFix(fix: ActiveFix, messages: Record<string, unknown>[]): {
+        messages: Record<string, unknown>[];
+        result: ApplyResult;
+    };
+    /**
+     * Apply a parameter fix — merge config.parameters into params.
+     */
+    applyParameterFix(fix: ActiveFix, params: Record<string, unknown>): {
+        params: Record<string, unknown>;
+        result: ApplyResult;
+    };
+    /**
+     * Apply a retry fix to an async operation.
+     *
+     * Retries with exponential backoff + jitter using
+     * `await new Promise(r => setTimeout(r, delay))`.
+     */
+    applyRetryFix<T>(fix: ActiveFix, operation: () => Promise<T>): Promise<{
+        value: T;
+        result: ApplyResult;
+    }>;
+    /**
+     * Apply a fallback fix.
+     *
+     * - 'model': Replace params.model with the fallback model
+     * - 'default': Set params._fallbackResponse for the caller to use
+     */
+    applyFallbackFix(fix: ActiveFix, params: Record<string, unknown>): {
+        params: Record<string, unknown>;
+        result: ApplyResult;
+    };
+    /**
+     * Apply a guard fix (validation).
+     *
+     * Guard types:
+     * - content_filter: Regex-based blocked patterns
+     * - format_check:   JSON.parse() validity
+     * - input_validation / output_validation: min/max length
+     */
+    applyGuardFix(fix: ActiveFix, content: string, isInput?: boolean): {
+        content: string;
+        passed: boolean;
+        result: ApplyResult;
+    };
+    /** Log a fix application result. */
+    logApplication(result: ApplyResult): void;
+    /** Get the application log. */
+    getApplicationLog(): ApplyResult[];
+    /**
+     * Safely compile a regex pattern from untrusted input.
+     * Returns null if invalid or too long.
+     */
+    private _safeCompileRegex;
+    /** Prepend content to the first message matching the target role. */
+    private _prependToTarget;
+    /** Append content to the first message matching the target role. */
+    private _appendToTarget;
+    /** Regex replace across all messages. */
+    private _replaceInMessages;
+    /** Add few-shot examples after the first system message. */
+    private _addFewShotExamples;
+}
+
+/**
+ * Fix Loader — Fetches active fixes from the Risicare API.
+ *
+ * Handles:
+ * - Initial loading of fixes on startup
+ * - Periodic background refresh via setInterval (unref'd)
+ * - Exponential backoff on failure
+ * - Circuit breaker: after 3 consecutive failures, stop trying for 30s
+ *
+ * Uses native fetch (Node.js 18+) with AbortController for timeouts.
+ *
+ * Port of Python SDK's runtime/loader.py adapted for Node.js.
+ */
+
+declare class FixLoader {
+    private readonly _config;
+    private readonly _cache;
+    private _refreshTimer;
+    private _lastLoadTime;
+    private _consecutiveFailures;
+    private _circuitOpenUntil;
+    private _onLoadCallbacks;
+    private static readonly CIRCUIT_BREAKER_THRESHOLD;
+    private static readonly CIRCUIT_BREAKER_COOLDOWN_MS;
+    constructor(config: FixRuntimeConfig, cache: FixCache);
+    /** Timestamp of last successful load. */
+    get lastLoadTime(): number | null;
+    /**
+     * Start the loader: perform initial load and start background refresh.
+     *
+     * Never throws — failures are logged and the runtime degrades gracefully.
+     */
+    start(): void;
+    /** Stop the loader: clear the refresh interval. */
+    stop(): void;
+    /**
+     * Register a callback invoked after each successful load.
+     */
+    onLoad(callback: (fixes: ActiveFix[]) => void): void;
+    /**
+     * Load fixes from the API.
+     *
+     * Name kept as "loadSync" for parity with the Python SDK, but this
+     * returns a Promise in JS (there's no synchronous fetch in Node.js).
+     */
+    loadSync(): Promise<ActiveFix[]>;
+    /** Get currently cached fixes without hitting the API. */
+    getCached(): ActiveFix[];
+    private _parseResponse;
+    private _onLoadSuccess;
+    private _onLoadFailure;
+    private _startRefreshInterval;
+}
+
+/**
+ * Fix Interceptors — Hook into LLM/tool calls to apply fixes.
+ *
+ * Interceptors are registered with the runtime and called during agent
+ * execution to apply relevant fixes at three interception points:
+ * - preCall:  Before the LLM/tool call (prompt/parameter/fallback fixes)
+ * - postCall: After the call (output guard validation)
+ * - onError:  When an error occurs (retry/fallback decisions)
+ *
+ * Port of Python SDK's runtime/interceptors.py adapted for Node.js.
+ */
+
+interface InterceptContext {
+    /** Type of operation: "llm_call", "tool_call", "agent_delegate" */
+    operationType: string;
+    /** Name of the operation: model name, tool name, agent name */
+    operationName: string;
+    /** Session ID for A/B testing bucketing */
+    sessionId?: string;
+    /** Trace ID for correlation */
+    traceId?: string;
+    /** Error code (set when retrying after error) */
+    errorCode?: string;
+    /** Error message (set when retrying after error) */
+    errorMessage?: string;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Fixes applied during this intercept lifecycle */
+    appliedFixes: ApplyResult[];
+}
+interface FixInterceptor {
+    /**
+     * Called before an LLM/tool call.
+     * Returns modified messages and params.
+     */
+    preCall(ctx: InterceptContext, messages: unknown[] | null, params: Record<string, unknown>): {
+        messages: unknown[] | null;
+        params: Record<string, unknown>;
+    };
+    /**
+     * Called after an LLM/tool call.
+     * Returns modified response and whether to continue.
+     */
+    postCall(ctx: InterceptContext, response: unknown): {
+        response: unknown;
+        shouldContinue: boolean;
+    };
+    /**
+     * Called when an error occurs.
+     * Returns whether to retry and optional modified params.
+     */
+    onError(ctx: InterceptContext, error: Error): {
+        shouldRetry: boolean;
+        modifiedParams: Record<string, unknown> | null;
+    };
+}
+
+/**
+ * Fix Runtime — Main orchestrator for the fix application system.
+ *
+ * Manages:
+ * - Loading active fixes from the API (via FixLoader)
+ * - Caching fixes locally (via FixCache)
+ * - Applying fixes via interceptors (via DefaultFixInterceptor)
+ * - Tracking fix effectiveness
+ *
+ * Singleton management via globalThis (same pattern as the tracer).
+ *
+ * Port of Python SDK's runtime/runtime.py adapted for Node.js.
+ */
+
+declare class FixRuntime {
+    private readonly _config;
+    private readonly _cache;
+    private readonly _loader;
+    private readonly _applier;
+    private readonly _interceptor;
+    private _started;
+    private _fixApplications;
+    private _fixSuccesses;
+    constructor(config: FixRuntimeConfig);
+    /** Runtime configuration (with defaults resolved). */
+    get config(): Required<FixRuntimeConfig>;
+    /** Whether the runtime is enabled and started. */
+    get isEnabled(): boolean;
+    /** The fix cache. */
+    get cache(): FixCache;
+    /** The fix loader. */
+    get loader(): FixLoader;
+    /** The fix applier. */
+    get applier(): FixApplier;
+    /** The interceptor. */
+    get interceptor(): FixInterceptor;
+    /**
+     * Start the runtime.
+     *
+     * Triggers initial fix load and starts background refresh.
+     * Never throws — failures degrade gracefully.
+     */
+    start(): void;
+    /**
+     * Stop the runtime.
+     *
+     * Stops background refresh and clears the cache.
+     * Never throws.
+     */
+    stop(): void;
+    /**
+     * Intercept a call: create context and run preCall fixes.
+     *
+     * Returns modified messages/params and the InterceptContext for
+     * use in subsequent interceptResponse / interceptError calls.
+     */
+    interceptCall(operationType: string, operationName: string, messages: unknown[] | null, params: Record<string, unknown>, options?: {
+        sessionId?: string;
+        traceId?: string;
+        errorCode?: string;
+    }): {
+        messages: unknown[] | null;
+        params: Record<string, unknown>;
+        ctx: InterceptContext;
+    };
+    /**
+     * Intercept a response: run postCall fixes (output validation).
+     */
+    interceptResponse(ctx: InterceptContext, response: unknown): {
+        response: unknown;
+        shouldContinue: boolean;
+    };
+    /**
+     * Intercept an error: decide on retry/fallback.
+     */
+    interceptError(ctx: InterceptContext, error: Error): {
+        shouldRetry: boolean;
+        modifiedParams: Record<string, unknown> | null;
+    };
+    /**
+     * Get applicable fix for an error code.
+     */
+    getFix(errorCode: string, sessionId?: string): ActiveFix | null;
+    /**
+     * Manually refresh fixes from the API.
+     */
+    refreshFixes(): Promise<ActiveFix[]>;
+    /** Get effectiveness statistics for all fixes. */
+    getEffectivenessStats(): Record<string, {
+        applications: number;
+        successes: number;
+        successRate: number;
+    }>;
+    private _trackSuccess;
+    private _trackFailure;
+}
+/** Get the global FixRuntime instance, if initialized. */
+declare function getFixRuntime(): FixRuntime | undefined;
+/**
+ * Initialize and start the global FixRuntime.
+ *
+ * If already initialized, returns the existing instance.
+ * Never throws — initialization failures degrade gracefully.
+ */
+declare function initFixRuntime(config: FixRuntimeConfig): FixRuntime;
+/**
+ * Shutdown and remove the global FixRuntime.
+ *
+ * Never throws.
+ */
+declare function shutdownFixRuntime(): void;
+
+/**
+ * Webhook signature verification helpers (CON-195 / B-7, F-34).
+ *
+ * Customers receive Risicare webhooks at endpoints they configure. Each
+ * delivery is signed by the sender (`packages/workers/src/workers/
+ * webhook_dispatch.py`) with HMAC-SHA256 over `<timestamp>.<payload_bytes>`
+ * using the per-webhook shared secret. The signature is delivered in the
+ * `X-Risicare-Signature` header in Stripe-style format `t=<unix>,v1=<hex>`,
+ * and the timestamp is also exposed verbatim as `X-Risicare-Timestamp`.
+ *
+ * This module is the TypeScript port of `risicare-sdk/src/risicare/
+ * webhooks.py`. It enforces THREE checks (all must pass):
+ *
+ *   1. Header parsing — both headers must be present and well-formed.
+ *   2. Time skew — `Math.abs(now - timestamp) <= toleranceS` (default
+ *      5 minutes). This is what makes captured signed payloads
+ *      non-replayable past the tolerance window.
+ *   3. HMAC equality — constant-time compare against a fresh signature
+ *      computed from the secret + the SAME timestamp + the raw body.
+ *
+ * Example (Express/Node receiver):
+ *
+ *     import express from 'express';
+ *     import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
+ *
+ *     const app = express();
+ *     // IMPORTANT: use raw body, not parsed JSON — the signature is
+ *     // over the EXACT bytes received; JSON re-serialization changes
+ *     // key ordering / whitespace and the signature will not match.
+ *     app.post('/risicare-webhook', express.raw({ type: '*\/*' }), (req, res) => {
+ *       try {
+ *         verifyWebhookSignature(req.body, req.headers, YOUR_WEBHOOK_SECRET);
+ *       } catch (e) {
+ *         if (e instanceof WebhookVerificationError) {
+ *           return res.status(401).send(e.message);
+ *         }
+ *         throw e;
+ *       }
+ *       // ... process the verified event ...
+ *       res.status(200).end();
+ *     });
+ *
+ * The helper is dependency-light (Node `crypto` stdlib only) so customers
+ * can use it without pulling in the rest of the SDK if they only need
+ * verification.
+ *
+ * Edge runtime note: this verifier is synchronous and uses Node's
+ * `crypto.timingSafeEqual` + `crypto.createHmac`. It will not run in
+ * Cloudflare Workers / Vercel Edge / Deno Deploy as-is. An async Web
+ * Crypto variant can be added if customers request it.
+ */
+/**
+ * Default skew window (seconds). 5 minutes matches Stripe / GitHub /
+ * common industry practice. Customers can override per-call if their
+ * clock infrastructure warrants a tighter or looser bound.
+ *
+ * Mirrors `DEFAULT_TIMESTAMP_TOLERANCE_S` in the Python SDK.
+ */
+declare const DEFAULT_TIMESTAMP_TOLERANCE_S = 300;
+/**
+ * Raised when a webhook delivery fails any verification check.
+ *
+ * Customers should catch this specifically rather than a generic `Error`
+ * so verification failures are not conflated with other input problems
+ * (e.g. body-parsing errors at the framework layer).
+ *
+ * The `message` is safe to log — it never includes the secret, the
+ * expected signature, or the computed signature.
+ */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for `verifyWebhookSignature`. All fields are optional.
+ */
+interface VerifyWebhookOptions {
+    /**
+     * Maximum clock-skew tolerance in seconds. Defaults to
+     * `DEFAULT_TIMESTAMP_TOLERANCE_S` (300). Setting to 0 is supported
+     * (strict same-second match) but discouraged in distributed
+     * deployments.
+     */
+    toleranceS?: number;
+    /**
+     * Test hook — override "current time" in unix seconds.
+     * Customers should not pass this.
+     */
+    _now?: number;
+}
+/**
+ * Header-like inputs accepted by `verifyWebhookSignature`.
+ *
+ * Covers (a) Web API `Headers` (case-insensitive `.get`), (b) Node
+ * `IncomingHttpHeaders` (plain object with lowercase keys, possibly
+ * array-valued for multi-set headers), (c) `Map<string, string>`
+ * (case-sensitive `.get`), and (d) plain `Record` (case-sensitive
+ * property lookup, possibly array-valued).
+ *
+ * Lookup strategy: try the canonical mixed-case name first
+ * (`X-Risicare-Signature`). If that returns undefined, fall back to the
+ * lowercased form (`x-risicare-signature`). Mirrors the Python
+ * `_get_header` helper.
+ */
+type HeaderLookup = Headers | Map<string, string> | Record<string, string | string[] | undefined>;
+/**
+ * Payload shapes accepted by `verifyWebhookSignature`.
+ *
+ * `Buffer extends Uint8Array` in Node, so callers passing `Buffer`
+ * satisfy the `Uint8Array` arm. `ArrayBuffer` is explicitly accepted
+ * for callers using Web-API request bodies. `string` is UTF-8 encoded
+ * internally.
+ *
+ * Crucially, callers must pass the EXACT bytes received over the
+ * wire. Parsing JSON and re-serializing changes byte order and
+ * whitespace; the signature will not match.
+ */
+type WebhookPayload = Uint8Array | ArrayBuffer | string;
+/**
+ * Verify a Risicare webhook delivery. Throws `WebhookVerificationError`
+ * on any failure; returns `undefined` on success.
+ *
+ * @param payload Raw request body bytes — the EXACT bytes received over
+ *   the wire. Re-serializing parsed JSON will change byte ordering and
+ *   break the signature.
+ * @param headers Header lookup. Web `Headers`, `Map<string,string>`,
+ *   Node `IncomingHttpHeaders`, or plain `Record` all work. Lookup is
+ *   case-insensitive (canonical mixed-case tried first, then lowercase).
+ * @param secret The shared secret configured on the Risicare webhook
+ *   record. Returned by `POST /v1/webhooks` once at create time.
+ * @param opts Optional overrides — `toleranceS` (default 300) and
+ *   `_now` (test hook).
+ *
+ * @throws WebhookVerificationError on any of: missing headers, malformed
+ *   signature, timestamp outside tolerance, HMAC mismatch, or invalid
+ *   payload type.
+ */
+declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
+
+export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, type HeaderLookup, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };