@sentrial/sdk 0.4.4 → 0.5.0

package/dist/index.d.cts

@@ -1,3 +1,74 @@
+import { C as CostParams, a as SentrialClientConfig, b as CreateSessionParams, G as GetVariantParams, V as VariantAssignment, R as RecordExperimentExposureParams, c as ExperimentExposureReceipt, T as TrackToolCallParams, d as Event, e as TrackDecisionParams, f as TrackErrorParams, g as Session, h as CompleteSessionParams, D as DeliveryDiagnostics, B as BeginParams, F as FinishParams } from './types-BEf8OATP.cjs';
+export { A as ApiResponse, i as BatcherConfig, j as EventBatcher, k as EventType, L as LargeToolContentConfig, P as PiiBuiltinPatterns, l as PiiConfig, m as PiiCustomPattern, n as PiiField, o as PiiMode, p as ProductionVariantConfig, q as SessionStatus, r as hashValue, s as redactPayload, t as redactString, u as redactValue, v as replaceMatch } from './types-BEf8OATP.cjs';
+
+/** The five builtin pattern categories, in their canonical (load-bearing) order. */
+type PiiPatternKey = 'emails' | 'creditCards' | 'ssns' | 'phones' | 'ipAddresses';
+/**
+ * Map of builtin pattern keys to their regex and label. ORDER MATTERS: consumers apply these in
+ * insertion order, replacing each match before the next pattern runs. Longer/more-specific number
+ * patterns MUST come before shorter ones — creditCards + ssns BEFORE phones — otherwise the PHONE
+ * pattern's separator alternative can eat a phone-shaped tail of a separator-formatted card (e.g.
+ * "411-111-111-1111" -> "411-[PHONE]"), leaking the leading digits; and for a bare 16-digit card
+ * the PHONE pattern would eat the trailing 10 digits, leaking the leading 6 (e.g.
+ * "4111111111111111" -> "411111[PHONE]"). Bare digit runs are already immune via PHONE_PATTERN's
+ * (?<!\d) guard. Kept in lockstep with the Python `_BUILTIN_PATTERNS`.
+ */
+declare const BUILTIN_PATTERNS: Record<PiiPatternKey, {
+    pattern: RegExp;
+    label: string;
+    validate?: (match: string) => boolean;
+}>;
+
+/** Process-local OTLP transport observations. No URLs, bodies, IDs or credentials retained. */
+declare const SERVER_STAGES: readonly ["body", "decode", "ingest", "resolve", "transaction", "postprocess", "total"];
+type Stage = (typeof SERVER_STAGES)[number];
+type AttemptOutcome = 'httpSuccess' | 'httpError' | 'transportError' | 'timeout' | 'cancelled' | 'bodyError';
+type DurationSummary = {
+    measured: number;
+    unavailable: number;
+    totalMs: number;
+    minMs: number | null;
+    maxMs: number | null;
+};
+type ServerDurations = Record<Stage, number | null>;
+type TransportAttempt = {
+    retry: boolean;
+    outcome: AttemptOutcome;
+    status: number | null;
+    elapsedMs: number | null;
+    serverTiming: ServerDurations;
+    acknowledgment: {
+        acceptedSpans: number | null;
+        rejectedSpans: number | null;
+    } | null;
+};
+type TransportDiagnosticsSnapshot = {
+    scope: 'otlp';
+    recentLimit: 32;
+    requests: {
+        started: number;
+        inFlight: number;
+        returned: number;
+        failed: number;
+        cancelled: number;
+        duration: DurationSummary;
+    };
+    attempts: {
+        started: number;
+        inFlight: number;
+        retries: number;
+        outcomes: Record<AttemptOutcome, number>;
+        duration: DurationSummary;
+    };
+    acknowledgments: {
+        complete: number;
+        partial: number;
+        unknown: number;
+    };
+    serverTiming: Record<Stage, DurationSummary>;
+    recent: TransportAttempt[];
+};
+
 /**
  * Async-safe context variables for the Sentrial SDK.
  *
@@ -99,28 +170,6 @@ declare function getSessionContext(): string | null;
  * Set the default client for wrappers.
  */
 declare function setDefaultClient(client: SentrialClient): void;
-/**
- * Wrap an OpenAI client to automatically track all LLM calls.
- *
- * @param client - OpenAI client instance
- * @param options - Wrapper options
- * @returns The same client, now with auto-tracking enabled
- *
- * @example
- * ```ts
- * import OpenAI from 'openai';
- * import { wrapOpenAI, configure } from '@sentrial/sdk';
- *
- * configure({ apiKey: 'sentrial_live_xxx' });
- * const openai = wrapOpenAI(new OpenAI());
- *
- * // Now use client normally - all calls are tracked!
- * const response = await openai.chat.completions.create({
- *   model: 'gpt-4o',
- *   messages: [{ role: 'user', content: 'Hello' }],
- * });
- * ```
- */
 declare function wrapOpenAI<T extends object>(client: T, options?: {
     trackWithoutSession?: boolean;
 }): T;
@@ -189,421 +238,36 @@ declare function wrapGoogle<T extends object>(model: T, options?: {
  */
 declare function wrapLLM<T extends object>(client: T, provider?: 'openai' | 'anthropic' | 'google'): T;
 
-/**
- * PII Redaction Module
- *
- * Automatically detects and redacts personally identifiable information (PII)
- * from SDK payloads before they are sent to the Sentrial API.
- */
-/** How redacted values are replaced */
-type PiiMode = 'label' | 'hash' | 'remove';
-/** Fields that can be redacted in SDK payloads */
-type PiiField = 'userInput' | 'assistantOutput' | 'toolInput' | 'toolOutput' | 'metadata' | 'reasoning' | 'failureReason';
-/** A custom regex pattern with a human-readable label */
-interface PiiCustomPattern {
-    pattern: RegExp;
-    label: string;
-}
-/** Toggle individual builtin pattern categories */
-interface PiiBuiltinPatterns {
-    emails?: boolean;
-    phones?: boolean;
-    ssns?: boolean;
-    creditCards?: boolean;
-    ipAddresses?: boolean;
-}
-/** Full PII redaction configuration */
-interface PiiConfig {
-    /** Enable PII redaction (default: false) */
-    enabled: boolean;
-    /** Which payload fields to redact (default: DEFAULT_FIELDS) */
-    fields?: PiiField[];
-    /** Replacement mode (default: 'label') */
-    mode?: PiiMode;
-    /** Enable enhanced detection heuristics (reserved for future use) */
-    enhancedDetection?: boolean;
-    /** Toggle builtin patterns (default: all enabled) */
-    builtinPatterns?: PiiBuiltinPatterns;
-    /** Additional custom patterns to apply */
-    customPatterns?: PiiCustomPattern[];
-}
-/**
- * Hash a value using SHA-256 and return the first 6 hex characters.
- * Used in 'hash' mode to produce a short, deterministic pseudonym.
- */
-declare function hashValue(value: string): string;
-/**
- * Produce the replacement string for a matched PII value.
- *
- * - 'label' mode:  [LABEL]
- * - 'hash' mode:   [PII:abcdef]
- * - 'remove' mode: '' (empty string)
- */
-declare function replaceMatch(match: string, label: string, mode: PiiMode): string;
-/**
- * Run all enabled builtin and custom patterns against a single string,
- * replacing every match according to the specified mode.
- */
-declare function redactString(value: string, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): string;
-/**
- * Recursively redact PII from a value. Handles strings, arrays, plain objects,
- * and passes through primitives (numbers, booleans, null, undefined) unchanged.
- */
-declare function redactValue(value: unknown, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): unknown;
-/**
- * Main entry point: redact configured fields in a payload object.
- *
- * Only fields listed in the PiiConfig (or DEFAULT_FIELDS) are redacted.
- * Other fields are returned unchanged.
- *
- * @param payload - The data payload (e.g., session params, tool call params)
- * @param config  - PII configuration from the client
- * @returns A new payload object with PII redacted from the configured fields
- */
-declare function redactPayload(payload: Record<string, unknown>, config: PiiConfig): Record<string, unknown>;
-
-/**
- * EventBatcher — fire-and-forget event queue with periodic flushing.
- *
- * Buffers tracking events (tool calls, decisions, errors, generic events)
- * and flushes them in batches to reduce HTTP overhead. Session lifecycle
- * calls (createSession, completeSession) bypass the batcher entirely
- * because they need synchronous responses.
- *
- * Flush triggers:
- *  1. Timer — every `flushIntervalMs` (default 1 000 ms)
- *  2. Queue size — when queue reaches `flushThreshold` (default 10)
- *  3. Manual — `flush()` or `shutdown()`
- *  4. Process exit — `beforeExit` handler
- *
- * Back-pressure: queue is capped at `maxQueueSize` (default 1 000).
- * When full, oldest events are dropped and a warning is logged.
- */
-interface BatcherConfig {
-    /** Whether batching is enabled (default: false — all calls are immediate) */
-    enabled?: boolean;
-    /** Milliseconds between automatic flushes (default: 1000) */
-    flushIntervalMs?: number;
-    /** Flush when the queue reaches this many items (default: 10) */
-    flushThreshold?: number;
-    /** Maximum queue size before dropping oldest events (default: 1000) */
-    maxQueueSize?: number;
-}
-/** Signature for the function that actually sends an event to the API. */
-type SendFn = (method: string, url: string, body: unknown) => Promise<unknown>;
-declare class EventBatcher {
-    private readonly queue;
-    private readonly flushIntervalMs;
-    private readonly flushThreshold;
-    private readonly maxQueueSize;
-    private timer;
-    private sendFn;
-    private flushing;
-    private shutdownCalled;
-    private readonly exitHandler;
-    constructor(sendFn: SendFn, config?: BatcherConfig);
-    /**
-     * Enqueue an event for batched delivery.
-     *
-     * If the queue hits `flushThreshold`, an automatic flush is triggered.
-     * If the queue is full (`maxQueueSize`), the oldest event is dropped.
-     */
-    enqueue(method: string, url: string, body: unknown): void;
-    /**
-     * Flush all queued events to the API.
-     *
-     * Drains the queue and fires all requests in parallel. Safe to call
-     * concurrently — only one flush runs at a time.
-     */
-    flush(): Promise<void>;
-    /**
-     * Stop the batcher: clear the timer, flush remaining events, remove exit handler.
-     */
-    shutdown(): Promise<void>;
-    /** Number of events currently queued. */
-    get size(): number;
-}
-
-/**
- * Type definitions for the Sentrial TypeScript SDK
- */
-
-/**
- * Event types that can be tracked in a session
- */
-declare enum EventType {
-    TOOL_CALL = "tool_call",
-    LLM_DECISION = "llm_decision",
-    STATE_CHANGE = "state_change",
-    ERROR = "error"
-}
-/**
- * Session status values
- */
-type SessionStatus = 'running' | 'completed' | 'failed' | 'cancelled';
-/**
- * Configuration options for SentrialClient
- */
-interface SentrialClientConfig {
-    /** API key for authentication (defaults to SENTRIAL_API_KEY env var) */
-    apiKey?: string;
-    /** URL of the Sentrial API server (defaults to SENTRIAL_API_URL env var or production) */
-    apiUrl?: string;
-    /**
-     * If true (default), SDK errors are logged but won't crash your app.
-     * Set to false during development to see full errors.
-     */
-    failSilently?: boolean;
-    /**
-     * PII redaction configuration.
-     * - Pass a PiiConfig object for full control.
-     * - Pass `true` to fetch the org's PII config from the server automatically.
-     */
-    pii?: PiiConfig | boolean;
-    /**
-     * Event batching configuration.
-     * When enabled, fire-and-forget tracking calls (trackToolCall, trackDecision,
-     * trackError, trackEvent) are queued and flushed periodically instead of
-     * being sent immediately. Session lifecycle calls (createSession,
-     * completeSession) always bypass the batcher.
-     */
-    batching?: BatcherConfig;
-}
-/**
- * Parameters for creating a new session
- */
-interface CreateSessionParams {
-    /** Name of the session */
-    name: string;
-    /** Identifier for the agent type (used for grouping) */
-    agentName: string;
-    /** External user ID (for grouping sessions by end-user) */
-    userId: string;
-    /** Optional parent session ID for multi-agent hierarchies */
-    parentSessionId?: string;
-    /** Optional conversation ID to group related sessions into a thread */
-    convoId?: string;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
+/** Portable, payload-free context for a separately instrumented worker session.
+ * This is correlation metadata, never an authorization token or proof of outcome. */
+interface ActionIdentity {
+    actionId: string;
+    attemptId?: string;
+    retryOfAttemptId?: string;
 }
-/**
- * Parameters for completing a session
- */
-interface CompleteSessionParams {
-    /** Session ID */
-    sessionId: string;
-    /** Whether the session successfully completed its goal (default: true) */
-    success?: boolean;
-    /** If success=false, why did it fail? */
-    failureReason?: string;
-    /** Total estimated cost in USD for this session */
-    estimatedCost?: number;
-    /** Custom metrics (e.g., { customer_satisfaction: 4.5, steps_taken: 3 }) */
-    customMetrics?: Record<string, number>;
-    /** Duration in milliseconds (auto-calculated if not provided) */
-    durationMs?: number;
-    /** Number of prompt/input tokens used */
-    promptTokens?: number;
-    /** Number of completion/output tokens used */
-    completionTokens?: number;
-    /** Total tokens used (prompt + completion) */
-    totalTokens?: number;
-    /** The user's original query/input for this session */
-    userInput?: string;
-    /** The final assistant response for this session */
-    assistantOutput?: string;
-    /** Alias for assistantOutput - the final output text */
-    output?: string;
+interface HandoffContext extends ActionIdentity {
+    version: 'sentrial-handoff-v1';
+    parentSessionId: string;
 }
-/**
- * Session data returned from the API
- */
-interface Session {
-    id: string;
-    agentId?: string;
-    parentSessionId?: string;
-    convoId?: string;
-    name: string;
-    agentName: string;
-    userId: string;
-    status: SessionStatus;
-    totalEvents: number;
-    userInput?: string;
-    assistantOutput?: string;
-    success?: boolean;
-    failureReason?: string;
-    estimatedCost?: number;
-    customMetrics?: Record<string, unknown>;
-    score?: number;
-    metricScores?: Record<string, unknown>;
-    metricReasonings?: Record<string, string>;
-    promptTokens?: number;
-    completionTokens?: number;
-    totalTokens?: number;
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-    createdAt: Date;
-    updatedAt: Date;
-    completedAt?: Date;
-}
-/**
- * Parameters for tracking a tool call event
- */
-interface TrackToolCallParams {
-    /** Session ID */
-    sessionId: string;
-    /** Name of the tool */
-    toolName: string;
-    /** Tool input data */
-    toolInput: Record<string, unknown>;
-    /** Tool output data */
-    toolOutput: Record<string, unknown>;
-    /** Optional reasoning for why this tool was called */
-    reasoning?: string;
-    /** Estimated cost in USD for this tool call */
-    estimatedCost?: number;
-    /** Error details if the tool failed */
-    toolError?: Record<string, unknown>;
-    /** Number of tokens used by this tool call (for LLM-based tools) */
-    tokenCount?: number;
-    /** OpenTelemetry trace ID for distributed tracing */
-    traceId?: string;
-    /** OpenTelemetry span ID for distributed tracing */
-    spanId?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Parameters for tracking an LLM decision event
- */
-interface TrackDecisionParams {
-    /** Session ID */
-    sessionId: string;
-    /** Decision reasoning */
-    reasoning: string;
-    /** Alternative options considered */
-    alternatives?: string[];
-    /** Confidence score (0.0 to 1.0) */
-    confidence?: number;
-    /** Estimated cost in USD for this decision */
-    estimatedCost?: number;
-    /** Number of tokens used */
-    tokenCount?: number;
-    /** OpenTelemetry trace ID for distributed tracing */
-    traceId?: string;
-    /** OpenTelemetry span ID for distributed tracing */
-    spanId?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Parameters for tracking an error event
- */
-interface TrackErrorParams {
-    /** Session ID */
-    sessionId: string;
-    /** Error message */
-    errorMessage: string;
-    /** Type of error (e.g., "ValueError", "APIError") */
-    errorType?: string;
-    /** Name of the tool that caused the error (if applicable) */
-    toolName?: string;
-    /** Stack trace for debugging */
-    stackTrace?: string;
-    /** OpenTelemetry trace ID for distributed tracing */
-    traceId?: string;
-    /** OpenTelemetry span ID for distributed tracing */
-    spanId?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Event data returned from the API
- */
-interface Event {
-    id: string;
-    sessionId: string;
-    eventType: EventType;
-    timestamp: Date;
-    sequenceNumber: number;
-    toolName?: string;
-    toolInput?: Record<string, unknown>;
-    toolOutput?: Record<string, unknown>;
-    toolError?: Record<string, unknown>;
-    reasoning?: string;
-    alternativesConsidered?: string[];
-    confidence?: number;
-    stateBefore?: Record<string, unknown>;
-    stateAfter?: Record<string, unknown>;
-    stateDiff?: Record<string, unknown>;
-    estimatedCost?: number;
-    tokenCount?: number;
-    metadata?: Record<string, unknown>;
-    traceId?: string;
-    spanId?: string;
-}
-/**
- * Parameters for beginning an interaction
- */
-interface BeginParams {
-    /** External user ID for grouping sessions */
-    userId: string;
-    /** Event type/name (e.g., "chat_message", "search_query") */
-    event: string;
-    /** Optional input data for the interaction */
-    input?: string;
-    /** Optional custom event ID (auto-generated UUID if not provided) */
-    eventId?: string;
-    /** Optional conversation ID to group related interactions */
-    convoId?: string;
-    /** Optional additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Parameters for finishing an interaction
- */
-interface FinishParams {
-    /** Output/response from the interaction */
-    output?: string;
-    /** Whether the interaction succeeded (default: true) */
-    success?: boolean;
-    /** Reason for failure if success=false */
-    failureReason?: string;
-    /** Total estimated cost in USD */
-    estimatedCost?: number;
-    /** Custom metrics */
-    customMetrics?: Record<string, number>;
-    /** Number of prompt/input tokens used */
-    promptTokens?: number;
-    /** Number of completion/output tokens used */
-    completionTokens?: number;
-    /** Total tokens used */
-    totalTokens?: number;
-    /** Duration in milliseconds (auto-calculated from begin/finish if not provided) */
-    durationMs?: number;
-}
-/**
- * Parameters for cost calculation
- */
-interface CostParams {
-    /** Model name (e.g., "gpt-4", "claude-3-sonnet") */
-    model: string;
-    /** Number of input tokens */
-    inputTokens: number;
-    /** Number of output tokens */
-    outputTokens: number;
-}
-/**
- * Standard API response wrapper
- */
-interface ApiResponse<T> {
-    data?: T;
-    error?: {
-        code: string;
-        message: string;
-        details?: Record<string, unknown>;
-    };
+interface DispatchContext extends ActionIdentity {
+    version: 'sentrial-handoff-v2';
+    parentSessionId: string;
+    dispatchId: string;
 }
+type HandoffOutcome = 'completed' | 'failed' | 'cancelled';
+declare function actionMetadata(identity: ActionIdentity, metadata?: Record<string, unknown>): Record<string, unknown>;
+declare function createHandoffContext(input: ActionIdentity & {
+    parentSessionId: string;
+}): string;
+declare function resumeHandoffContext(carrier: string, metadata?: Record<string, unknown>): {
+    parentSessionId: string;
+    metadata: Record<string, unknown>;
+};
+/** Use a new dispatchId for each execution; keep it stable only for transport retries. */
+declare function createDispatchContext(input: ActionIdentity & {
+    parentSessionId: string;
+    dispatchId: string;
+}): string;
 
 /**
  * Cost calculation utilities for various LLM providers
@@ -660,15 +324,140 @@ declare function calculateAnthropicCost(params: CostParams): number;
  * ```
  */
 declare function calculateGoogleCost(params: CostParams): number;
-
 /**
- * Sentrial Client - Main SDK interface
- *
- * Captures agent sessions, tool calls, and metrics. This data powers:
- * - Signal detection (auto-detect patterns/anomalies)
- * - Root cause analysis (understand WHY agents fail)
- * - Code fixer (AI-suggested fixes with GitHub PRs)
- */
+ * Provider → cost dispatch. SINGLE source shared by the Vercel AI SDK wrapper (vercel.ts) and the
+ * Mastra SDK so a provider is billed identically across integrations — previously each carried its
+ * own switch and the Mastra copy dropped flat-rate providers to $0 (#488/#559).
+ *
+ * UNIFIED CROSS-SDK FALLBACK POLICY (lockstep with the Python SDK's `resolve_provider_cost` in
+ * packages/python-sdk/sentrial/pricing.py, guarded by tests/test_pricing_sync.py). The chain,
+ * identical in both SDKs:
+ *   1. Resolve the provider HINT tolerantly, by SUBSTRING — OTel-semconv spellings like
+ *      'az.ai.openai' or 'mistral_ai' resolve to the correct table (openai/anthropic/google first,
+ *      then the flat-rate providers). A hint that resolves nothing falls back to inferring the
+ *      provider from the model id (guessProvider), so an empty/'unknown'/'gateway' hint never
+ *      forces the default block when the model id names its family.
+ *   2. A gateway 'creator/model' id whose creator is a FLAT-rate provider bills that flat rate
+ *      regardless of the hint (an Anthropic-compatible gateway may carry a keyset hint).
+ *   3. openai/anthropic/google bill on their per-model tables; a gateway creator naming one of
+ *      them wins the table choice and the slash prefix is always stripped for the key match. An
+ *      UNKNOWN model within a known provider bills the provider's cheap-modern
+ *      `fallback.{provider}` key (never an expensive legacy flagship).
+ *   4. Flat-rate providers (deepseek/cohere/mistral) bill their canonical `flatProviders` rate.
+ *   5. A GENUINELY unknown provider (including recognized-but-unpriced families like meta/llama
+ *      and alibaba/qwen) bills the shared cheap `fallback.default` block — NEVER a silent $0,
+ *      which would understate real spend. (Unified Jul 2026; this dispatch previously returned $0
+ *      here while Python billed the default block.)
+ * All rates come from the canonical pricing.json (fallback.default included).
+ */
+declare function calculateCostByProvider(provider: string, model: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Usage shape accepted by {@link normalizeUsage} — supports both AI SDK v3/v4
+ * (promptTokens/completionTokens, OpenAI naming) and v5/v6 (inputTokens/outputTokens,
+ * generic naming). All fields optional; a `totalTokens` may be present on either.
+ */
+type NormalizableUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+};
+type NormalizedUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+/**
+ * Normalize LLM usage from any Vercel AI SDK version (and Mastra, which follows AI SDK naming)
+ * into a consistent { promptTokens, completionTokens, totalTokens } shape; returns undefined when
+ * there is no usage or every count is zero.
+ *
+ * AI SDK v3/v4 uses promptTokens/completionTokens (OpenAI naming); v5/v6 uses
+ * inputTokens/outputTokens (generic naming). This is the SINGLE canonical implementation shared by
+ * the Vercel AI SDK wrapper (vercel.ts) and the Mastra SDK, which previously each carried a
+ * divergent copy: vercel.ts coerced with `|| 0` (NaN/non-numeric -> 0) while mastra used `?? 0`
+ * (nullish-only, so a NaN or a non-numeric field could leak straight through). We adopt the SAFER
+ * `|| 0`-style semantics here via `firstTokenCount` (an explicit Number.isFinite guard applied to
+ * BOTH the field selection and the final value) so a malformed usage object can never surface
+ * NaN/garbage token counts or costs, and a NaN primary field (e.g. inputTokens) falls through to a
+ * valid secondary (promptTokens) rather than masking it — this does not change behavior for real
+ * numeric inputs, and only tightens the previously looser mastra path.
+ */
+declare function normalizeUsage(usage: NormalizableUsage | Record<string, unknown> | undefined): NormalizedUsage | undefined;
+declare function guessProvider(modelId: string): string;
+/**
+ * Canonical "normalize raw AI-SDK usage → prompt/completion/total token counts → cost via
+ * calculateCostByProvider(provider, model, ...)" derivation, shared by BOTH AI-SDK wrappers
+ * (Vercel `resolveTokensAndCost` call sites and the Mastra integration). Lives here — beside
+ * normalizeUsage + calculateCostByProvider — so the two wrappers can never drift on how they
+ * fold provider-extra token fields; previously only the Vercel copy folded Anthropic
+ * cachedInputTokens / Google reasoningTokens, so @sentrial/mastra silently under-billed
+ * cache-read-heavy Anthropic and thinking-heavy Google calls.
+ *
+ * totalTokens comes from normalizeUsage, which already falls back to promptTokens+completionTokens,
+ * so this preserves the stricter sum-fallback everywhere (no caller regresses to `?? 0`). The
+ * containment arithmetic gates each fold so subset-reporting providers (OpenAI) and AI-SDK v7
+ * (fields moved into inputTokenDetails/outputTokenDetails) can never double-count.
+ */
+/**
+ * Fold AI-SDK provider-extra token fields into flat prompt/completion/total counts.
+ *
+ * AI SDK v5/v6 report provider extras as separate top-level fields that our flat reads drop:
+ * - Anthropic: inputTokens EXCLUDES cache reads (cachedInputTokens is EXTRA; total = in+out)
+ * - Google: outputTokens EXCLUDES thinking (reasoningTokens; total = in+out+reasoning)
+ * OpenAI reports both as SUBSETS (already inside the flat counts), and v7 moved the fields into
+ * inputTokenDetails/outputTokenDetails (absent here) — so each fold is gated on the containment
+ * arithmetic so subset-reporting providers and v7 can never double-count. Shared by BOTH AI-SDK
+ * wrappers (resolveTokensAndCost + the Mastra per-step aggregator) so they can never drift.
+ */
+declare function foldProviderExtras(rawUsage: NormalizableUsage | Record<string, unknown> | undefined, provider: string, base: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /**
+     * The Anthropic cache-READ tokens folded into `promptTokens` (0 when no fold applied). Reported
+     * token COUNTS stay cache-inclusive, but cost must weight this slice at
+     * {@link ANTHROPIC_CACHE_READ_MULTIPLIER} (0.1x), matching the direct wrapAnthropic path — so
+     * callers computing cost subtract 0.9x of this back out. See resolveTokensAndCost.
+     */
+    foldedCachedInputTokens: number;
+};
+declare function resolveTokensAndCost(rawUsage: NormalizableUsage | Record<string, unknown> | undefined, provider: string, model: string, 
+/**
+ * Anthropic cache-READ tokens already folded into `rawUsage`'s prompt count by an UPSTREAM
+ * per-step pass (the Mastra aggregator folds each step before summing, then discards the raw
+ * `cachedInputTokens` field so foldProviderExtras here can't re-derive it). Pass the summed
+ * folded count so the 0.1x cache-read discount is still applied to the cost basis. Omit (0)
+ * for the normal single-usage path, where foldProviderExtras below computes the fold itself.
+ */
+preFoldedCachedInputTokens?: number): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost: number;
+};
+
+declare const AGENT_DIAGNOSTIC_CATEGORIES: readonly ["missing_context", "tool_problem", "missing_capability", "uncertain_completion"];
+interface AgentDiagnosticInput {
+    /** Opaque identifier reused for subsequent reports within this session. */
+    reportId: string;
+    category: (typeof AGENT_DIAGNOSTIC_CATEGORIES)[number];
+    /** Both states are assertions by the agent, including claimed recovery. */
+    state: 'reported' | 'recovered';
+    description: string;
+    /** Optional related OTel span IDs in this trace; these are unverified references. */
+    relatedSpanIds?: readonly string[];
+}
+interface AgentDiagnostic extends Omit<AgentDiagnosticInput, 'relatedSpanIds'> {
+    revision: 'agent-diagnostic-v1';
+    origin: 'agent_report';
+    relatedSpanIds: readonly string[];
+}
 
 /**
  * Sentrial Client for agent observability.
@@ -709,6 +498,18 @@ declare function calculateGoogleCost(params: CostParams): number;
  * By default, the SDK fails silently (failSilently=true) to ensure
  * monitoring never crashes your application. Set failSilently=false
  * during development to see errors.
+ *
+ * Containment seam (the never-crash contract's enforcement point): every public tracking
+ * entrypoint on this client (and on Interaction) is wrapped by `containMethod` (see
+ * contained.ts and the application block at the bottom of this file) — the ENTIRE method
+ * body runs inside one try honoring `failSilently`. Any exception escaping a method body
+ * is caught at the method boundary: with failSilently=true (default) it is logged once per
+ * method and the method's degraded value is returned (null / undefined / a degraded
+ * Interaction); with failSilently=false it rethrows/rejects unchanged. Interior guards
+ * (toText, safeJsonStringify, capStateSnapshot, accumulate's safeNum, the toolError field
+ * accessors) remain for DATA QUALITY: they let a tracking call still succeed with degraded
+ * values instead of the seam dropping the whole call. Mirrors the Python SDK's
+ * `_wire.contained` decorations.
  */
 declare class SentrialClient {
     private readonly apiUrl;
@@ -719,8 +520,26 @@ declare class SentrialClient {
     private piiHydrationPromise?;
     private readonly _stateVar;
     private readonly batcher?;
+    private readonly contentUploader?;
+    private readonly transportDiagnostics;
+    private readonly otlpSessions;
+    /** Every ambient OTel traceId this client has EVER consumed for a session — permanent (bounded,
+     * FIFO) because the server's otel-sess:<traceId> fallback key is permanent; see claimTraceId. */
+    private readonly consumedAmbientTraceIds;
+    private pendingExperimentAssignmentIds;
     /** Per-session cost/token accumulator — populated by trackToolCall/trackDecision */
     private sessionAccumulators;
+    /**
+     * Accumulators for sessions that never call completeSession() — e.g. a mastra stream the caller
+     * abandons without consuming, so its onFinish never fires — are evicted after this TTL so their
+     * bookkeeping can't linger. The TTL is measured from LAST ACTIVITY (accumulate() refreshes the
+     * entry's timestamp), so an actively-tracking long-running session is never dropped — only
+     * sessions idle for 2h expire. The accumulator is only a fallback for callers that don't pass
+     * explicit cost/tokens to finish (#561).
+     */
+    private static readonly ACCUMULATOR_TTL_MS;
+    /** Hard cap on live accumulator entries — backstop for the TTL sweep (#561). */
+    private static readonly MAX_ACCUMULATORS;
     private get currentState();
     private set currentState(value);
     constructor(config?: SentrialClientConfig);
@@ -737,7 +556,14 @@ declare class SentrialClient {
      * Retries on transient failures (network errors, timeouts, 429/5xx).
      * Up to MAX_RETRIES attempts with exponential backoff.
      */
+    /**
+     * Public wrapper around the retrying transport (exponential backoff, 10s timeout,
+     * PII redaction, structured ApiError/NetworkError) so callers like Experiment reuse
+     * it instead of hand-rolling a bare fetch (#482).
+     */
+    apiRequest<T>(method: string, url: string, body?: unknown): Promise<T | null>;
     private safeRequest;
+    private requestWithRetries;
     private sleep;
     private accumulate;
     /**
@@ -746,26 +572,38 @@ declare class SentrialClient {
      * @param params - Session creation parameters
      * @returns Session ID, or null if the request failed and failSilently is true
      */
+    /** Build the dependency bundle the OTLP transport needs (private members accessed here). */
+    private otlpDeps;
     createSession(params: CreateSessionParams): Promise<string | null>;
+    /**
+     * Get a sticky production experiment variant for this user/conversation.
+     *
+     * The returned assignment id is automatically linked to the next session
+     * created by this client. You can also pass `sessionId` to link immediately.
+     */
+    getVariant(params: GetVariantParams): Promise<VariantAssignment>;
+    /** Report only after using this configuration. getVariant/createSession never imply exposure.
+     * Returns null on fail-silent delivery failure; safe to retry with the same fields. */
+    recordExperimentExposure(params: RecordExperimentExposureParams): Promise<ExperimentExposureReceipt | null>;
     /**
      * Track a tool call event
      *
      * @param params - Tool call parameters
-     * @returns Event data
+     * @returns `null` — the OTLP transport emits a span and does not return a synchronous event
      */
     trackToolCall(params: TrackToolCallParams): Promise<Event | null>;
     /**
      * Track an LLM decision event
      *
      * @param params - Decision parameters
-     * @returns Event data
+     * @returns `null` — the OTLP transport emits a span and does not return a synchronous event
      */
     trackDecision(params: TrackDecisionParams): Promise<Event | null>;
     /**
      * Track an error event
      *
      * @param params - Error parameters
-     * @returns Event data
+     * @returns `null` — the OTLP transport emits a span and does not return a synchronous event
      */
     trackError(params: TrackErrorParams): Promise<Event | null>;
     /**
@@ -778,17 +616,47 @@ declare class SentrialClient {
     /**
      * Set the user input for a session
      *
+     * Re-posts the session's root span (start-only, no end time) with the updated
+     * `gen_ai.input.messages` so the server refreshes `sessions.userInput` WITHOUT finalizing the
+     * session — it stays running. Always resolves `null` under the OTLP transport (no synchronous session row).
+     *
      * @param sessionId - Session ID
      * @param input - User input text
-     * @returns Updated session or null on error
+     * @returns `null` — the OTLP transport does not return a synchronous session row
      */
     setInput(sessionId: string, input: string): Promise<Session | null>;
     /**
-     * Track a generic event
+     * Merge additional metadata into a running session (post-begin).
+     *
+     * No network call: the merged metadata is carried on the finalize re-post, where the server
+     * merges it into the session's metadata (user keys top-level, later values win on a key
+     * collision; the reserved `otel` diagnostics key is preserved server-side). String values are
+     * redacted like begin()'s metadata.
      *
-     * @param params - Event parameters
-     * @returns Event data or null on error
+     * @param sessionId - Session ID
+     * @param metadata - Metadata keys to merge into the session metadata
      */
+    setSessionMetadata(sessionId: string, metadata: Record<string, unknown>): void;
+    /**
+     * Set/override the session-level model for a running session (post-begin).
+     *
+     * No network call: carried on the finalize re-post as gen_ai.request.model and under the
+     * stable `model` key in the session metadata (the sessions table has no model column).
+     *
+     * @param sessionId - Session ID
+     * @param model - Model identifier (e.g. 'claude-sonnet-4-5')
+     */
+    setSessionModel(sessionId: string, model: string): void;
+    /**
+     * Record an optional agent assertion, including claimed recovery. No model call,
+     * automatic error status, state snapshot, or verified failure label is created.
+     * Reuse reportId within this session for later observations; each is retained.
+     */
+    reportDiagnostic(params: {
+        sessionId: string;
+        report: AgentDiagnosticInput;
+    }): Promise<null>;
+    /** Track a generic event. */
     trackEvent(params: {
         sessionId: string;
         eventType: string;
@@ -801,7 +669,8 @@ declare class SentrialClient {
      * This is the recommended way to close sessions for performance monitoring.
      *
      * @param params - Session completion parameters
-     * @returns Updated session data
+     * @returns `null` — the OTLP transport re-posts the final root span and the server finalizes
+     *   the session asynchronously, so no session row is returned synchronously.
      *
      * @example
      * ```ts
@@ -825,14 +694,41 @@ declare class SentrialClient {
     /**
      * Flush any queued events immediately.
      *
-     * No-op if batching is not enabled.
+     * Waits for pending content uploads before draining queued telemetry.
      */
     flush(): Promise<void>;
+    /** Queue delivery health; null when batching is disabled. Contains no payloads. */
+    getDeliveryDiagnostics(): Readonly<DeliveryDiagnostics> | null;
+    /** Content upload counts only; submitted bytes may still await server verification. */
+    getContentUploadDiagnostics(): {
+        attempted: number;
+        submitted: number;
+        missing: number;
+        active: number;
+        pendingEvents: number;
+    } | null;
+    /** Bounded process-local OTLP request/response diagnostics, independent of batching. */
+    getTransportDiagnostics(): TransportDiagnosticsSnapshot;
+    /** Record delegation before dispatch, then pass the returned carrier to the worker. */
+    handoff(identity: ActionIdentity & {
+        sessionId: string;
+    }): Promise<string>;
+    /** Emit before queueing work. This records intent, not queue delivery acknowledgment. */
+    dispatchHandoff(identity: ActionIdentity & {
+        sessionId: string;
+        dispatchId: string;
+    }): Promise<string>;
+    acceptHandoff(sessionId: string, carrier: string): Promise<void>;
+    /** Call before finishing the worker session. Outcome describes execution, not business success. */
+    finishHandoff(sessionId: string, carrier: string, outcome: HandoffOutcome): Promise<void>;
+    /** Call in the parent only after receiving this worker's terminal result. */
+    receiveHandoff(sessionId: string, carrier: string, workerSessionId: string, outcome: HandoffOutcome): Promise<void>;
+    private recordHandoff;
     /**
      * Shut down the event batcher, flushing remaining events.
      *
      * Call this before your process exits for a clean shutdown.
-     * No-op if batching is not enabled.
+     * Cancels pending content uploads, then drains their fallback events and queued telemetry.
      */
     shutdown(): Promise<void>;
     /**
@@ -887,7 +783,6 @@ declare class Interaction {
     readonly userId: string;
     /** Event name for this interaction */
     readonly event: string;
-    private readonly startTime;
     private finished;
     private success;
     private failureReason?;
@@ -906,11 +801,30 @@ declare class Interaction {
      * @param output - The output/response text
      */
     setOutput(output: string): void;
+    /**
+     * Merge additional metadata into this interaction's session (post-begin).
+     *
+     * Carried on the finish() re-post: the server merges the keys into the session's metadata
+     * top-level (later values win; the reserved `otel` diagnostics key is preserved).
+     *
+     * @param metadata - Metadata keys to merge into the session metadata
+     */
+    setMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Set/override the session-level model for this interaction (post-begin).
+     *
+     * Carried on the finish() re-post as gen_ai.request.model and under the stable `model` key in
+     * the session metadata.
+     *
+     * @param model - Model identifier (e.g. 'claude-sonnet-4-5')
+     */
+    setModel(model: string): void;
     /**
      * Finish the interaction and record metrics
      *
      * @param params - Finish parameters
-     * @returns Updated session data, or null if degraded/already finished
+     * @returns `null` — the OTLP transport finalizes asynchronously server-side (also `null`
+     *   if degraded/already finished).
      *
      * @example
      * ```ts
@@ -926,6 +840,8 @@ declare class Interaction {
      * Track a tool call within this interaction
      */
     trackToolCall(params: Omit<TrackToolCallParams, 'sessionId'>): Promise<Event | null>;
+    /** Report an agent observation without changing this interaction's success or failure. */
+    reportDiagnostic(report: AgentDiagnosticInput): Promise<null>;
     /**
      * Track an LLM decision within this interaction
      */
@@ -986,6 +902,8 @@ declare function configure(config: SentrialClientConfig): void;
  * ```
  */
 declare function begin(params: BeginParams): Promise<Interaction>;
+declare function getVariant(params: GetVariantParams): Promise<VariantAssignment>;
+declare function recordExperimentExposure(params: RecordExperimentExposureParams): Promise<ExperimentExposureReceipt | null>;
 /**
  * Simple API namespace for module-level usage
  */
@@ -994,6 +912,8 @@ declare function shutdown(): Promise<void>;
 declare const sentrial: {
     configure: typeof configure;
     begin: typeof begin;
+    getVariant: typeof getVariant;
+    recordExperimentExposure: typeof recordExperimentExposure;
     flush: typeof flush;
     shutdown: typeof shutdown;
 };
@@ -1047,7 +967,11 @@ declare class NetworkError extends SentrialError {
     constructor(message: string, cause?: Error);
 }
 /**
- * Error thrown when validation fails
+ * Error thrown when validation fails.
+ *
+ * @deprecated The SDK no longer throws this internally. Retained as a public export for backwards
+ * compatibility with downstream consumers that import it; slated for removal in a future MINOR/MAJOR
+ * release (not a patch), per the SDK compatibility policy.
  */
 declare class ValidationError extends SentrialError {
     constructor(message: string, details?: Record<string, unknown>);
@@ -1057,7 +981,7 @@ declare class ValidationError extends SentrialError {
  * Vercel AI SDK Integration for Sentrial
  *
  * Automatically traces AI SDK calls with full input/output logging, metrics, and tool execution.
- * Supports Vercel AI SDK v3, v4, v5, and v6.
+ * Supports Vercel AI SDK v3 through v7.
  *
  * @example Simple Usage
  * ```ts
@@ -1093,13 +1017,16 @@ declare class ValidationError extends SentrialError {
  * @packageDocumentation
  */
 
+type AnyFunction = (...args: unknown[]) => unknown;
 type AIModule = {
-    generateText?: Function;
-    streamText?: Function;
-    generateObject?: Function;
-    streamObject?: Function;
-    experimental_generateText?: Function;
-    experimental_streamText?: Function;
+    generateText?: AnyFunction;
+    streamText?: AnyFunction;
+    generateObject?: AnyFunction;
+    streamObject?: AnyFunction;
+    experimental_generateText?: AnyFunction;
+    experimental_streamText?: AnyFunction;
+    experimental_generateObject?: AnyFunction;
+    experimental_streamObject?: AnyFunction;
 };
 type GenerateTextParams = {
     model: {
@@ -1113,7 +1040,7 @@ type GenerateTextParams = {
     }>;
     system?: string;
     tools?: Record<string, {
-        execute?: Function;
+        execute?: AnyFunction;
     } & Record<string, unknown>>;
     maxTokens?: number;
     maxSteps?: number;
@@ -1143,6 +1070,16 @@ type StepResult = {
     }>;
     usage?: UsageInfo;
     finishReason?: string;
+    /** Per-step response metadata — v5+ modelId, v3/v4 model. */
+    response?: {
+        modelId?: string;
+        model?: string;
+    };
+    /** v6+: the model that produced this step (prepareStep can switch mid-call). */
+    model?: {
+        provider?: string;
+        modelId?: string;
+    };
 };
 type GenerateTextResult = {
     text: string;
@@ -1217,10 +1154,10 @@ declare function configureVercel(config: {
     convoId?: StringOrFn;
     failSilently?: boolean;
 }): void;
-declare function wrapGenerateText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<GenerateTextResult>;
-declare function wrapStreamText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => StreamTextResult;
-declare function wrapGenerateObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<unknown>;
-declare function wrapStreamObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => unknown;
+declare function wrapGenerateText(originalFn: AnyFunction, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<GenerateTextResult>;
+declare function wrapStreamText(originalFn: AnyFunction, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => StreamTextResult;
+declare function wrapGenerateObject(originalFn: AnyFunction, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<unknown>;
+declare function wrapStreamObject(originalFn: AnyFunction, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => unknown;
 /**
  * Wrap the Vercel AI SDK to automatically trace all AI calls.
  *
@@ -1257,6 +1194,61 @@ declare function wrapAISDK(ai: AIModule, options?: {
     streamObject: ReturnType<typeof wrapStreamObject>;
 };
 
+/**
+ * Options shape accepted by {@link getVariantForAISDK} — a permissive subset of
+ * an AI SDK `generateText` / `streamText` call. Extra keys are preserved, so it
+ * composes with whatever options you already build.
+ */
+type AISDKVariantOptions = {
+    model?: unknown;
+    system?: string;
+    prompt?: string;
+    messages?: unknown;
+    experimental_telemetry?: {
+        isEnabled?: boolean;
+        metadata?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+};
+/**
+ * Resolve a production A/B variant and merge it into Vercel AI SDK call options.
+ *
+ * Pairs `client.getVariant()` with a `generateText` / `streamText` call: it
+ * fetches the sticky assignment for this user/convo, applies the variant's
+ * `systemPrompt`, `prompt`, and (via `modelResolver`, since the AI SDK needs a
+ * model *object*, not a string) `model`, and tags the call's
+ * `experimental_telemetry.metadata` with the experiment + variant so the
+ * exposure is visible on the resulting session. Returns the merged options
+ * (spread straight into your `generateText` call) and the raw assignment so you
+ * can branch on `assignment.variant`.
+ *
+ * The assignment is recorded server-side by `getVariant` regardless of whether a
+ * variant config is applied, so a `reason: 'holdout'` / `'not_found'` result is
+ * safe — the base options pass through unchanged (sticky control).
+ *
+ * @example
+ * ```ts
+ * import { openai } from '@ai-sdk/openai';
+ * import { wrapAISDK, getVariantForAISDK } from '@sentrial/sdk';
+ * import * as ai from 'ai';
+ *
+ * const { generateText } = wrapAISDK(ai);
+ * const { options, assignment } = await getVariantForAISDK(
+ *   { experimentName: 'support-prompt-v2', userId, convoId },
+ *   { model: openai('gpt-4o-mini'), system: 'You are a support agent.', prompt: userQuery },
+ *   { modelResolver: (id) => openai(id) }
+ * );
+ * const { text } = await generateText(options); // runs the assigned variant, tracked
+ * ```
+ */
+declare function getVariantForAISDK<T extends AISDKVariantOptions>(variantParams: GetVariantParams, baseOptions: T, opts?: {
+    modelResolver?: (modelId: string) => unknown;
+    client?: SentrialClient;
+}): Promise<{
+    options: T;
+    assignment: VariantAssignment;
+}>;
+
 /**
  * Sentrial wrapper for the Claude Agent SDK (Claude Code).
  *
@@ -1321,6 +1313,487 @@ interface WrapClaudeAgentOptions {
  */
 declare function wrapClaudeAgent(queryFn: QueryFunction, wrapOptions: WrapClaudeAgentOptions): QueryFunction;
 
+/**
+ * OpenAI Agents SDK Integration for Sentrial
+ *
+ * Observes the OpenAI Agents SDK's (`@openai/agents`) tracing pipeline and maps
+ * every trace onto a Sentrial session via the `begin()`/Interaction API:
+ *
+ * - **trace start** → `begin()` (agent/event name from the root agent span,
+ *   falling back to the trace's workflow name; session title from the trace name)
+ * - **generation / response spans** → per-call LLM events (`llm:{model}` tool name
+ *   convention, prompt/completion tokens from usage, cost via the pricing tables,
+ *   duration from the span's start/end timestamps)
+ * - **function spans** → `trackToolCall` (name, parsed args, result, errors)
+ * - **handoff spans** → `trackDecision` ("Handoff from X to Y")
+ * - **guardrail spans** → `trackError` when triggered, `trackDecision` when passed
+ * - **trace end** → `finish()` (aggregated tokens/cost, last LLM output as the
+ *   session output, failure state from root agent span errors / triggered guardrails)
+ *
+ * Distinction from {@link wrapOpenAI}:
+ * `wrapOpenAI` wraps a RAW `openai` client instance so each LLM call is tracked
+ * inside a session YOU manage with `begin()`. This module instead observes the
+ * OpenAI **Agents SDK** runtime (`Agent` + `run`) from the outside via its
+ * documented tracing-processor hook — each agent run becomes a full Sentrial
+ * session automatically, including tool calls, handoffs, and guardrails. If you
+ * use the Agents SDK, prefer this module; don't combine both on the same run or
+ * LLM calls will be double-counted.
+ *
+ * Verified against the official OpenAI Agents JS SDK
+ * (https://openai.github.io/openai-agents-js/ and the `@openai/agents-core`
+ * tracing sources): `TracingProcessor` is `onTraceStart/onTraceEnd/onSpanStart/
+ * onSpanEnd(…): Promise<void>` + `shutdown(timeout?)`/`forceFlush()`; `Trace`
+ * exposes camelCase `traceId/name/groupId/metadata`; `Span` exposes
+ * `traceId/spanId/parentId/startedAt/endedAt/error/spanData` with ISO-string
+ * timestamps and a `SpanError { message, data? }`; `SpanData` fields are
+ * snake_case (`from_agent`, `to_agent`, `mcp_data`, usage `input_tokens`/
+ * `output_tokens`; `ResponseSpanData` carries the raw Responses API payload on
+ * `_response`). Registration is `addTraceProcessor(processor)` (additive — the
+ * default OpenAI-dashboard exporter keeps running alongside).
+ *
+ * The `@openai/agents` package stays an optional peer dependency: like
+ * `wrapAISDK(ai)`, the module never imports it — you hand `addTraceProcessor`
+ * (or the module namespace that carries it) to {@link instrumentOpenAIAgents}.
+ *
+ * @example
+ * ```ts
+ * import { Agent, run, addTraceProcessor } from '@openai/agents';
+ * import { sentrial, instrumentOpenAIAgents } from '@sentrial/sdk';
+ *
+ * sentrial.configure({ apiKey: process.env.SENTRIAL_API_KEY });
+ * instrumentOpenAIAgents({ addTraceProcessor }, { userId: 'user_123' });
+ *
+ * const agent = new Agent({ name: 'Assistant', instructions: 'Be helpful.' });
+ * const result = await run(agent, 'Write a haiku about recursion.');
+ * // The run is now a Sentrial session with LLM events, tool calls, handoffs.
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** The subset of `Trace` this processor reads (camelCase, per agents-core). */
+type AgentsTrace = {
+    traceId?: string;
+    name?: string;
+    groupId?: string | null;
+    metadata?: Record<string, unknown>;
+};
+/** `SpanError` shape (`span.error`). */
+type AgentsSpanError = {
+    message?: string;
+    data?: Record<string, unknown>;
+};
+/** The subset of `Span` this processor reads (camelCase getters, ISO timestamps). */
+type AgentsSpan = {
+    traceId?: string;
+    spanId?: string;
+    parentId?: string | null;
+    startedAt?: string | null;
+    endedAt?: string | null;
+    error?: AgentsSpanError | null;
+    spanData?: Record<string, unknown> & {
+        type?: string;
+    };
+};
+/** The one entry point we need from `@openai/agents` / `@openai/agents-core`. */
+type AgentsModuleLike = {
+    addTraceProcessor: (processor: unknown) => void;
+};
+interface OpenAIAgentsProcessorOptions {
+    /** Explicit SentrialClient. Defaults to a client from the environment (SENTRIAL_API_KEY). */
+    client?: SentrialClient;
+    /** Explicit agent/event name override (defaults to the root agent span's name per run). */
+    defaultAgent?: string;
+    /** User ID to associate with sessions (default 'anonymous'). */
+    userId?: string;
+    /** Extra metadata merged into every session. */
+    extraMetadata?: Record<string, unknown>;
+}
+/**
+ * Duck-typed `TracingProcessor` (from `@openai/agents-core`) that mirrors OpenAI
+ * Agents SDK runs into Sentrial sessions.
+ *
+ * Register it via {@link instrumentOpenAIAgents}, or directly:
+ * ```ts
+ * import { addTraceProcessor } from '@openai/agents';
+ * addTraceProcessor(new SentrialOpenAIAgentsProcessor({ client }));
+ * ```
+ *
+ * Every callback body is containment-wrapped: the Agents SDK awaits these
+ * methods inline on the user's run path, so a tracking failure must never
+ * reject into the host agent — it is swallowed instead (the SentrialClient/
+ * Interaction methods additionally carry their own containment seam).
+ *
+ * Performance tip: construct the client with `batching: { enabled: true }` so
+ * `track*` calls enqueue instead of awaiting a network round-trip per span.
+ * (The TS BatcherConfig takes an object — a bare `batching: true` is silently
+ * ignored; the Python SDK's `batching=True` bool shorthand has no TS twin.)
+ */
+declare class SentrialOpenAIAgentsProcessor {
+    private clientRef?;
+    private readonly defaultAgent?;
+    private readonly userId;
+    private readonly extraMetadata;
+    private readonly traces;
+    private tracesCapWarned;
+    constructor(options?: OpenAIAgentsProcessorOptions);
+    /** Optional TracingProcessor lifecycle hook — nothing to start. */
+    start(): void;
+    onTraceStart(trace: AgentsTrace): Promise<void>;
+    onTraceEnd(trace: AgentsTrace): Promise<void>;
+    onSpanStart(span: AgentsSpan): Promise<void>;
+    onSpanEnd(span: AgentsSpan): Promise<void>;
+    /**
+     * Called at application stop: finishes any still-open sessions as interrupted
+     * and flushes the client's event queue (if batching).
+     */
+    shutdown(_timeout?: number): Promise<void>;
+    /** Forces immediate processing of queued events (no-op without batching). */
+    forceFlush(): Promise<void>;
+    private resolveClient;
+    private flushClient;
+    private handleTraceStart;
+    private stateFor;
+    /**
+     * Begin the Sentrial session for this trace exactly once. Event/agent name
+     * preference: explicit `defaultAgent` > root agent span name > trace workflow
+     * name > 'openai-agents'. The session title is the trace's workflow name.
+     *
+     * DELIBERATE cross-SDK divergence on begin failure: the rejected promise is
+     * cached, so a trace whose begin() failed never retries (avoids a partial
+     * session whose earlier spans were lost). The Python twin leaves
+     * `interaction=None` and retries at the next span (favoring late recovery).
+     * Both are documented choices, not drift.
+     */
+    private ensureInteraction;
+    private handleSpanStart;
+    private handleSpanEnd;
+    private trackLLMEvent;
+    private trackFunction;
+    private trackHandoff;
+    private trackGuardrail;
+    private handleTraceEnd;
+    private finishState;
+}
+/**
+ * Construct a {@link SentrialOpenAIAgentsProcessor} and register it with the
+ * OpenAI Agents SDK. Pass the SDK's `addTraceProcessor` (or any object carrying
+ * it, e.g. the whole `@openai/agents` module namespace) — the peer dependency is
+ * never imported here, mirroring `wrapAISDK(ai)`.
+ *
+ * Idempotent per (agents module, client) pair: calling this again with the same
+ * `addTraceProcessor` and the same `options.client` (or again with no client —
+ * the env-default) returns the FIRST registered processor instead of registering
+ * a duplicate, which would mirror every run into two sessions. The first
+ * duplicate call emits a console warning (silent thereafter).
+ *
+ * @example
+ * ```ts
+ * import * as agents from '@openai/agents';
+ * import { instrumentOpenAIAgents } from '@sentrial/sdk';
+ *
+ * instrumentOpenAIAgents(agents, { userId: 'user_123' });
+ * ```
+ *
+ * @param agents - The `@openai/agents` module namespace (or `{ addTraceProcessor }`).
+ * @param options - Processor options (client, defaultAgent, userId, extraMetadata).
+ * @returns The registered processor (keep it to call `shutdown()`/`forceFlush()`).
+ */
+declare function instrumentOpenAIAgents(agents: AgentsModuleLike, options?: OpenAIAgentsProcessorOptions): SentrialOpenAIAgentsProcessor;
+
+/**
+ * Google Agent Development Kit (ADK) Integration for Sentrial — TypeScript twin
+ * of the Python `sentrial.google_adk` module, ported for `adk-js` (`@google/adk`).
+ *
+ * Maps a Google ADK **run** (one `Runner.runAsync` invocation) onto a single
+ * Sentrial session via the `begin()`/Interaction API. The attachment surface is a
+ * Runner-level **Plugin** — ADK's `BasePlugin` fires globally for the *entire*
+ * invocation across *every* agent, tool, and model call, so one run → one Sentrial
+ * session automatically (the ADK equivalent of the OpenAI Agents SDK's global
+ * trace processor in {@link SentrialOpenAIAgentsProcessor}).
+ *
+ * Mapping (mirrors the Python google_adk.py):
+ *
+ * - **run start** (`beforeRunCallback`) → `begin()` — agent/event name from the
+ *   root agent, `convoId` from the ADK session id, `userId` from the ADK session
+ *   (overridable), input from the run's `userContent`.
+ * - **model calls** (`beforeModelCallback` → `afterModelCallback`) → per-call LLM
+ *   event via `trackToolCall` (`llm:{model}` convention, model from
+ *   `LlmRequest.model`, prompt/completion tokens from `LlmResponse.usageMetadata`
+ *   — `promptTokenCount` / `candidatesTokenCount` — cost via the pricing tables,
+ *   duration from the before/after timestamps). Streaming *partial* responses are
+ *   skipped so tokens aren't double-counted; the final response carries the usage.
+ * - **tool calls** (`beforeToolCallback` → `afterToolCallback`) → `trackToolCall`
+ *   (tool name/args/result, duration from before/after).
+ * - **errors** (`onToolErrorCallback` / `onModelErrorCallback` and any
+ *   `LlmResponse.errorCode`) → `trackError` (the session finishes `success=false`).
+ * - **run end** (`afterRunCallback`) → `finish()` with rolled-up tokens/cost and
+ *   the last model output; custom metrics `llm_calls` / `tool_calls`.
+ *
+ * Distinction from {@link wrapGoogle}:
+ * `wrapGoogle` wraps a RAW `@google/genai` model so each `generateContent` call is
+ * tracked inside a session YOU manage with `begin()`. This module instead observes
+ * the ADK **runtime** (`Agent` + `Runner`) from the outside via its documented
+ * Plugin hooks — each ADK run becomes a full Sentrial session automatically. If you
+ * use ADK, prefer this module; don't combine both on the same run (LLM calls would
+ * be double-counted).
+ *
+ * The `@google/adk` package stays an OPTIONAL peer dependency: this module NEVER
+ * imports it. ADK's `PluginManager` dispatches to plugin callbacks BY NAME and
+ * dedups by `.name`, and a plain object structurally satisfies `BasePlugin`, so a
+ * duck-typed class needs no `BasePlugin` subclass — the module imports cleanly with
+ * or without ADK installed. You attach it via `plugins: [new SentrialAdkPlugin()]`
+ * at Runner construction, or after the fact with {@link instrumentAdk}.
+ *
+ * Verified against the official ADK-JS source (github.com/google/adk-js, package
+ * `@google/adk`):
+ * - `core/src/plugins/base_plugin.ts` — plugin callbacks take a SINGLE camelCase
+ *   params object (NOT Python's keyword args): `beforeRunCallback({invocationContext})`,
+ *   `afterRunCallback({invocationContext})`, `beforeModelCallback({callbackContext, llmRequest})`,
+ *   `afterModelCallback({callbackContext, llmResponse})`,
+ *   `onModelErrorCallback({callbackContext, llmRequest, error})`,
+ *   `beforeToolCallback({tool, toolArgs, toolContext})`,
+ *   `afterToolCallback({tool, toolArgs, toolContext, result})`,
+ *   `onToolErrorCallback({tool, toolArgs, toolContext, error})`. Returning a
+ *   non-`undefined` value SHORT-CIRCUITS the run, so every callback returns
+ *   `undefined` (pure observer).
+ * - `core/src/plugins/plugin_manager.ts` — `runCallbacks` CATCHES a throwing
+ *   callback and RE-THROWS a wrapped error that HALTS the agent run; containment
+ *   inside every callback body is therefore mandatory. `registerPlugin` throws on a
+ *   duplicate `.name`; `getPlugin(name)` retrieves by name.
+ * - `core/src/models/llm_response.ts` — `content?: Content` (`.parts[].text`),
+ *   `usageMetadata` (`promptTokenCount` / `candidatesTokenCount`), `partial`,
+ *   `errorCode` / `errorMessage`.
+ * - `core/src/models/llm_request.ts` — `model?: string`.
+ * - `core/src/agents/invocation_context.ts` — `invocationId`, `agent` (`.name`),
+ *   `session` (`.id` / `.appName` / `.userId`), `appName`/`userId` getters, `userContent`.
+ * - `core/src/agents/readonly_context.ts` — the callback `Context` exposes getters
+ *   `invocationId` / `agentName` / `sessionId` / `userId` / `userContent` and the
+ *   public `invocationContext`.
+ * - `core/src/runner/runner.ts` — `plugins?: BasePlugin[]` at construction;
+ *   `runner.pluginManager.registerPlugin(plugin)`.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryRunner } from '@google/adk';
+ * import { LlmAgent } from '@google/adk';
+ * import { sentrial, SentrialAdkPlugin } from '@sentrial/sdk';
+ *
+ * sentrial.configure({ apiKey: process.env.SENTRIAL_API_KEY });
+ *
+ * const agent = new LlmAgent({ name: 'assistant', model: 'gemini-2.0-flash' });
+ * const runner = new InMemoryRunner({ agent, plugins: [new SentrialAdkPlugin()] });
+ * // Every runner.runAsync(...) is now a Sentrial session with LLM events,
+ * // tool calls, and token/cost rollups.
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** The subset of ADK `Content` (`@google/genai`) this plugin reads. */
+type AdkContent = {
+    parts?: Array<{
+        text?: unknown;
+    } | unknown>;
+} | string | unknown;
+/** The subset of ADK `InvocationContext` this plugin reads (run lifecycle). */
+type AdkInvocationContext = {
+    invocationId?: string;
+    agent?: {
+        name?: string;
+    };
+    session?: {
+        id?: string;
+        appName?: string;
+        userId?: string;
+    };
+    appName?: string;
+    userId?: string;
+    userContent?: AdkContent;
+};
+/** The subset of the ADK callback `Context` this plugin reads (model/tool calls). */
+type AdkCallbackContext = {
+    invocationId?: string;
+    agentName?: string;
+    sessionId?: string;
+    userId?: string;
+    userContent?: AdkContent;
+    invocationContext?: AdkInvocationContext;
+};
+/** The subset of ADK `LlmRequest` this plugin reads. */
+type AdkLlmRequest = {
+    model?: string;
+};
+/** The subset of ADK `LlmResponse` this plugin reads. */
+type AdkLlmResponse = {
+    content?: AdkContent;
+    usageMetadata?: {
+        promptTokenCount?: unknown;
+        candidatesTokenCount?: unknown;
+    };
+    partial?: unknown;
+    errorCode?: unknown;
+    errorMessage?: unknown;
+};
+/** The subset of ADK `BaseTool` this plugin reads. */
+type AdkTool = {
+    name?: string;
+};
+/** The Runner surface {@link instrumentAdk} needs (`runner.pluginManager.registerPlugin`). */
+type AdkRunnerLike = {
+    pluginManager?: {
+        registerPlugin?: (plugin: unknown) => void;
+        getPlugin?: (name: string) => unknown;
+    };
+};
+interface AdkPluginOptions {
+    /** Explicit SentrialClient. Defaults to a client from the environment (SENTRIAL_API_KEY). */
+    client?: SentrialClient;
+    /** ADK plugin name (default 'sentrial'); ADK requires unique plugin names. */
+    name?: string;
+    /** Explicit agent/event name override (defaults to the root agent's name per run). */
+    defaultAgent?: string;
+    /** User ID override (defaults to the ADK session's userId, then 'anonymous'). */
+    userId?: string;
+    /** Extra metadata merged into every session. */
+    extraMetadata?: Record<string, unknown>;
+}
+/**
+ * Duck-typed Google ADK `BasePlugin` that mirrors ADK runs into Sentrial sessions.
+ *
+ * Register it on a `Runner`:
+ * ```ts
+ * const runner = new InMemoryRunner({ agent, plugins: [new SentrialAdkPlugin()] });
+ * ```
+ * or attach it to an existing runner with {@link instrumentAdk}.
+ *
+ * This is a *plain* class implementing the `BasePlugin` callback protocol — it is
+ * intentionally NOT a `BasePlugin` subclass, because ADK's `PluginManager`
+ * dispatches to callbacks by name and dedups by `.name`, so subclassing would force
+ * a hard `@google/adk` import (breaking the "optional peer" contract and
+ * import-without-ADK). Every callback body is containment-wrapped: ADK's
+ * PluginManager re-throws a callback error and HALTS the run, so a tracking failure
+ * must never escape — it is swallowed instead. Every callback returns `undefined`
+ * (a pure observer never short-circuits the model/tool call).
+ *
+ * Performance tip: construct the client with `batching: { enabled: true }` so
+ * `track*` calls enqueue instead of awaiting a network round-trip per event. ADK
+ * invokes these callbacks inline on the run's event loop.
+ */
+declare class SentrialAdkPlugin {
+    /** PluginManager reads `.name` for dedup/logging — a real string, always present. */
+    readonly name: string;
+    private clientRef?;
+    private readonly defaultAgent?;
+    private readonly userIdOption?;
+    private readonly extraMetadata;
+    private readonly runs;
+    /** One-time guard so the runs-cap eviction warns at most once (like the duplicate-instrument warn). */
+    private runsCapWarned;
+    constructor(options?: AdkPluginOptions);
+    beforeRunCallback(params: {
+        invocationContext: AdkInvocationContext;
+    }): Promise<undefined>;
+    afterRunCallback(params: {
+        invocationContext: AdkInvocationContext;
+    }): Promise<void>;
+    onRunErrorCallback(params: {
+        invocationContext: AdkInvocationContext;
+        error: unknown;
+    }): Promise<void>;
+    beforeModelCallback(params: {
+        callbackContext: AdkCallbackContext;
+        llmRequest: AdkLlmRequest;
+    }): Promise<undefined>;
+    afterModelCallback(params: {
+        callbackContext: AdkCallbackContext;
+        llmResponse: AdkLlmResponse;
+    }): Promise<undefined>;
+    onModelErrorCallback(params: {
+        callbackContext: AdkCallbackContext;
+        llmRequest: AdkLlmRequest;
+        error: unknown;
+    }): Promise<undefined>;
+    beforeToolCallback(params: {
+        tool: AdkTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: AdkCallbackContext;
+    }): Promise<undefined>;
+    afterToolCallback(params: {
+        tool: AdkTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: AdkCallbackContext;
+        result: unknown;
+    }): Promise<undefined>;
+    onToolErrorCallback(params: {
+        tool: AdkTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: AdkCallbackContext;
+        error: unknown;
+    }): Promise<undefined>;
+    private resolveClient;
+    /**
+     * Fetch (or lazily create) the per-run state for an invocation id, back-filling
+     * any run-identity fields not known when it was first created (a model/tool
+     * callback can reach a run before beforeRun in some ADK flows).
+     */
+    private getOrCreateState;
+    private stateFromInvocationContext;
+    private stateFromCallbackContext;
+    /**
+     * Begin the Sentrial session for this run exactly once. Event/agent name
+     * preference: explicit `defaultAgent` > root agent name > 'google-adk'. The ADK
+     * session id becomes `convoId`; the ADK session `userId` (or the configured
+     * override) becomes the Sentrial user.
+     *
+     * DELIBERATE (matches the openai-agents.ts TS twin): the interaction promise is
+     * cached, so a run whose `begin()` REJECTED never retries (avoids a partial
+     * session whose earlier events were lost). The Python google_adk leaves the
+     * interaction unset and retries at the next callback — both are documented,
+     * per-SDK choices, not drift.
+     */
+    private ensureInteraction;
+    private handleRunStart;
+    private handleRunEnd;
+    private handleRunError;
+    private handleModelStart;
+    private handleModelEnd;
+    private handleModelError;
+    private emitLlmEvent;
+    private handleToolStart;
+    private popToolTiming;
+    private handleToolEnd;
+    private handleToolError;
+    private finishState;
+}
+/**
+ * Register a {@link SentrialAdkPlugin} on an already-constructed ADK `Runner`.
+ *
+ * Convenience for when you didn't pass `plugins: [new SentrialAdkPlugin()]` at
+ * Runner construction. Pass the runner (its `pluginManager.registerPlugin` is the
+ * only surface used) — the `@google/adk` peer is never imported here, mirroring
+ * `instrumentOpenAIAgents(agents)`.
+ *
+ * Idempotent per runner: calling it again on the same runner returns the FIRST
+ * registered plugin instead of registering a duplicate (which ADK would reject on
+ * the duplicate name anyway, and which would mirror every run into two sessions).
+ * The first duplicate call emits a console warning (silent thereafter).
+ *
+ * @example
+ * ```ts
+ * import { InMemoryRunner } from '@google/adk';
+ * import { instrumentAdk } from '@sentrial/sdk';
+ *
+ * const runner = new InMemoryRunner({ agent });
+ * instrumentAdk(runner, { userId: 'user_123' });
+ * ```
+ *
+ * @param runner - An ADK `Runner` exposing `pluginManager.registerPlugin`.
+ * @param options - Plugin options (client, name, defaultAgent, userId, extraMetadata).
+ * @returns The registered plugin.
+ */
+declare function instrumentAdk(runner: AdkRunnerLike, options?: AdkPluginOptions): SentrialAdkPlugin;
+
 /**
  * Sentrial Decorators - Easy instrumentation for AI agents
  *
@@ -1889,4 +2362,4 @@ declare class Experiment {
     getResults(): Promise<ExperimentResults | null>;
 }
 
-export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };
+export { type AISDKVariantOptions, type ActionIdentity, type AdkCallbackContext, type AdkContent, type AdkInvocationContext, type AdkLlmRequest, type AdkLlmResponse, type AdkPluginOptions, type AdkRunnerLike, type AdkTool, type AgentDiagnostic, type AgentDiagnosticInput, type AgentsModuleLike, type AgentsSpan, type AgentsSpanError, type AgentsTrace, ApiError, BUILTIN_PATTERNS, BeginParams, CompleteSessionParams, type ContextToken, type ContextVar, CostParams, CreateSessionParams, DeliveryDiagnostics, type DispatchContext, type DurationSummary, Event, Experiment, type ExperimentContext, ExperimentExposureReceipt, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, FinishParams, type GenerateTextParams, type GenerateTextResult, GetVariantParams, type HandoffContext, type HandoffOutcome, Interaction, NetworkError, type NormalizableUsage, type NormalizedUsage, type OpenAIAgentsProcessorOptions, RecordExperimentExposureParams, SentrialAdkPlugin, SentrialClient, SentrialClientConfig, SentrialError, SentrialOpenAIAgentsProcessor, type ServerDurations, Session, SessionContext, type StreamTextResult, Tool, TrackDecisionParams, TrackErrorParams, TrackSession, TrackToolCallParams, type TransportAttempt, type TransportDiagnosticsSnapshot, ValidationError, VariantAssignment, type WrapClaudeAgentOptions, actionMetadata, begin, calculateAnthropicCost, calculateCostByProvider, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, createDispatchContext, createHandoffContext, foldProviderExtras, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariant, getVariantForAISDK, getVariantName, guessProvider, instrumentAdk, instrumentOpenAIAgents, isExperimentMode, normalizeUsage, recordExperimentExposure, resolveTokensAndCost, resumeHandoffContext, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };