aden-ts 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,2478 @@
+import OpenAI from 'openai';
+
+/**
+ * Control Types - Types for the Control Agent
+ *
+ * Defines control actions, events, and policies for bidirectional
+ * communication with the control server.
+ */
+
+/**
+ * Control actions that can be applied to requests
+ * - allow: Request proceeds normally
+ * - block: Request is rejected
+ * - throttle: Request is delayed before proceeding
+ * - degrade: Request uses a cheaper/fallback model
+ * - alert: Request proceeds but triggers an alert notification
+ */
+type ControlAction = "allow" | "block" | "throttle" | "degrade" | "alert";
+/**
+ * Control decision - what action to take for a request
+ */
+interface ControlDecision {
+    /** The action to take */
+    action: ControlAction;
+    /** Human-readable reason for the decision */
+    reason?: string;
+    /** If action is "degrade", switch to this model */
+    degradeToModel?: string;
+    /** If action is "throttle", delay by this many milliseconds */
+    throttleDelayMs?: number;
+    /** If action is "alert", the severity level */
+    alertLevel?: "info" | "warning" | "critical";
+}
+/**
+ * Base event structure with common fields
+ */
+interface BaseEvent {
+    /** Event type discriminator */
+    event_type: string;
+    /** ISO timestamp of the event */
+    timestamp: string;
+    /** SDK instance ID for tracking */
+    sdk_instance_id: string;
+}
+/**
+ * Control event - emitted when a control action is taken
+ */
+interface ControlEvent extends BaseEvent {
+    event_type: "control";
+    /** Trace ID for correlation */
+    trace_id: string;
+    /** Span ID of the affected request */
+    span_id: string;
+    /** Context ID (user, session, deal, etc.) */
+    context_id?: string;
+    /** Provider (openai, anthropic, gemini) */
+    provider: string;
+    /** Original model that was requested */
+    original_model: string;
+    /** Action that was taken */
+    action: ControlAction;
+    /** Reason for the action */
+    reason?: string;
+    /** If degraded, what model was used instead */
+    degraded_to?: string;
+    /** If throttled, how long was the delay in ms */
+    throttle_delay_ms?: number;
+    /** Estimated cost that triggered the decision */
+    estimated_cost?: number;
+}
+/**
+ * Heartbeat event - periodic health check
+ */
+interface HeartbeatEvent extends BaseEvent {
+    event_type: "heartbeat";
+    /** Connection status */
+    status: "healthy" | "degraded" | "reconnecting";
+    /** Requests processed since last heartbeat */
+    requests_since_last: number;
+    /** Errors since last heartbeat */
+    errors_since_last: number;
+    /** Current policy cache age in seconds */
+    policy_cache_age_seconds: number;
+    /** Whether WebSocket is connected */
+    websocket_connected: boolean;
+    /** SDK version */
+    sdk_version: string;
+}
+/**
+ * Budget type - what scope the budget applies to
+ */
+type BudgetType = "global" | "agent" | "tenant" | "customer" | "feature" | "tag";
+/**
+ * Limit action - what to do when budget is exceeded
+ */
+type LimitAction = "kill" | "throttle" | "degrade";
+/**
+ * Budget alert configuration
+ */
+interface BudgetAlert {
+    /** Threshold percentage (0-100) */
+    threshold: number;
+    /** Whether this alert is enabled */
+    enabled: boolean;
+}
+/**
+ * Budget notification settings
+ */
+interface BudgetNotifications {
+    /** Show in-app notifications */
+    inApp: boolean;
+    /** Send email notifications */
+    email: boolean;
+    /** Email recipients */
+    emailRecipients: string[];
+    /** Send webhook notifications */
+    webhook: boolean;
+}
+/**
+ * Budget rule - limits spend per context
+ */
+interface BudgetRule {
+    /** Unique identifier for this budget */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Budget type/scope */
+    type: BudgetType;
+    /** Tags for tag-based budgets (required when type is 'tag') */
+    tags?: string[];
+    /** Budget limit in USD */
+    limit: number;
+    /** Current spend in USD */
+    spent: number;
+    /** Action to take when budget is exceeded */
+    limitAction: LimitAction;
+    /** If limitAction is "degrade", switch to this model */
+    degradeToModel?: string;
+    /** Alert thresholds */
+    alerts: BudgetAlert[];
+    /** Notification settings */
+    notifications: BudgetNotifications;
+}
+/**
+ * Throttle rule - rate limiting
+ */
+interface ThrottleRule {
+    /** Context ID this rule applies to (omit for global) */
+    context_id?: string;
+    /** Provider this rule applies to (omit for all) */
+    provider?: string;
+    /** Maximum requests per minute */
+    requests_per_minute?: number;
+    /** Fixed delay to apply to each request (ms) */
+    delay_ms?: number;
+}
+/**
+ * Block rule - hard block on certain requests
+ */
+interface BlockRule {
+    /** Context ID to block (omit for pattern match) */
+    context_id?: string;
+    /** Provider to block (omit for all) */
+    provider?: string;
+    /** Model pattern to block (e.g., "gpt-4*") */
+    model_pattern?: string;
+    /** Reason shown to caller */
+    reason: string;
+}
+/**
+ * Degrade rule - automatic model downgrade
+ */
+interface DegradeRule {
+    /** Model to downgrade from */
+    from_model: string;
+    /** Model to downgrade to */
+    to_model: string;
+    /** When to trigger the downgrade */
+    trigger: "budget_threshold" | "rate_limit" | "always";
+    /** For budget_threshold: percentage at which to trigger (0-100) */
+    threshold_percent?: number;
+    /** Context ID this rule applies to (omit for all) */
+    context_id?: string;
+}
+/**
+ * Alert rule - trigger notifications without blocking
+ */
+interface AlertRule {
+    /** Context ID this rule applies to (omit for global) */
+    context_id?: string;
+    /** Provider this rule applies to (omit for all) */
+    provider?: string;
+    /** Model pattern to alert on (e.g., "gpt-4*" for expensive models) */
+    model_pattern?: string;
+    /** When to trigger the alert */
+    trigger: "budget_threshold" | "model_usage" | "always";
+    /** For budget_threshold: percentage at which to trigger (0-100) */
+    threshold_percent?: number;
+    /** Alert severity level */
+    level: "info" | "warning" | "critical";
+    /** Message to include in the alert */
+    message: string;
+}
+/**
+ * Complete control policy from server
+ */
+interface ControlPolicy {
+    /** Policy version for cache invalidation */
+    version: string;
+    /** When this policy was last updated */
+    updated_at: string;
+    /** Budget rules */
+    budgets?: BudgetRule[];
+    /** Throttle rules */
+    throttles?: ThrottleRule[];
+    /** Block rules */
+    blocks?: BlockRule[];
+    /** Degrade rules */
+    degradations?: DegradeRule[];
+    /** Alert rules */
+    alerts?: AlertRule[];
+}
+/**
+ * Request context for getting a control decision
+ */
+interface ControlRequest {
+    /** Context ID (user, session, deal, etc.) */
+    context_id?: string;
+    /** Provider being called */
+    provider: string;
+    /** Model being requested */
+    model: string;
+    /** Estimated cost of this request in USD */
+    estimated_cost?: number;
+    /** Estimated input tokens */
+    estimated_input_tokens?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Alert event passed to onAlert callback
+ */
+interface AlertEvent {
+    /** Alert severity level */
+    level: "info" | "warning" | "critical";
+    /** Alert message */
+    message: string;
+    /** Reason the alert was triggered */
+    reason: string;
+    /** Context ID that triggered the alert */
+    contextId?: string;
+    /** Provider that triggered the alert */
+    provider: string;
+    /** Model that triggered the alert */
+    model: string;
+    /** Timestamp of the alert */
+    timestamp: Date;
+}
+/**
+ * Options for creating a control agent
+ */
+interface ControlAgentOptions {
+    /** Server URL (wss:// for WebSocket, https:// for HTTP-only) */
+    serverUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Polling interval for HTTP fallback (ms), default: 30000 */
+    pollingIntervalMs?: number;
+    /** Heartbeat interval (ms), default: 10000 */
+    heartbeatIntervalMs?: number;
+    /** Request timeout (ms), default: 5000 */
+    timeoutMs?: number;
+    /** Fail open (allow) if server is unreachable, default: true */
+    failOpen?: boolean;
+    /** Custom context ID extractor */
+    getContextId?: () => string | undefined;
+    /** SDK instance identifier (auto-generated if not provided) */
+    instanceId?: string;
+    /**
+     * Callback invoked when an alert is triggered.
+     * Alerts do NOT block requests - they are notifications only.
+     * Use this for logging, notifications, or monitoring.
+     */
+    onAlert?: (alert: AlertEvent) => void | Promise<void>;
+    /**
+     * Enable hybrid enforcement (local + server-side validation).
+     * When enabled, budgets above the threshold are validated with the server.
+     * Default: false
+     */
+    enableHybridEnforcement?: boolean;
+    /**
+     * Budget usage threshold (percentage) at which to start server validation.
+     * Requests below this threshold use local-only enforcement.
+     * Default: 80
+     */
+    serverValidationThreshold?: number;
+    /**
+     * Timeout for server validation requests (ms).
+     * Default: 2000
+     */
+    serverValidationTimeoutMs?: number;
+    /**
+     * Enable adaptive threshold adjustment based on remaining budget.
+     * When enabled, force validation when remaining budget is critically low.
+     * Default: true
+     */
+    adaptiveThresholdEnabled?: boolean;
+    /**
+     * Minimum remaining budget (USD) that triggers forced server validation.
+     * Only applies when adaptiveThresholdEnabled is true.
+     * Default: 1.0
+     */
+    adaptiveMinRemainingUsd?: number;
+    /**
+     * Enable probabilistic sampling for server validation.
+     * Reduces latency impact by validating a fraction of requests.
+     * Default: true
+     */
+    samplingEnabled?: boolean;
+    /**
+     * Base sampling rate at the threshold (0-1).
+     * This is the minimum rate used at serverValidationThreshold.
+     * Default: 0.1 (10%)
+     */
+    samplingBaseRate?: number;
+    /**
+     * Budget usage percentage at which to validate all requests.
+     * Between threshold and this value, sampling rate interpolates to 1.0.
+     * Default: 95
+     */
+    samplingFullValidationPercent?: number;
+    /**
+     * Maximum expected overspend percentage beyond the soft limit.
+     * Acts as a hard limit safety net to prevent runaway spending.
+     * Default: 10 (allowing up to 110% of budget)
+     */
+    maxExpectedOverspendPercent?: number;
+}
+/**
+ * Budget validation request sent to server
+ */
+interface BudgetValidationRequest {
+    /** Budget ID to validate */
+    budgetId: string;
+    /** Estimated cost of the pending request */
+    estimatedCost: number;
+    /** Local spend tracking (server uses max of local vs server) */
+    localSpend?: number;
+    /** Budget context */
+    context?: {
+        type?: string;
+        value?: string;
+        tags?: string[];
+    };
+}
+/**
+ * Budget validation response from server
+ */
+interface BudgetValidationResponse {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Action to take */
+    action: "allow" | "block" | "degrade" | "throttle";
+    /** Authoritative spend from server (TSDB) */
+    authoritativeSpend: number;
+    /** Budget limit */
+    budgetLimit: number;
+    /** Current usage percentage */
+    usagePercent: number;
+    /** Policy version */
+    policyVersion: string;
+    /** Updated spend after this request */
+    updatedSpend: number;
+    /** Reason for the decision */
+    reason?: string;
+    /** Projected usage percentage */
+    projectedPercent?: number;
+    /** Model to degrade to (if action is "degrade") */
+    degradeToModel?: string;
+}
+/**
+ * Control Agent interface - the public API
+ */
+interface IControlAgent {
+    /**
+     * Connect to the control server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the control server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get a control decision for a request
+     */
+    getDecision(request: ControlRequest): Promise<ControlDecision>;
+    /**
+     * Report a metric event to the server
+     */
+    reportMetric(event: MetricEvent): Promise<void>;
+    /**
+     * Report a control event to the server
+     */
+    reportControlEvent(event: Omit<ControlEvent, "event_type" | "timestamp" | "sdk_instance_id">): Promise<void>;
+    /**
+     * Check if connected to server
+     */
+    isConnected(): boolean;
+    /**
+     * Get current cached policy
+     */
+    getPolicy(): ControlPolicy | null;
+}
+
+/**
+ * Normalized usage metrics that work across both API response shapes
+ * (Responses API vs Chat Completions API)
+ */
+interface NormalizedUsage {
+    /** Input/prompt tokens consumed */
+    input_tokens: number;
+    /** Output/completion tokens consumed */
+    output_tokens: number;
+    /** Total tokens (input + output) */
+    total_tokens: number;
+    /** Reasoning tokens used (for o1/o3 models) */
+    reasoning_tokens: number;
+    /** Tokens served from prompt cache (reduces cost) */
+    cached_tokens: number;
+    /** Prediction tokens that were accepted */
+    accepted_prediction_tokens: number;
+    /** Prediction tokens that were rejected */
+    rejected_prediction_tokens: number;
+}
+/**
+ * Request metadata that affects billing/cost
+ */
+interface RequestMetadata {
+    /** Unique trace ID for this request */
+    traceId: string;
+    /** Model used for the request */
+    model: string;
+    /** Service tier (affects pricing/performance) */
+    service_tier?: "auto" | "default" | "flex" | "priority" | string;
+    /** Maximum output tokens cap */
+    max_output_tokens?: number;
+    /** Maximum tool calls allowed */
+    max_tool_calls?: number;
+    /** Prompt cache key for improved cache hits */
+    prompt_cache_key?: string;
+    /** Prompt cache retention policy */
+    prompt_cache_retention?: "in_memory" | "24h" | string;
+    /** Whether streaming was enabled */
+    stream: boolean;
+}
+/**
+ * Information about where an LLM call originated in the code
+ */
+interface CallSite {
+    /** File path where the call originated */
+    file: string;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column: number;
+    /** Function name (if available) */
+    function?: string;
+}
+/**
+ * Complete metric event emitted after each API call.
+ * All fields are flat (not nested) for consistent cross-provider analytics.
+ * Uses OpenTelemetry-compatible naming: trace_id groups operations, span_id identifies each operation.
+ */
+interface MetricEvent {
+    /** Trace ID grouping related operations (OTel standard) */
+    trace_id: string;
+    /** Unique span ID for this specific operation (OTel standard) */
+    span_id: string;
+    /** Parent span ID for nested/hierarchical calls (OTel standard) */
+    parent_span_id?: string;
+    /** Provider-specific request ID (if available) */
+    request_id: string | null;
+    /** LLM provider: openai, gemini, anthropic */
+    provider: "openai" | "gemini" | "anthropic";
+    /** Model used for the request */
+    model: string;
+    /** Whether streaming was enabled */
+    stream: boolean;
+    /** ISO timestamp when the request started */
+    timestamp: string;
+    /** Request latency in milliseconds */
+    latency_ms: number;
+    /** HTTP status code (if available) */
+    status_code?: number;
+    /** Error message if request failed */
+    error?: string;
+    /** Input/prompt tokens consumed */
+    input_tokens: number;
+    /** Output/completion tokens consumed */
+    output_tokens: number;
+    /** Total tokens (input + output) */
+    total_tokens: number;
+    /** Tokens served from cache (reduces cost) */
+    cached_tokens: number;
+    /** Reasoning tokens used (for o1/o3 models) */
+    reasoning_tokens: number;
+    /** Remaining requests in current window */
+    rate_limit_remaining_requests?: number;
+    /** Remaining tokens in current window */
+    rate_limit_remaining_tokens?: number;
+    /** Time until request limit resets (seconds) */
+    rate_limit_reset_requests?: number;
+    /** Time until token limit resets (seconds) */
+    rate_limit_reset_tokens?: number;
+    /** Sequence number within the trace */
+    call_sequence?: number;
+    /** Stack of agent/handler names leading to this call */
+    agent_stack?: string[];
+    /** File path where the call originated (immediate caller) */
+    call_site_file?: string;
+    /** Line number where the call originated */
+    call_site_line?: number;
+    /** Column number where the call originated */
+    call_site_column?: number;
+    /** Function name where the call originated */
+    call_site_function?: string;
+    /** Full call stack for detailed tracing (file:line:function) */
+    call_stack?: string[];
+    /** Number of tool calls made */
+    tool_call_count?: number;
+    /** Tool names that were called (comma-separated) */
+    tool_names?: string;
+    /** Service tier (OpenAI: auto, default, flex, priority) */
+    service_tier?: string;
+    /** Custom metadata attached to the request */
+    metadata?: Record<string, string>;
+}
+/**
+ * Rate limit information from response headers
+ */
+interface RateLimitInfo {
+    /** Remaining requests in current window */
+    remaining_requests?: number;
+    /** Remaining tokens in current window */
+    remaining_tokens?: number;
+    /** Time until request limit resets (seconds) */
+    reset_requests?: number;
+    /** Time until token limit resets (seconds) */
+    reset_tokens?: number;
+}
+/**
+ * Metric for individual tool calls
+ */
+interface ToolCallMetric {
+    /** Tool type (function, web_search, code_interpreter, etc.) */
+    type: string;
+    /** Tool/function name */
+    name?: string;
+    /** Duration of tool execution in ms (if available) */
+    duration_ms?: number;
+}
+/**
+ * Callback function for emitting metrics
+ */
+type MetricEmitter = (event: MetricEvent) => void | Promise<void>;
+/**
+ * Context passed to the beforeRequest hook
+ */
+interface BeforeRequestContext {
+    /** The model being used for this request */
+    model: string;
+    /** Whether this is a streaming request */
+    stream: boolean;
+    /** Generated span ID for this request (OTel standard) */
+    spanId: string;
+    /** Trace ID grouping related operations (OTel standard) */
+    traceId: string;
+    /** Timestamp when the request was initiated */
+    timestamp: Date;
+    /** Custom metadata that can be passed through */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from the beforeRequest hook
+ */
+type BeforeRequestResult = {
+    action: "proceed";
+} | {
+    action: "throttle";
+    delayMs: number;
+} | {
+    action: "cancel";
+    reason: string;
+} | {
+    action: "degrade";
+    toModel: string;
+    reason?: string;
+    delayMs?: number;
+} | {
+    action: "alert";
+    level: "info" | "warning" | "critical";
+    message: string;
+    delayMs?: number;
+};
+/**
+ * Hook called before each API request, allowing user-defined rate limiting
+ *
+ * @example
+ * ```ts
+ * beforeRequest: async (params, context) => {
+ *   const remaining = await checkQuota(context.metadata?.tenantId);
+ *   if (remaining <= 0) {
+ *     return { action: 'cancel', reason: 'Quota exceeded' };
+ *   }
+ *   if (remaining < 10) {
+ *     return { action: 'throttle', delayMs: 1000 };
+ *   }
+ *   return { action: 'proceed' };
+ * }
+ * ```
+ */
+type BeforeRequestHook = (params: Record<string, unknown>, context: BeforeRequestContext) => BeforeRequestResult | Promise<BeforeRequestResult>;
+/**
+ * Error thrown when a request is cancelled by the beforeRequest hook
+ */
+declare class RequestCancelledError extends Error {
+    readonly reason: string;
+    readonly context: BeforeRequestContext;
+    constructor(reason: string, context: BeforeRequestContext);
+}
+/**
+ * Options for the metered OpenAI client
+ */
+/**
+ * SDK classes that can be passed for instrumentation.
+ * Use this when you have multiple copies of SDK packages in your node_modules
+ * (e.g., when using file: dependencies or monorepos).
+ */
+interface SDKClasses {
+    /** GoogleGenerativeAI class from @google/generative-ai */
+    GoogleGenerativeAI?: any;
+    /** OpenAI class from openai */
+    OpenAI?: any;
+    /** Anthropic class from @anthropic-ai/sdk */
+    Anthropic?: any;
+}
+/**
+ * Default control server URL
+ */
+declare const DEFAULT_CONTROL_SERVER = "https://kube.acho.io";
+/**
+ * Get the control server URL with priority:
+ * 1. Explicit serverUrl option
+ * 2. ADEN_API_URL environment variable
+ * 3. DEFAULT_CONTROL_SERVER constant
+ */
+declare function getControlServerUrl(serverUrl?: string): string;
+interface MeterOptions {
+    /**
+     * API key for the control server.
+     * When provided, automatically creates a control agent and emitter.
+     * This is the simplest way to enable metering with remote control.
+     *
+     * If not provided, checks ADEN_API_KEY environment variable.
+     *
+     * @example
+     * ```typescript
+     * // Simplest setup - just provide API key
+     * await instrument({
+     *   apiKey: process.env.ADEN_API_KEY,
+     *   sdks: { OpenAI },
+     * });
+     * ```
+     */
+    apiKey?: string;
+    /**
+     * Control server URL.
+     * Priority: serverUrl option > ADEN_API_URL env var > https://kube.acho.io
+     * Only used when apiKey is provided.
+     */
+    serverUrl?: string;
+    /**
+     * Whether to allow requests when control server is unreachable.
+     * Default: true (fail open - requests proceed if server is down)
+     * Set to false for strict control (fail closed - block if server unreachable)
+     */
+    failOpen?: boolean;
+    /**
+     * Custom metric emitter function.
+     * When apiKey is provided, this is optional - metrics go to control server.
+     * When apiKey is NOT provided, this is required.
+     *
+     * You can combine with apiKey to emit to multiple destinations:
+     * @example
+     * ```typescript
+     * await instrument({
+     *   apiKey: process.env.ADEN_API_KEY,
+     *   emitMetric: createConsoleEmitter({ pretty: true }), // Also log locally
+     * });
+     * ```
+     */
+    emitMetric?: MetricEmitter;
+    /** Whether to include tool call metrics (default: true) */
+    trackToolCalls?: boolean;
+    /** Custom span ID generator (default: crypto.randomUUID) */
+    generateSpanId?: () => string;
+    /**
+     * Hook called before each request for user-defined rate limiting.
+     * Can cancel requests, throttle them with a delay, or allow them to proceed.
+     */
+    beforeRequest?: BeforeRequestHook;
+    /** Custom metadata to pass to beforeRequest hook */
+    requestMetadata?: Record<string, unknown>;
+    /**
+     * Whether to automatically track call relationships using AsyncLocalStorage.
+     * When enabled, related LLM calls are grouped by session, with parent/child
+     * relationships, agent stacks, and call sites automatically detected.
+     * Default: true
+     */
+    trackCallRelationships?: boolean;
+    /**
+     * SDK classes to instrument. Pass these when you have multiple copies of
+     * SDK packages in your node_modules (common in monorepos or with file: dependencies).
+     * If not provided, Aden will try to import the SDKs from its own node_modules,
+     * which may not be the same instance your application uses.
+     *
+     * @example
+     * ```typescript
+     * import { GoogleGenerativeAI } from "@google/generative-ai";
+     *
+     * instrument({
+     *   apiKey: process.env.ADEN_API_KEY,
+     *   sdks: { GoogleGenerativeAI },
+     * });
+     * ```
+     */
+    sdks?: SDKClasses;
+    /**
+     * Function to get the current context ID (user ID, session ID, etc.)
+     * Used for budget tracking and policy enforcement per context.
+     *
+     * @example
+     * ```typescript
+     * instrument({
+     *   apiKey: process.env.ADEN_API_KEY,
+     *   getContextId: () => getCurrentUserId(),
+     * });
+     * ```
+     */
+    getContextId?: () => string | undefined;
+    /**
+     * Pre-configured control agent instance.
+     * Use this for advanced control agent configuration.
+     * When apiKey is provided, a control agent is created automatically.
+     */
+    controlAgent?: IControlAgent;
+    /**
+     * Callback invoked when an alert is triggered by the control agent.
+     * Alerts do NOT block requests - they are notifications only.
+     * Use this for logging, notifications, or monitoring.
+     *
+     * @example
+     * ```typescript
+     * instrument({
+     *   apiKey: process.env.ADEN_API_KEY,
+     *   onAlert: (alert) => {
+     *     console.warn(`[${alert.level}] ${alert.message}`);
+     *     // Send to Slack, PagerDuty, etc.
+     *   },
+     * });
+     * ```
+     */
+    onAlert?: (alert: {
+        level: "info" | "warning" | "critical";
+        message: string;
+        reason: string;
+        contextId?: string;
+        provider: string;
+        model: string;
+        timestamp: Date;
+    }) => void | Promise<void>;
+}
+/**
+ * Budget configuration for guardrails
+ */
+interface BudgetConfig {
+    /** Maximum input tokens allowed per request */
+    maxInputTokens?: number;
+    /** Maximum total tokens allowed per request */
+    maxTotalTokens?: number;
+    /** Action to take when budget is exceeded */
+    onExceeded?: "throw" | "truncate" | "warn";
+    /** Custom handler when budget is exceeded */
+    onExceededHandler?: (info: BudgetExceededInfo) => void | Promise<void>;
+}
+/**
+ * Information about a budget violation
+ */
+interface BudgetExceededInfo {
+    /** Estimated input tokens */
+    estimatedInputTokens: number;
+    /** Configured maximum */
+    maxInputTokens: number;
+    /** Model being used */
+    model: string;
+    /** Original input that exceeded budget */
+    input: unknown;
+}
+/**
+ * Streaming event types we care about for metrics
+ */
+type StreamingEventType = "response.created" | "response.in_progress" | "response.completed" | "response.failed" | "response.incomplete" | "response.output_item.added" | "response.content_part.added" | "response.content_part.done" | "response.output_item.done" | "response.function_call_arguments.delta" | "response.function_call_arguments.done";
+/**
+ * Extended OpenAI client with metering capabilities
+ */
+type MeteredOpenAI = OpenAI & {
+    __metered: true;
+    __meterOptions: MeterOptions;
+};
+
+/**
+ * Wraps an OpenAI client with metering capabilities.
+ *
+ * This function injects metering into the client without modifying the SDK,
+ * allowing you to track usage metrics, billing data, and request metadata
+ * for every API call.
+ *
+ * @param client - The OpenAI client instance to wrap
+ * @param options - Metering options including the metric emitter
+ * @returns The same client with metering injected
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import { makeMeteredOpenAI } from "openai-meter";
+ *
+ * const client = new OpenAI();
+ * const metered = makeMeteredOpenAI(client, {
+ *   emitMetric: (event) => {
+ *     console.log("Usage:", event.usage);
+ *     // Send to your metrics backend
+ *   },
+ * });
+ *
+ * // Use normally - metrics are collected automatically
+ * const response = await metered.responses.create({
+ *   model: "gpt-4.1",
+ *   input: "Hello!",
+ * });
+ * ```
+ */
+declare function makeMeteredOpenAI(client: OpenAI, options: MeterOptions): MeteredOpenAI;
+/**
+ * Check if a client has already been wrapped with metering
+ */
+declare function isMetered(client: OpenAI): client is MeteredOpenAI;
+
+/**
+ * OpenAI SDK instrumentation.
+ *
+ * Call `instrumentOpenAI()` to instrument the OpenAI SDK.
+ * This is called automatically by the main `instrument()` function.
+ */
+
+/**
+ * Instrument OpenAI SDK globally.
+ *
+ * Call once at application startup. All OpenAI client instances
+ * will automatically be metered.
+ *
+ * @returns true if instrumentation was successful, false if SDK not found
+ */
+declare function instrumentOpenAI(options: MeterOptions): Promise<boolean>;
+/**
+ * Remove OpenAI instrumentation.
+ *
+ * Restores original behavior for all clients.
+ */
+declare function uninstrumentOpenAI(): Promise<void>;
+/**
+ * Check if OpenAI is currently instrumented
+ */
+declare function isOpenAIInstrumented(): boolean;
+
+/**
+ * Global instrumentation for Google Generative AI (Gemini) clients.
+ *
+ * Call `instrumentGemini()` once at startup, and all Gemini client instances
+ * (existing and future) are automatically metered.
+ */
+
+/**
+ * Instrument Google Generative AI (Gemini) globally.
+ *
+ * Call once at application startup. All Gemini GenerativeModel instances
+ * will automatically be metered.
+ *
+ * @returns true if instrumentation was successful, false if SDK not found
+ */
+declare function instrumentGemini(options: MeterOptions): Promise<boolean>;
+/**
+ * Remove Gemini instrumentation.
+ *
+ * Restores original behavior for all clients.
+ */
+declare function uninstrumentGemini(): Promise<void>;
+/**
+ * Check if Gemini is currently instrumented
+ */
+declare function isGeminiInstrumented(): boolean;
+
+/**
+ * Global instrumentation for Anthropic (Claude) SDK clients.
+ *
+ * Call `instrumentAnthropic()` once at startup, and all Anthropic client instances
+ * (existing and future) are automatically metered.
+ */
+
+/**
+ * Instrument Anthropic (Claude) SDK globally.
+ *
+ * Call once at application startup. All Anthropic client instances
+ * will automatically be metered.
+ *
+ * @returns true if instrumentation was successful, false if SDK not found
+ */
+declare function instrumentAnthropic(options: MeterOptions): Promise<boolean>;
+/**
+ * Remove Anthropic instrumentation.
+ *
+ * Restores original behavior for all clients.
+ */
+declare function uninstrumentAnthropic(): Promise<void>;
+/**
+ * Check if Anthropic is currently instrumented
+ */
+declare function isAnthropicInstrumented(): boolean;
+
+/**
+ * Fetch-based instrumentation for frameworks that bypass SDK classes
+ *
+ * Works with: Vercel AI SDK, LangChain, Mastra, and any framework
+ * that makes direct HTTP calls to LLM APIs.
+ */
+
+/**
+ * Instrument global fetch to capture LLM API calls
+ */
+declare function instrumentFetch(options: MeterOptions): Promise<boolean>;
+/**
+ * Remove fetch instrumentation
+ */
+declare function uninstrumentFetch(): Promise<void>;
+/**
+ * Check if fetch is instrumented
+ */
+declare function isFetchInstrumented(): boolean;
+
+/**
+ * Unified instrumentation for LLM SDKs.
+ *
+ * Call `instrument()` once at startup, and all available LLM client instances
+ * (OpenAI, Gemini, Anthropic) are automatically detected and metered.
+ */
+
+/**
+ * Result of instrumentation showing which SDKs were instrumented
+ */
+interface InstrumentationResult {
+    openai: boolean;
+    gemini: boolean;
+    anthropic: boolean;
+    controlAgent: IControlAgent | null;
+}
+/**
+ * Instrument all available LLM SDKs globally.
+ *
+ * Call once at application startup. All detected LLM client instances
+ * (OpenAI, Gemini, Anthropic) will automatically be metered.
+ *
+ * The function auto-detects which SDKs are installed and instruments them.
+ * SDKs that aren't installed are silently skipped.
+ *
+ * @example
+ * ```typescript
+ * import { instrument } from "aden";
+ * import OpenAI from "openai";
+ *
+ * // Simplest setup - just provide API key
+ * await instrument({
+ *   apiKey: process.env.ADEN_API_KEY,
+ *   sdks: { OpenAI },
+ * });
+ *
+ * // Or use ADEN_API_KEY environment variable
+ * await instrument({ sdks: { OpenAI } });
+ *
+ * // Use any LLM SDK normally - metrics collected automatically
+ * const openai = new OpenAI();
+ * ```
+ */
+declare function instrument(options: MeterOptions): Promise<InstrumentationResult>;
+/**
+ * Remove instrumentation from all LLM SDKs.
+ *
+ * Restores original behavior for all clients.
+ */
+declare function uninstrument(): Promise<void>;
+/**
+ * Check which SDKs are currently instrumented
+ */
+declare function getInstrumentedSDKs(): InstrumentationResult;
+/**
+ * Check if any SDK is currently instrumented
+ */
+declare function isInstrumented(): boolean;
+/**
+ * Get the current instrumentation options
+ */
+declare function getInstrumentationOptions(): MeterOptions | null;
+/**
+ * Update instrumentation options without re-instrumenting.
+ *
+ * Useful for changing emitters or settings at runtime.
+ */
+declare function updateInstrumentationOptions(updates: Partial<MeterOptions>): void;
+
+/**
+ * Google GenAI SDK instrumentation (new SDK).
+ *
+ * This module provides global instrumentation for the new Google GenAI SDK
+ * (@google/genai package) used by Google ADK and other modern Google AI tools.
+ *
+ * The new SDK uses:
+ *     import { GoogleGenAI } from "@google/genai";
+ *     const client = new GoogleGenAI({ apiKey: "..." });
+ *     await client.models.generateContent({ model: "...", contents: "..." });
+ */
+
+/**
+ * Instrument the Google GenAI SDK (google-genai package).
+ *
+ * This is the new SDK used by Google ADK and replaces google-generativeai.
+ *
+ * @param options - Metering options including the metric emitter
+ * @returns true if instrumentation succeeded, false if SDK not available
+ */
+declare function instrumentGenai(options: MeterOptions): Promise<boolean>;
+/**
+ * Remove Google GenAI SDK instrumentation.
+ */
+declare function uninstrumentGenai(): Promise<void>;
+/**
+ * Check if Google GenAI SDK is currently instrumented.
+ */
+declare function isGenaiInstrumented(): boolean;
+/**
+ * Get current GenAI instrumentation options.
+ */
+declare function getGenaiOptions(): MeterOptions | null;
+
+/**
+ * Context for tracking related LLM calls within a trace (OTel-compatible)
+ */
+interface MeterContext {
+    /** Trace ID grouping related operations (OTel standard) */
+    traceId: string;
+    /** Current call sequence number within trace */
+    callSequence: number;
+    /** Stack of agent/function names for nested calls */
+    agentStack: string[];
+    /** Parent span ID for hierarchical tracking (OTel standard) */
+    parentSpanId?: string;
+    /** Custom metadata attached to this context */
+    metadata?: Record<string, unknown>;
+    /** Stack fingerprint for heuristic grouping */
+    stackFingerprint?: string;
+}
+/**
+ * Extended metric event with call relationship tracking (OTel-compatible)
+ */
+interface CallRelationship {
+    /** Trace ID grouping related operations (OTel standard) */
+    traceId: string;
+    /** Parent span ID if this is a nested call (OTel standard) */
+    parentSpanId?: string;
+    /** Sequence number within the trace */
+    callSequence: number;
+    /** Stack of agent names leading to this call */
+    agentStack: string[];
+    /** Where in the code this call originated (immediate caller) */
+    callSite?: CallSite;
+    /** Full call stack for detailed tracing */
+    callStack?: string[];
+}
+/**
+ * Extract the first user-code call site from the current stack
+ */
+declare function extractCallSite(): CallSite | undefined;
+/**
+ * Extract agent names from the current call stack
+ */
+declare function extractAgentStack(): string[];
+/**
+ * Generate a fingerprint from the call stack for grouping related calls
+ */
+declare function generateStackFingerprint(): string;
+/**
+ * Create a new meter context
+ */
+declare function createMeterContext(options?: {
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}): MeterContext;
+/**
+ * Get the current meter context, creating one automatically if needed
+ *
+ * This enables zero-wrapper usage - the first LLM call will auto-create
+ * a session context that subsequent calls will inherit.
+ */
+declare function getCurrentContext(): MeterContext;
+/**
+ * Check if we're currently inside a meter context
+ */
+declare function hasContext(): boolean;
+/**
+ * Run a function within a new meter context (trace)
+ *
+ * @example
+ * ```ts
+ * await withMeterContext(async () => {
+ *   // All LLM calls here share the same trace
+ *   await client.responses.create({ ... });
+ *   await client.responses.create({ ... });
+ * }, { metadata: { userId: "123" } });
+ * ```
+ */
+declare function withMeterContext<T>(fn: () => T, options?: {
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}): T;
+/**
+ * Run an async function within a new meter context (trace)
+ */
+declare function withMeterContextAsync<T>(fn: () => Promise<T>, options?: {
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<T>;
+/**
+ * Enter a meter context that persists across awaits without explicit wrapping
+ *
+ * This is the zero-wrapper approach - call once at the start of your
+ * request/session handler, and all subsequent LLM calls will be tracked.
+ *
+ * @example
+ * ```ts
+ * app.post('/chat', async (req, res) => {
+ *   enterMeterContext({ metadata: { userId: req.userId } });
+ *
+ *   // All LLM calls in this request are now tracked together
+ *   const response = await client.responses.create({ ... });
+ *   res.json(response);
+ * });
+ * ```
+ */
+declare function enterMeterContext(options?: {
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}): MeterContext;
+/**
+ * Push an agent name onto the current context's agent stack
+ *
+ * Use this when entering a named agent/handler to track nesting.
+ */
+declare function pushAgent(name: string): void;
+/**
+ * Pop an agent name from the current context's agent stack
+ */
+declare function popAgent(): string | undefined;
+/**
+ * Run a function within a named agent context
+ *
+ * @example
+ * ```ts
+ * await withAgent("ResearchAgent", async () => {
+ *   // LLM calls here will have "ResearchAgent" in their agentStack
+ *   await client.responses.create({ ... });
+ * });
+ * ```
+ */
+declare function withAgent<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Reset the global session (useful for testing)
+ */
+declare function resetGlobalSession(): void;
+/**
+ * Set custom metadata on the current context
+ */
+declare function setContextMetadata(key: string, value: unknown): void;
+/**
+ * Get custom metadata from the current context
+ */
+declare function getContextMetadata(key: string): unknown;
+/**
+ * Merge stack-detected agents with explicit agent stack
+ */
+declare function getFullAgentStack(): string[];
+
+/**
+ * Normalizes usage data from OpenAI API responses.
+ *
+ * Handles both API shapes:
+ * - Responses API: uses `input_tokens` / `output_tokens`
+ * - Chat Completions API: uses `prompt_tokens` / `completion_tokens`
+ *
+ * @param usage - Raw usage object from OpenAI API response
+ * @returns Normalized usage metrics, or null if no usage data provided
+ */
+declare function normalizeOpenAIUsage(usage: unknown): NormalizedUsage | null;
+/**
+ * Normalizes usage data from Anthropic API responses.
+ *
+ * Anthropic Messages API usage fields:
+ * - input_tokens: Input tokens consumed
+ * - output_tokens: Output tokens generated
+ * - cache_read_input_tokens: Tokens served from cache (optional)
+ * - cache_creation_input_tokens: Tokens used to create cache (optional)
+ *
+ * @param usage - Raw usage object from Anthropic API response
+ * @returns Normalized usage metrics, or null if no usage data provided
+ */
+declare function normalizeAnthropicUsage(usage: unknown): NormalizedUsage | null;
+/**
+ * Normalizes usage data from Google Gemini API responses.
+ *
+ * Gemini GenerateContent usage_metadata fields:
+ * - promptTokenCount: Input tokens
+ * - candidatesTokenCount: Output tokens
+ * - totalTokenCount: Total tokens
+ * - cachedContentTokenCount: Cached tokens (optional)
+ *
+ * @param usageMetadata - Raw usage_metadata from Gemini API response
+ * @returns Normalized usage metrics, or null if no usage data provided
+ */
+declare function normalizeGeminiUsage(usageMetadata: unknown): NormalizedUsage | null;
+/**
+ * Normalizes usage data from any supported LLM provider.
+ *
+ * @param usage - Raw usage object from API response
+ * @param provider - The provider the usage came from (default: "openai")
+ * @returns Normalized usage metrics, or null if no usage data provided
+ *
+ * @example
+ * ```typescript
+ * // OpenAI
+ * const response = await openai.chat.completions.create({ ... });
+ * const normalized = normalizeUsage(response.usage, "openai");
+ *
+ * // Anthropic
+ * const response = await anthropic.messages.create({ ... });
+ * const normalized = normalizeUsage(response.usage, "anthropic");
+ *
+ * // Gemini
+ * const response = await model.generateContent({ ... });
+ * const normalized = normalizeUsage(response.usageMetadata, "gemini");
+ * ```
+ */
+declare function normalizeUsage(usage: unknown, provider?: "openai" | "anthropic" | "gemini"): NormalizedUsage | null;
+/**
+ * Creates an empty/zero usage object
+ */
+declare function emptyUsage(): NormalizedUsage;
+/**
+ * Merges two usage objects (useful for accumulating streaming deltas)
+ */
+declare function mergeUsage(a: NormalizedUsage, b: NormalizedUsage): NormalizedUsage;
+
+/**
+ * Error thrown when a request exceeds the configured budget
+ */
+declare class BudgetExceededError extends Error {
+    readonly estimatedInputTokens: number;
+    readonly maxInputTokens: number;
+    readonly model: string;
+    constructor(info: BudgetExceededInfo);
+}
+/**
+ * Counts input tokens using OpenAI's input token counting endpoint.
+ *
+ * Uses POST /v1/responses/input_tokens to get exact token counts
+ * before making the actual API call.
+ *
+ * @param client - OpenAI client instance
+ * @param model - Model to count tokens for
+ * @param input - The input to count tokens for
+ * @returns The estimated input token count
+ *
+ * @example
+ * ```ts
+ * const tokens = await countInputTokens(client, "gpt-4.1-mini", "Hello world");
+ * console.log(`This prompt will use ${tokens} input tokens`);
+ * ```
+ */
+declare function countInputTokens(client: OpenAI, model: string, input: unknown): Promise<number>;
+/**
+ * Creates a budget-enforced wrapper around the OpenAI client.
+ *
+ * This wrapper checks input token counts before making API calls and
+ * can throw, warn, or truncate based on your configuration.
+ *
+ * @param client - OpenAI client instance (can be metered or not)
+ * @param config - Budget configuration
+ * @returns The client with budget enforcement
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import { withBudgetGuardrails } from "openai-meter";
+ *
+ * const client = new OpenAI();
+ * const budgeted = withBudgetGuardrails(client, {
+ *   maxInputTokens: 4000,
+ *   onExceeded: "throw",
+ * });
+ *
+ * // This will throw if input exceeds 4000 tokens
+ * await budgeted.responses.create({
+ *   model: "gpt-4.1",
+ *   input: veryLongPrompt,
+ * });
+ * ```
+ */
+declare function withBudgetGuardrails<T extends OpenAI>(client: T, config: BudgetConfig): T;
+/**
+ * Convenience function to create a fully metered and budgeted client
+ */
+declare function createBudgetedMeteredClient(client: MeteredOpenAI, budgetConfig: BudgetConfig): MeteredOpenAI;
+
+/**
+ * A simple console emitter for development/debugging
+ */
+declare function createConsoleEmitter(options?: {
+    /** Log level: "info" logs all events, "warn" logs only errors */
+    level?: "info" | "warn";
+    /** Whether to pretty-print the output */
+    pretty?: boolean;
+}): MetricEmitter;
+/**
+ * Creates an emitter that batches metrics and flushes periodically
+ */
+declare function createBatchEmitter(flush: (events: MetricEvent[]) => void | Promise<void>, options?: {
+    /** Maximum batch size before auto-flush */
+    maxBatchSize?: number;
+    /** Maximum time (ms) to wait before flushing */
+    flushInterval?: number;
+}): MetricEmitter & {
+    flush: () => Promise<void>;
+    stop: () => void;
+};
+/**
+ * Creates an emitter that writes to multiple destinations
+ */
+declare function createMultiEmitter(emitters: MetricEmitter[]): MetricEmitter;
+/**
+ * Creates an emitter that filters events before passing to another emitter
+ */
+declare function createFilteredEmitter(emitter: MetricEmitter, filter: (event: MetricEvent) => boolean): MetricEmitter;
+/**
+ * Creates an emitter that transforms events before passing to another emitter
+ */
+declare function createTransformEmitter<T>(emitter: (transformed: T) => void | Promise<void>, transform: (event: MetricEvent) => T): MetricEmitter;
+/**
+ * Creates a no-op emitter (useful for testing or disabling metrics)
+ */
+declare function createNoopEmitter(): MetricEmitter;
+/**
+ * Helper to collect metrics in memory (useful for testing)
+ */
+declare function createMemoryEmitter(): MetricEmitter & {
+    events: MetricEvent[];
+    clear: () => void;
+};
+/**
+ * Options for the JSON file emitter
+ */
+interface JsonFileEmitterOptions {
+    /** File path to write metrics to */
+    filePath: string;
+    /** Format: "jsonl" for JSON Lines (one event per line), "json" for array */
+    format?: "jsonl" | "json";
+    /** Whether to use async writes (default: true for better performance) */
+    async?: boolean;
+    /** Whether to pretty-print JSON (default: false) */
+    pretty?: boolean;
+}
+/**
+ * Creates an emitter that writes metrics to a local JSON/JSONL file.
+ *
+ * JSONL format (default) is recommended - one JSON object per line:
+ * - Efficient for appending
+ * - Easy to stream/parse line by line
+ * - Works well with tools like jq
+ *
+ * @example
+ * ```typescript
+ * // JSONL format (recommended)
+ * const emitter = createJsonFileEmitter({
+ *   filePath: "./metrics.jsonl",
+ * });
+ *
+ * // JSON array format
+ * const emitter = createJsonFileEmitter({
+ *   filePath: "./metrics.json",
+ *   format: "json",
+ *   pretty: true,
+ * });
+ *
+ * instrument({ emitMetric: emitter });
+ * ```
+ */
+declare function createJsonFileEmitter(options: JsonFileEmitterOptions): MetricEmitter & {
+    flush: () => Promise<void>;
+};
+
+/**
+ * File-based metric logging for local storage and analysis.
+ *
+ * Writes raw metric data to JSONL files organized by date and session,
+ * enabling offline analysis, debugging, and compliance auditing.
+ */
+
+/**
+ * Options for the MetricFileLogger
+ */
+interface MetricFileLoggerOptions {
+    /** Base directory for log files. Default: ./meter_logs or METER_LOG_DIR env var */
+    logDir?: string;
+    /** Whether to use async writes (default: true for better performance) */
+    async?: boolean;
+}
+/**
+ * Writes raw metric data to local JSONL files for analysis.
+ *
+ * Files are organized by date and session:
+ *     meter_logs/
+ *         2024-01-15/
+ *             session_abc123.jsonl
+ *             session_def456.jsonl
+ *         2024-01-16/
+ *             ...
+ *
+ * Each line in the JSONL file is a complete JSON object representing
+ * one metric event (LLM request, TTS synthesis, STT transcription).
+ *
+ * @example
+ * ```typescript
+ * import { MetricFileLogger } from "aden";
+ *
+ * const logger = new MetricFileLogger({ logDir: "./my_logs" });
+ * logger.writeLLMEvent({
+ *   sessionId: "session_123",
+ *   inputTokens: 100,
+ *   outputTokens: 50,
+ *   model: "gpt-4o-mini",
+ * });
+ * ```
+ */
+declare class MetricFileLogger {
+    private logDir;
+    private useAsync;
+    constructor(options?: MetricFileLoggerOptions);
+    /**
+     * Create the log directory if it doesn't exist.
+     */
+    private ensureDirExists;
+    /**
+     * Get the log file path for a session.
+     */
+    private getSessionFile;
+    /**
+     * Write a metric event to the session's log file.
+     */
+    writeEvent(sessionId: string, eventType: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Write a MetricEvent to the log file.
+     */
+    writeMetricEvent(event: MetricEvent): Promise<void>;
+    /**
+     * Write an LLM metric event.
+     */
+    writeLLMEvent(options: {
+        sessionId: string;
+        inputTokens: number;
+        outputTokens: number;
+        model: string;
+        latencyMs?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Write a TTS metric event.
+     */
+    writeTTSEvent(options: {
+        sessionId: string;
+        characters: number;
+        model: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Write an STT metric event.
+     */
+    writeSTTEvent(options: {
+        sessionId: string;
+        audioSeconds: number;
+        model: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Write session start event.
+     */
+    writeSessionStart(options: {
+        sessionId: string;
+        roomName: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Write session end event with final summary.
+     */
+    writeSessionEnd(options: {
+        sessionId: string;
+        summary: Record<string, unknown>;
+    }): Promise<void>;
+}
+/**
+ * Create a file-based metric emitter.
+ *
+ * This creates a MetricEmitter that writes to session-organized JSONL files.
+ *
+ * @example
+ * ```typescript
+ * import { instrument, createFileEmitter } from "aden";
+ *
+ * instrument({
+ *   emitMetric: createFileEmitter({ logDir: "./my_logs" }),
+ * });
+ * ```
+ *
+ * @param options - Options for the file logger
+ * @returns A MetricEmitter function
+ */
+declare function createFileEmitter(options?: MetricFileLoggerOptions): MetricEmitter;
+
+/**
+ * HTTP transport for sending metrics to a central API endpoint.
+ *
+ * This is the recommended approach for production - clients send metrics
+ * to your API, which handles storage, aggregation, and multi-tenancy.
+ */
+
+/**
+ * Callback when metrics are dropped due to queue overflow
+ */
+type QueueOverflowHandler = (droppedCount: number) => void;
+/**
+ * Callback when a batch send fails after all retries
+ */
+type SendErrorHandler = (error: Error, batch: MetricEvent[], stats: TransportStats) => void;
+/**
+ * Transport statistics for observability
+ */
+interface TransportStats {
+    /** Total metrics successfully sent */
+    sent: number;
+    /** Total metrics dropped due to queue overflow */
+    dropped: number;
+    /** Total metrics that failed to send after retries */
+    errors: number;
+    /** Current queue size */
+    queued: number;
+}
+/**
+ * Options for the HTTP transport
+ */
+interface HttpTransportOptions {
+    /** API endpoint URL */
+    apiUrl: string;
+    /** API key for authentication (sent as Bearer token) */
+    apiKey?: string;
+    /** Number of events to batch before sending (default: 50) */
+    batchSize?: number;
+    /** Milliseconds between automatic flushes (default: 5000) */
+    flushInterval?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Maximum queue size before dropping events (default: 10000) */
+    maxQueueSize?: number;
+    /** Additional headers to send with requests */
+    headers?: Record<string, string>;
+    /** Callback when events are dropped due to queue overflow */
+    onQueueOverflow?: QueueOverflowHandler;
+    /** Callback when a batch fails to send */
+    onSendError?: SendErrorHandler;
+}
+/**
+ * HTTP transport that batches and sends metrics to an API endpoint.
+ *
+ * Features:
+ * - Batched sending for efficiency
+ * - Automatic periodic flushing
+ * - Retry with exponential backoff
+ * - Queue overflow protection
+ * - Observability via stats
+ *
+ * @example
+ * ```typescript
+ * const transport = createHttpTransport({
+ *   apiUrl: "https://api.example.com/v1/metrics",
+ *   apiKey: "your-api-key",
+ * });
+ *
+ * const metered = makeMeteredOpenAI(client, {
+ *   emitMetric: transport,
+ * });
+ *
+ * // On shutdown
+ * await transport.flush();
+ * transport.stop();
+ * ```
+ */
+declare class HttpTransport {
+    private readonly apiUrl;
+    private readonly apiKey?;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly maxQueueSize;
+    private readonly extraHeaders;
+    private readonly onQueueOverflow?;
+    private readonly onSendError?;
+    private queue;
+    private flushTimer;
+    private isStopped;
+    private sentCount;
+    private droppedCount;
+    private errorCount;
+    constructor(options: HttpTransportOptions);
+    private startFlushTimer;
+    /**
+     * Add an event to the send queue.
+     * This is the MetricEmitter interface.
+     */
+    emit: MetricEmitter;
+    /**
+     * Flush pending events (async version)
+     */
+    flushAsync(): Promise<void>;
+    /**
+     * Flush pending events (sync-friendly, returns promise)
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush all pending events (may require multiple batches)
+     */
+    flushAll(): Promise<void>;
+    private sendBatch;
+    private sleep;
+    /**
+     * Get transport statistics
+     */
+    get stats(): TransportStats;
+    /**
+     * Stop the transport and flush remaining events
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the transport is stopped
+     */
+    get stopped(): boolean;
+}
+/**
+ * Create an HTTP transport for sending metrics to an API.
+ *
+ * @example
+ * ```typescript
+ * // Using options
+ * const transport = createHttpTransport({
+ *   apiUrl: "https://api.example.com/v1/metrics",
+ *   apiKey: "your-api-key",
+ *   batchSize: 100,
+ * });
+ *
+ * // Using environment variables
+ * // Set METER_API_URL and optionally METER_API_KEY
+ * const transport = createHttpTransport();
+ * ```
+ */
+declare function createHttpTransport(options?: Partial<HttpTransportOptions>): HttpTransport;
+/**
+ * Create an HTTP transport emitter function.
+ *
+ * This is a convenience function that returns just the emit function,
+ * suitable for use directly as a MetricEmitter.
+ *
+ * Note: The returned emitter cannot be stopped or flushed. For production use,
+ * prefer createHttpTransport() which gives you access to stop() and flush().
+ *
+ * @example
+ * ```typescript
+ * const metered = makeMeteredOpenAI(client, {
+ *   emitMetric: createHttpEmitter({
+ *     apiUrl: "https://api.example.com/v1/metrics",
+ *   }),
+ * });
+ * ```
+ */
+declare function createHttpEmitter(options?: Partial<HttpTransportOptions>): MetricEmitter;
+
+/**
+ * Time-series data point for trend analysis
+ */
+interface TimeSeriesPoint {
+    timestamp: Date;
+    value: number;
+}
+/**
+ * Comprehensive analytics for CTO-level reporting
+ */
+interface AnalyticsReport {
+    costs: {
+        total: number;
+        byModel: Record<string, number>;
+        byHour: TimeSeriesPoint[];
+        projectedMonthly: number;
+        cacheSavings: number;
+        avgCostPerRequest: number;
+        avgCostPer1kTokens: number;
+    };
+    performance: {
+        avgLatency: number;
+        p50Latency: number;
+        p95Latency: number;
+        p99Latency: number;
+        requestsPerMinute: number;
+        tokensPerSecond: number;
+    };
+    efficiency: {
+        cacheHitRate: number;
+        avgInputTokens: number;
+        avgOutputTokens: number;
+        inputOutputRatio: number;
+        reasoningOverhead: number;
+    };
+    reliability: {
+        successRate: number;
+        errorRate: number;
+        errorsByType: Record<string, number>;
+        avgRetriesPerRequest: number;
+    };
+    usage: {
+        totalRequests: number;
+        totalTokens: number;
+        peakRequestsPerMinute: number;
+        peakHour: string;
+        modelDistribution: Record<string, number>;
+    };
+}
+/**
+ * Analytics engine for collecting and analyzing metrics
+ */
+declare class AnalyticsEngine {
+    private events;
+    private pricing;
+    private startTime;
+    constructor(customPricing?: Record<string, {
+        input: number;
+        output: number;
+        cached: number;
+    }>);
+    /**
+     * Record a metric event
+     */
+    record(event: MetricEvent): void;
+    /**
+     * Get the pricing for a model (with fallback to base model)
+     */
+    private getModelPricing;
+    /**
+     * Calculate cost for a single event
+     */
+    private calculateEventCost;
+    /**
+     * Calculate percentile from sorted array
+     */
+    private percentile;
+    /**
+     * Generate comprehensive analytics report
+     */
+    generateReport(): AnalyticsReport;
+    /**
+     * Classify error type
+     */
+    private classifyError;
+    /**
+     * Format report as markdown for CTO presentation
+     */
+    formatMarkdown(report: AnalyticsReport): string;
+    /**
+     * Generate actionable recommendations based on metrics
+     */
+    private generateRecommendations;
+    /**
+     * Reset analytics data
+     */
+    reset(): void;
+    /**
+     * Get raw events
+     */
+    getEvents(): MetricEvent[];
+}
+/**
+ * Create an emitter that feeds into the analytics engine
+ */
+declare function createAnalyticsEmitter(engine: AnalyticsEngine): (event: MetricEvent) => void;
+
+/**
+ * JSON Schema types for comprehensive analytics reporting
+ */
+/**
+ * Individual request/event within a pattern
+ */
+interface PatternEvent {
+    id: string;
+    timestamp: string;
+    model: string;
+    latency_ms: number;
+    input_tokens: number;
+    output_tokens: number;
+    cached_tokens: number;
+    reasoning_tokens: number;
+    cost: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Multi-turn conversation pattern
+ */
+interface ConversationPattern {
+    type: "conversation";
+    conversation_id: string;
+    user_id?: string;
+    started_at: string;
+    ended_at?: string;
+    turns: Array<{
+        turn_number: number;
+        role: "user" | "assistant";
+        event: PatternEvent;
+        context_tokens: number;
+        context_utilization: number;
+        cumulative_cost: number;
+        cache_efficiency: number;
+    }>;
+    summary: {
+        total_turns: number;
+        total_tokens: number;
+        total_cost: number;
+        avg_latency: number;
+        avg_tokens_per_turn: number;
+        context_growth_rate: number;
+        cache_savings: number;
+    };
+}
+/**
+ * Tenant in multi-tenant pattern
+ */
+interface TenantUsage {
+    tenant_id: string;
+    tenant_name?: string;
+    tier: "free" | "pro" | "enterprise" | string;
+    users: Array<{
+        user_id: string;
+        request_count: number;
+        total_tokens: number;
+        total_cost: number;
+    }>;
+    events: PatternEvent[];
+    summary: {
+        total_requests: number;
+        total_tokens: number;
+        total_cost: number;
+        quota_used: number;
+        quota_limit: number;
+        avg_cost_per_request: number;
+        peak_requests_per_minute: number;
+    };
+}
+/**
+ * Multi-tenant agent fleet pattern
+ */
+interface MultiTenantPattern {
+    type: "multi_tenant";
+    period_start: string;
+    period_end: string;
+    tenants: TenantUsage[];
+    summary: {
+        total_tenants: number;
+        total_requests: number;
+        total_tokens: number;
+        total_revenue?: number;
+        total_cost: number;
+        gross_margin?: number;
+        top_tenant_by_usage: string;
+        top_tenant_by_cost: string;
+        tier_distribution: Record<string, number>;
+    };
+}
+/**
+ * Tool call within an agent
+ */
+interface ToolCall {
+    tool_name: string;
+    tool_id: string;
+    input: Record<string, unknown>;
+    output?: unknown;
+    duration_ms: number;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Agent execution within cascaded pattern
+ */
+interface AgentExecution {
+    agent_id: string;
+    agent_name: string;
+    agent_type: "orchestrator" | "worker" | "specialist";
+    parent_agent_id?: string;
+    depth: number;
+    started_at: string;
+    ended_at: string;
+    model: string;
+    events: PatternEvent[];
+    tool_calls: ToolCall[];
+    subagents: AgentExecution[];
+    summary: {
+        total_llm_calls: number;
+        total_tool_calls: number;
+        total_tokens: number;
+        total_cost: number;
+        total_duration_ms: number;
+        success: boolean;
+        error?: string;
+    };
+}
+/**
+ * Multi-agent cascaded pattern
+ */
+interface CascadedAgentPattern {
+    type: "cascaded_agents";
+    task_id: string;
+    task_description?: string;
+    started_at: string;
+    ended_at: string;
+    root_agent: AgentExecution;
+    summary: {
+        total_agents: number;
+        max_depth: number;
+        total_llm_calls: number;
+        total_tool_calls: number;
+        total_tokens: number;
+        total_cost: number;
+        total_duration_ms: number;
+        parallelism_factor: number;
+        cost_by_agent_type: Record<string, number>;
+        tokens_by_depth: Record<number, number>;
+        tool_usage: Record<string, {
+            count: number;
+            avg_duration_ms: number;
+            success_rate: number;
+        }>;
+    };
+}
+/**
+ * Complete analytics report with all patterns
+ */
+interface AnalyticsJSON {
+    generated_at: string;
+    period: {
+        start: string;
+        end: string;
+        duration_hours: number;
+    };
+    summary: {
+        total_requests: number;
+        total_tokens: number;
+        total_cost: number;
+        projected_monthly_cost: number;
+        cache_savings: number;
+        success_rate: number;
+        avg_latency_ms: number;
+        p50_latency_ms: number;
+        p95_latency_ms: number;
+        p99_latency_ms: number;
+    };
+    costs: {
+        by_model: Record<string, {
+            requests: number;
+            tokens: number;
+            cost: number;
+        }>;
+        by_hour: Array<{
+            hour: string;
+            cost: number;
+            requests: number;
+        }>;
+        by_pattern_type: Record<string, number>;
+    };
+    patterns: {
+        conversations: ConversationPattern[];
+        multi_tenant: MultiTenantPattern | null;
+        cascaded_agents: CascadedAgentPattern[];
+    };
+    recommendations: Array<{
+        category: "cost" | "performance" | "efficiency" | "reliability";
+        severity: "info" | "warning" | "critical";
+        title: string;
+        description: string;
+        potential_savings?: number;
+        action: string;
+    }>;
+}
+
+/**
+ * Report Builder
+ * Combines real analytics data with pattern simulations to generate comprehensive reports
+ */
+
+interface ReportBuilderOptions {
+    /**
+     * Include simulated conversation patterns
+     */
+    simulateConversations?: number;
+    /**
+     * Include simulated multi-tenant data
+     */
+    simulateMultiTenant?: {
+        tenants: number;
+        requestsPerTenant?: {
+            min: number;
+            max: number;
+        };
+    };
+    /**
+     * Include simulated cascaded agent executions
+     */
+    simulateCascadedAgents?: number;
+    /**
+     * Custom model pricing
+     */
+    pricing?: Record<string, {
+        input: number;
+        output: number;
+        cached: number;
+    }>;
+}
+/**
+ * Report Builder for generating comprehensive analytics reports
+ */
+declare class ReportBuilder {
+    private events;
+    private conversations;
+    private multiTenant;
+    private cascadedAgents;
+    private startTime;
+    private pricing;
+    constructor(options?: {
+        pricing?: Record<string, {
+            input: number;
+            output: number;
+            cached: number;
+        }>;
+    });
+    /**
+     * Record a metric event from real API calls
+     */
+    recordEvent(event: MetricEvent): void;
+    /**
+     * Add a conversation pattern (real or simulated)
+     */
+    addConversation(conversation: ConversationPattern): void;
+    /**
+     * Set multi-tenant data (real or simulated)
+     */
+    setMultiTenant(data: MultiTenantPattern): void;
+    /**
+     * Add a cascaded agent execution (real or simulated)
+     */
+    addCascadedAgent(execution: CascadedAgentPattern): void;
+    /**
+     * Simulate and add patterns based on options
+     */
+    addSimulatedPatterns(options: ReportBuilderOptions): void;
+    /**
+     * Calculate cost for MetricEvent
+     */
+    private calculateEventCost;
+    /**
+     * Calculate cost for UnifiedEvent
+     */
+    private calculateUnifiedEventCost;
+    /**
+     * Generate the complete analytics JSON
+     */
+    buildJSON(): AnalyticsJSON;
+    /**
+     * Generate recommendations based on metrics
+     */
+    private generateRecommendations;
+    /**
+     * Build and return HTML report
+     */
+    buildHTML(): string;
+    /**
+     * Reset the builder
+     */
+    reset(): void;
+}
+/**
+ * Create a metric emitter that feeds into the report builder
+ */
+declare function createReportEmitter(builder: ReportBuilder): (event: MetricEvent) => void;
+
+/**
+ * HTML Report Generator
+ * Creates interactive HTML reports with charts for CTO-level analytics
+ */
+
+/**
+ * Generate complete HTML report from analytics JSON
+ */
+declare function generateHTMLReport(data: AnalyticsJSON): string;
+
+/**
+ * Pattern Simulator for generating realistic analytics data
+ * Simulates multi-turn conversations, multi-tenant fleets, and cascaded agents
+ */
+
+/**
+ * Simulate a multi-turn conversation
+ */
+declare function simulateConversation(options: {
+    turns?: number;
+    model?: string;
+    userId?: string;
+    enableCaching?: boolean;
+}): ConversationPattern;
+/**
+ * Simulate multi-tenant usage
+ */
+declare function simulateMultiTenant(options: {
+    tenantCount?: number;
+    requestsPerTenant?: {
+        min: number;
+        max: number;
+    };
+    tiers?: Array<{
+        name: string;
+        quota: number;
+        weight: number;
+    }>;
+}): MultiTenantPattern;
+/**
+ * Simulate cascaded multi-agent execution
+ */
+declare function simulateCascadedAgents(options: {
+    taskDescription?: string;
+    maxDepth?: number;
+    avgSubagentsPerLevel?: number;
+    toolsAvailable?: string[];
+}): CascadedAgentPattern;
+
+/**
+ * Logging configuration for the aden SDK.
+ *
+ * Provides a simple logging abstraction that can be configured via
+ * environment variables or programmatically.
+ */
+/**
+ * Log levels in order of severity
+ */
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/**
+ * Logging configuration options
+ */
+interface LoggingConfig {
+    /** Global log level for the SDK. Default: "info" or ADEN_LOG_LEVEL env var */
+    level?: LogLevel;
+    /** Log level for metrics-specific logs. Default: same as level */
+    metricsLevel?: LogLevel;
+    /** Custom log handler. Default: console */
+    handler?: LogHandler;
+}
+/**
+ * Log handler interface
+ */
+interface LogHandler {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Configure logging for the aden SDK.
+ *
+ * @example
+ * ```typescript
+ * import { configureLogging } from "aden";
+ *
+ * // Set log level to debug
+ * configureLogging({ level: "debug" });
+ *
+ * // Quiet metrics logs but keep other logs
+ * configureLogging({ level: "info", metricsLevel: "warn" });
+ *
+ * // Use a custom log handler
+ * configureLogging({
+ *   handler: {
+ *     debug: (msg, ...args) => myLogger.debug(msg, ...args),
+ *     info: (msg, ...args) => myLogger.info(msg, ...args),
+ *     warn: (msg, ...args) => myLogger.warn(msg, ...args),
+ *     error: (msg, ...args) => myLogger.error(msg, ...args),
+ *   },
+ * });
+ * ```
+ */
+declare function configureLogging(config: LoggingConfig): void;
+/**
+ * Get the current logging configuration
+ */
+declare function getLoggingConfig(): Readonly<Required<LoggingConfig>>;
+/**
+ * Reset logging configuration to defaults
+ */
+declare function resetLoggingConfig(): void;
+/**
+ * Logger for the aden SDK
+ */
+declare const logger: {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};
+/**
+ * Logger for metrics-specific logs
+ */
+declare const metricsLogger: {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};
+
+/**
+ * Control Agent - Bidirectional communication with control server
+ *
+ * Emits: metrics, control events, heartbeat
+ * Receives: control policies (budgets, throttle, block, degrade)
+ *
+ * Uses WebSocket for real-time communication with HTTP polling fallback.
+ */
+
+/**
+ * Control Agent implementation
+ */
+declare class ControlAgent implements IControlAgent {
+    private options;
+    private ws;
+    private cachedPolicy;
+    private lastPolicyFetch;
+    private pollingTimer;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private connected;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private eventQueue;
+    private maxQueueSize;
+    private requestsSinceLastHeartbeat;
+    private errorsSinceLastHeartbeat;
+    private requestCounts;
+    constructor(options: ControlAgentOptions);
+    /**
+     * Connect to the control server
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect via WebSocket
+     */
+    private connectWebSocket;
+    /**
+     * Schedule WebSocket reconnection
+     */
+    private scheduleReconnect;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Start HTTP polling for policy updates
+     * Returns a promise that resolves when the first policy fetch completes
+     */
+    private startPolling;
+    /**
+     * Stop HTTP polling
+     */
+    private stopPolling;
+    /**
+     * Fetch policy via HTTP
+     */
+    private fetchPolicy;
+    /**
+     * Start heartbeat timer
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat timer
+     */
+    private stopHeartbeat;
+    /**
+     * Send heartbeat event
+     */
+    private sendHeartbeat;
+    /**
+     * Disconnect from the control server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get a control decision for a request
+     */
+    getDecision(request: ControlRequest): Promise<ControlDecision>;
+    /**
+     * Evaluate policy rules against a request
+     * Priority order: block > budget/degrade > throttle > alert > allow
+     * Note: throttle adds delay but doesn't skip other checks
+     */
+    private evaluatePolicy;
+    /**
+     * Check if request matches an alert rule
+     */
+    private matchesAlertRule;
+    /**
+     * Check if request matches a block rule
+     */
+    private matchesBlockRule;
+    /**
+     * Find budgets that apply to the given request based on budget type
+     */
+    private findApplicableBudgets;
+    /**
+     * Check rate limit for a key
+     */
+    private checkRateLimit;
+    /**
+     * Report a metric event to the server
+     */
+    reportMetric(event: MetricEvent): Promise<void>;
+    /**
+     * Estimate cost from a metric event
+     * Uses gpt-4o pricing as default: $2.50/1M input, $10/1M output
+     */
+    private estimateCost;
+    /**
+     * Calculate the sampling rate for server validation based on usage percentage.
+     *
+     * The rate interpolates from samplingBaseRate at threshold to 1.0 at
+     * samplingFullValidationPercent.
+     *
+     * Example with defaults (threshold=80%, base_rate=0.1, full=95%):
+     * - At 80%: 10% of requests validated
+     * - At 87.5%: 55% of requests validated
+     * - At 95%+: 100% of requests validated
+     */
+    private calculateSamplingRate;
+    /**
+     * Determine if we should validate this request with the server.
+     *
+     * Uses adaptive thresholds and probabilistic sampling to minimize
+     * latency impact while maintaining enforcement accuracy.
+     *
+     * Returns true if:
+     * 1. Hybrid enforcement is enabled
+     * 2. Budget usage is at or above the validation threshold
+     * 3. Either:
+     *    a. Remaining budget is below adaptiveMinRemainingUsd (always validate)
+     *    b. Sampling dice roll succeeds based on current usage level
+     */
+    private shouldValidateWithServer;
+    /**
+     * Check if request exceeds the hard limit (soft limit + max overspend buffer).
+     *
+     * This provides a safety net to prevent runaway spending even under
+     * concurrency race conditions.
+     *
+     * Returns a BLOCK decision if hard limit exceeded, null otherwise.
+     */
+    private checkHardLimit;
+    /**
+     * Validate budget with server synchronously.
+     *
+     * Returns BudgetValidationResponse if successful, null if validation failed.
+     * On failure, caller should fall back to local enforcement based on failOpen.
+     */
+    private validateBudgetWithServer;
+    /**
+     * Convert server validation response to a ControlDecision
+     */
+    private applyServerValidationResult;
+    /**
+     * Evaluate a single budget with hybrid enforcement
+     */
+    private evaluateBudgetWithHybridEnforcement;
+    /**
+     * Report a control event to the server
+     */
+    reportControlEvent(event: Omit<ControlEvent, "event_type" | "timestamp" | "sdk_instance_id">): Promise<void>;
+    /**
+     * Report an error event
+     */
+    reportError(message: string, error?: Error, traceId?: string): Promise<void>;
+    /**
+     * Send an event to the server
+     */
+    private sendEvent;
+    /**
+     * Queue an event for later sending
+     */
+    private queueEvent;
+    /**
+     * Flush queued events
+     */
+    private flushEventQueue;
+    /**
+     * Make HTTP request to server
+     */
+    private httpRequest;
+    /**
+     * Check if connected to server (WebSocket)
+     */
+    isConnected(): boolean;
+    /**
+     * Get current cached policy
+     */
+    getPolicy(): ControlPolicy | null;
+}
+/**
+ * Create a control agent
+ */
+declare function createControlAgent(options: ControlAgentOptions): ControlAgent;
+/**
+ * Create a metric emitter that sends to the control agent
+ *
+ * This allows the control agent to work alongside other emitters:
+ * ```typescript
+ * const agent = createControlAgent({ ... });
+ *
+ * await instrument({
+ *   emitMetric: createMultiEmitter([
+ *     createConsoleEmitter({ pretty: true }),
+ *     createControlAgentEmitter(agent),
+ *   ]),
+ *   controlAgent: agent,
+ * });
+ * ```
+ */
+declare function createControlAgentEmitter(agent: IControlAgent): (event: MetricEvent) => Promise<void>;
+
+export { type AgentExecution, type AlertEvent, type AlertRule, AnalyticsEngine, type AnalyticsJSON, type AnalyticsReport, type BeforeRequestContext, type BeforeRequestHook, type BeforeRequestResult, type BlockRule, type BudgetConfig, BudgetExceededError, type BudgetExceededInfo, type BudgetRule, type BudgetValidationRequest, type BudgetValidationResponse, type CallRelationship, type CallSite, type CascadedAgentPattern, type ControlAction, ControlAgent, type ControlAgentOptions, type ControlDecision, type ControlEvent, type ControlPolicy, type ControlRequest, type ConversationPattern, DEFAULT_CONTROL_SERVER, type DegradeRule, type HeartbeatEvent, HttpTransport, type HttpTransportOptions, type IControlAgent, type InstrumentationResult, type JsonFileEmitterOptions, type LogHandler, type LogLevel, type LoggingConfig, type MeterContext, type MeterOptions, type MeteredOpenAI, type MetricEmitter, type MetricEvent, MetricFileLogger, type MetricFileLoggerOptions, type MultiTenantPattern, type NormalizedUsage, type PatternEvent, type QueueOverflowHandler, type RateLimitInfo, ReportBuilder, RequestCancelledError, type RequestMetadata, type SDKClasses, type SendErrorHandler, type StreamingEventType, type TenantUsage, type ThrottleRule, type ToolCall, type ToolCallMetric, type TransportStats, configureLogging, countInputTokens, createAnalyticsEmitter, createBatchEmitter, createBudgetedMeteredClient, createConsoleEmitter, createControlAgent, createControlAgentEmitter, createFileEmitter, createFilteredEmitter, createHttpEmitter, createHttpTransport, createJsonFileEmitter, createMemoryEmitter, createMeterContext, createMultiEmitter, createNoopEmitter, createReportEmitter, createTransformEmitter, emptyUsage, enterMeterContext, extractAgentStack, extractCallSite, generateHTMLReport, generateStackFingerprint, getContextMetadata, getControlServerUrl, getCurrentContext, getFullAgentStack, getGenaiOptions, getInstrumentationOptions, getInstrumentedSDKs, getLoggingConfig, hasContext, instrument, instrumentAnthropic, instrumentFetch, instrumentGemini, instrumentGenai, instrumentOpenAI, isAnthropicInstrumented, isFetchInstrumented, isGeminiInstrumented, isGenaiInstrumented, isInstrumented, isMetered, isOpenAIInstrumented, logger, makeMeteredOpenAI, mergeUsage, metricsLogger, normalizeAnthropicUsage, normalizeGeminiUsage, normalizeOpenAIUsage, normalizeUsage, popAgent, pushAgent, resetGlobalSession, resetLoggingConfig, setContextMetadata, simulateCascadedAgents, simulateConversation, simulateMultiTenant, uninstrument, uninstrumentAnthropic, uninstrumentFetch, uninstrumentGemini, uninstrumentGenai, uninstrumentOpenAI, updateInstrumentationOptions, withAgent, withBudgetGuardrails, withMeterContext, withMeterContextAsync };