umans-gate 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,1094 +0,0 @@
-import { Database } from 'bun:sqlite';
-
-/** Normalized per-request usage metrics. All fields nullable. */
-interface UsageMetrics {
-    /** Provider: "anthropic" | "openai" */
-    provider: "anthropic" | "openai";
-    /** Streaming or non-streaming response. */
-    streaming: boolean;
-    /** Non-cached input tokens. */
-    input_tokens: number | null;
-    /** Output tokens (cumulative, authoritative, billed). */
-    output_tokens: number | null;
-    /** Tokens written to cache (Anthropic: cache_creation_input_tokens; OpenAI: n/a). */
-    cache_creation_tokens: number | null;
-    /** Tokens read from cache (Anthropic: cache_read_input_tokens; OpenAI: prompt_tokens_details.cached_tokens). */
-    cache_read_tokens: number | null;
-    /** Total input = input + cache_creation + cache_read (Anthropic) or prompt_tokens (OpenAI). */
-    total_input_tokens: number | null;
-    /** Total output (same as output_tokens for Anthropic; completion_tokens for OpenAI). */
-    total_output_tokens: number | null;
-    /** Tokens spent on internal reasoning (optional, nullable). */
-    thinking_tokens: number | null;
-    /** Time-to-first-token in ms. DERIVED from event timing, never an API field. */
-    ttft_ms: number | null;
-    /** Full request duration in ms. */
-    duration_ms: number | null;
-    /** Tokens-per-second = output_tokens / ((duration_ms - ttft_ms) / 1000). Null if not computable. */
-    tps: number | null;
-    /** True if usage was absent (stream aborted, or include_usage not set). */
-    usage_missing: boolean;
-    /** Model name (set by extractUsage wrapper; not populated by individual extractors). */
-    model?: string;
-}
-/** A chunk of SSE data with its wall-clock receive timestamp. */
-interface TimedChunk {
-    text: string;
-    time: number;
-}
-/** Aggregated per-model performance stats (computed in SQL, not JS). */
-interface PerformanceStatsRow {
-    model: string;
-    provider: "anthropic" | "openai";
-    request_count: number;
-    streaming_count: number;
-    total_input_tokens: number;
-    total_output_tokens: number;
-    total_cache_read_tokens: number;
-    total_thinking_tokens: number;
-    cached_pct: number;
-    ttft_mean: number | null;
-    ttft_p10: number | null;
-    ttft_p50: number | null;
-    ttft_p95: number | null;
-    ttft_outlier_count: number;
-    tps_mean: number | null;
-    tps_p10: number | null;
-    tps_p50: number | null;
-    tps_p95: number | null;
-    tps_outlier_count: number;
-}
-
-/** HTTP protocol used for the upstream connection. */
-type UpstreamProtocol = "http2" | "http1.1";
-/** HTTP protocol for incoming connections (always http1.1 without TLS). */
-type IncomingProtocol = "http1.1";
-/** Capture state lifecycle. */
-type CaptureState = "enqueued" | "streaming" | "done";
-/** A full capture row from the database. */
-interface CaptureRow {
-    id: number;
-    method: string;
-    path: string;
-    url: string;
-    request_headers: string | null;
-    request_body: string | null;
-    request_size: number;
-    response_status: number | null;
-    response_headers: string | null;
-    response_body: string | null;
-    response_size: number;
-    content_type: string | null;
-    is_sse: number;
-    duration_ms: number;
-    state: CaptureState;
-    started_at: number | null;
-    finished_at: number | null;
-    incoming_protocol: string | null;
-    upstream_protocol: string | null;
-    provider: string | null;
-    model: string | null;
-    streaming: number | null;
-    input_tokens: number | null;
-    output_tokens: number | null;
-    cache_creation_tokens: number | null;
-    cache_read_tokens: number | null;
-    total_input_tokens: number | null;
-    total_output_tokens: number | null;
-    thinking_tokens: number | null;
-    ttft_ms: number | null;
-    tps: number | null;
-    usage_missing: number | null;
-    metrics_extracted_at: number | null;
-    is_vision: number;
-    parent_capture_id: number | null;
-    status_source: string | null;
-    gate_reason: string | null;
-}
-/** Summary of a capture (no body data) — used in list view and WS broadcasts. */
-interface CaptureSummary {
-    id: number;
-    method: string;
-    path: string;
-    response_status: number | null;
-    is_sse: boolean;
-    content_type: string | null;
-    request_size: number;
-    response_size: number;
-    duration_ms: number;
-    state: CaptureState;
-    started_at: number | null;
-    finished_at: number | null;
-    incoming_protocol: string;
-    upstream_protocol: string;
-    model: string | null;
-    usage_missing: boolean | null;
-    /** Time-to-first-token in ms (null if not computed or non-streaming). */
-    ttft_ms: number | null;
-    /** Tokens-per-second (null if not computable). */
-    tps: number | null;
-    /** Tokens written to cache (Anthropic cache_creation_input_tokens). */
-    cache_creation_tokens: number | null;
-    /** Tokens read from cache (cache hits). */
-    cache_read_tokens: number | null;
-    /** Total input tokens (input + cache_creation + cache_read). */
-    total_input_tokens: number | null;
-    /** Output tokens (non-cached, billed). */
-    output_tokens: number | null;
-    /** Total output tokens (same as output_tokens for most providers). */
-    total_output_tokens: number | null;
-    /** True if this row is a vision-model API call (merged into captures). */
-    is_vision: boolean;
-    /** "upstream" = status from upstream API; "gate" = proxy-generated; null = not yet recorded. */
-    status_source: "upstream" | "gate" | null;
-    /** Human-readable explanation when the proxy generated the HTTP status. */
-    gate_reason: string | null;
-}
-/** Request metadata captured at proxy time. */
-interface RequestMeta {
-    method: string;
-    path: string;
-    request_size: number;
-    started_at: number;
-}
-/** Response metadata queued for write-behind. */
-interface ResponseMeta {
-    $status: number;
-    $rh: string;
-    $rb: string;
-    $rs: number;
-    $ct: string;
-    $sse: number;
-    $dur: number;
-    $fin: number;
-    $status_source: "upstream" | "gate" | null;
-    $gate_reason: string | null;
-    $usage?: UsageMetrics | null;
-    $model?: string | null;
-}
-/** WebSocket message types broadcast to connected inspector clients. */
-type WsMessage = {
-    type: "new";
-    capture: CaptureSummary;
-} | {
-    type: "update";
-    capture: CaptureSummary;
-} | {
-    type: "state";
-    captureId: number;
-    state: CaptureState;
-} | {
-    type: "gate";
-    stats: GateStats;
-} | {
-    type: "clear";
-} | {
-    type: "vision-clear";
-};
-/** Configuration object resolved from environment variables. */
-interface ProxyConfig {
-    port: number;
-    host: string;
-    target: string;
-    maxCaptures: number;
-    dbPath: string;
-    viewerPrefix: string;
-    flushIntervalMs: number;
-    flushBatch: number;
-    idleTimeout: number;
-    upstreamProtocol: UpstreamProtocol;
-    incomingProtocol: IncomingProtocol;
-    /** Apply the Claude Code stamp bundle on Anthropic requests (TTL, top_k, max_tokens, thinking, output_config, context_management). */
-    stampClaudeCode: boolean;
-    /** Value to inject as `reasoning_effort` on OpenAI request bodies. Null = disabled. */
-    stampReasoningEffort: "high" | "max" | null;
-    openaiPath: string;
-    /** Upstream connection warmer — pings upstream to prevent TLS handshake overhead on first request. */
-    warmerEnabled: boolean;
-    /** Warmer ping interval in milliseconds. */
-    warmerIntervalMs: number;
-    /** Path appended to `target` for warmer pings (no auth required). */
-    warmerPath: string;
-    /** Umans API key for /v1/usage calls (required for tier-aware limits). Null = fail-safe mode. */
-    umansApiKey: string | null;
-    /** Polling interval for /v1/usage reconciliation, in ms. */
-    usageRefreshMs: number;
-    /** Polling interval for /v1/models fetch (model weights + listing), in ms. */
-    modelsRefreshMs: number;
-    /** Persisted concurrency hard cap (from /v1/usage, editable for robustness testing). */
-    concurrencyHardCap: number;
-    /** Persisted concurrency soft limit (from /v1/usage, read-only display). */
-    concurrencySoftLimit: number;
-    /** Pro-tier rolling window: -1 = unlimited (no limiter), 0 = auto-derive from /v1/usage, >0 = explicit limit. */
-    rateLimitRequests: number;
-    /** Max time a request can wait in the queue before 503, in ms. */
-    queueTimeoutMs: number;
-    /** Max depth of the enqueued-waiters queue before 503-on-full. */
-    maxQueueDepth: number;
-    /** Cooldown after releasing a permit before reusing the slot, in ms. */
-    releaseCooldownMs: number;
-    /** Concurrency-429 count to trip the circuit breaker. */
-    breakerThreshold: number;
-    /** Time window for breaker 429 counting, in ms. */
-    breakerWindowMs: number;
-    /** Circuit breaker OPEN cooldown before HALF_OPEN probe, in ms. */
-    breakerCooldownMs: number;
-    /** Vision handoff strategy: never (off), catalog (model lookup), always. */
-    visionStrategy: "never" | "catalog" | "always";
-    /** URL of vision model API, or null to disable. */
-    visionTarget: string | null;
-    /** Model name sent to the vision API. */
-    visionModel: string | null;
-    /** Prompt sent to the vision model. */
-    visionPrompt: string;
-    /** Prompt version, for cache invalidation. */
-    visionPromptVersion: number;
-    /** Max images to process per request. */
-    visionMaxImages: number;
-    /** Max tokens for the description returned by the vision model. */
-    visionMaxDescriptionTokens: number;
-    /** Reasoning effort for vision model ("none"|"low"|"medium"|"high"). Null = don't send field. */
-    visionReasoningEffort: "none" | "low" | "medium" | "high" | null;
-    /** Timeout for vision model calls, in ms. */
-    visionTimeoutMs: number;
-    /** LRU cache size for vision descriptions. */
-    visionCacheSize: number;
-    /** TTL for vision cache entries (both in-memory and persistent), in ms. */
-    visionCacheTtlMs: number;
-    /** Hard row ceiling for the persistent vision cache table. */
-    visionCacheMaxRows: number;
-    /** Enable SQLite-backed persistent description cache. */
-    visionPersistentCache: boolean;
-    /** When true (catalog strategy), also intercept images for vision-capable
-     *  models — converting them to cacheable text descriptions for KV cache
-     *  efficiency and to bypass the 10-image-per-session limit. */
-    visionForceInterceptCapable: boolean;
-    /** Max concurrent vision-model API calls across all requests (default 1). */
-    visionConcurrency: number;
-    /** Max image dimension (longest side) after transcode, in pixels. */
-    visionMaxDimension: number;
-    /** JPEG quality 1–100 (used only when image_format is "jpeg"). */
-    visionJpegQuality: number;
-    /** Image format for transcoded images: "jpeg" (lossy) or "png" (lossless). */
-    visionImageFormat: "jpeg" | "png";
-    /** OpenAI image_url detail parameter: "auto", "low", or "high". */
-    visionImageDetail: "auto" | "low" | "high";
-    /** When true, vision cache misses forward the original body and process vision in the background. */
-    backgroundVision: boolean;
-    /** Reserved concurrency slots for the "main" intention (default 1). */
-    concurrencyMainReservation: number;
-    /** Reserved concurrency slots for the "vision" intention (default 1). */
-    concurrencyVisionReservation: number;
-    /** Max captured request/response body size in bytes. 0 = unlimited. */
-    captureBodyMaxBytes: number;
-    /** Max depth of the write-behind response queue. Distinct from waiters queue. */
-    queueMaxDepth: number;
-    /** WebSocket backpressure limit in bytes. 0 = use Bun default. */
-    wsBackpressureLimit: number;
-    /** Close WebSocket connections that exceed the backpressure limit. */
-    wsCloseOnBackpressureLimit: boolean;
-    /** Max pending vision requests to batch together. */
-    visionPendingMaxBatch: number;
-    /** Enable zstd compression for captured text payloads. */
-    compressionEnabled: boolean;
-    /** Use a Bun Worker for write-behind batch updates (offloads event loop blocking). */
-    useWriteWorker: boolean;
-    /** Hard timeout for upstream requests in milliseconds. Prevents permit leaks when upstream hangs and client stays connected. */
-    upstreamTimeoutMs: number;
-}
-/** Upstream/incoming protocol fields — used by summary builders. */
-interface ProtocolConfig {
-    incomingProtocol: ProxyConfig["incomingProtocol"];
-    upstreamProtocol: ProxyConfig["upstreamProtocol"];
-    upstreamTimeoutMs: ProxyConfig["upstreamTimeoutMs"];
-}
-/** Stamp-related fields used by the proxy stamp pipeline. */
-interface StampConfig {
-    stampClaudeCode: ProxyConfig["stampClaudeCode"];
-    stampReasoningEffort: ProxyConfig["stampReasoningEffort"];
-    openaiPath: ProxyConfig["openaiPath"];
-}
-/** Capture-related fields used by the proxy for body truncation + DB path. */
-interface CaptureConfig {
-    target: ProxyConfig["target"];
-    captureBodyMaxBytes: ProxyConfig["captureBodyMaxBytes"];
-    maxCaptures: ProxyConfig["maxCaptures"];
-    dbPath: ProxyConfig["dbPath"];
-    backgroundVision: ProxyConfig["backgroundVision"];
-}
-/** Gate-related fields for concurrency/rate-limit/circuit-breaker tuning. */
-interface GateConfig {
-    concurrencyHardCap: ProxyConfig["concurrencyHardCap"];
-    concurrencySoftLimit: ProxyConfig["concurrencySoftLimit"];
-    rateLimitRequests: ProxyConfig["rateLimitRequests"];
-    queueTimeoutMs: ProxyConfig["queueTimeoutMs"];
-    maxQueueDepth: ProxyConfig["maxQueueDepth"];
-    releaseCooldownMs: ProxyConfig["releaseCooldownMs"];
-    breakerThreshold: ProxyConfig["breakerThreshold"];
-    breakerWindowMs: ProxyConfig["breakerWindowMs"];
-    breakerCooldownMs: ProxyConfig["breakerCooldownMs"];
-    concurrencyMainReservation: ProxyConfig["concurrencyMainReservation"];
-    concurrencyVisionReservation: ProxyConfig["concurrencyVisionReservation"];
-}
-/** Write-behind queue flush fields used by WriteQueue. */
-interface QueueConfig {
-    flushIntervalMs: ProxyConfig["flushIntervalMs"];
-    flushBatch: ProxyConfig["flushBatch"];
-    queueMaxDepth: ProxyConfig["queueMaxDepth"];
-}
-/** A cache_control block in an Anthropic message body. */
-interface CacheControlBlock {
-    type: string;
-    ttl?: string;
-}
-/** Anthropic message content block that may carry cache_control. */
-interface ContentBlock {
-    type?: string;
-    text?: string;
-    cache_control?: CacheControlBlock;
-    [key: string]: unknown;
-}
-/** Anthropic `thinking` block injected for matching models. */
-interface ThinkingConfig {
-    type: "adaptive";
-}
-/** Anthropic `output_config` block injected for matching models. */
-interface OutputConfig {
-    effort: "high" | "max";
-}
-/** Anthropic request body shape (subset we care about for TTL stamping). */
-interface AnthropicBody {
-    system?: ContentBlock[] | string;
-    messages?: Array<{
-        role: string;
-        content: ContentBlock[] | string;
-    }>;
-    max_tokens?: number;
-    thinking?: ThinkingConfig;
-    output_config?: OutputConfig;
-    context_management?: {
-        edits: Array<{
-            type: string;
-            keep: string;
-        }>;
-    };
-    [key: string]: unknown;
-}
-/** Snapshot of /v1/usage response (subset we care about). */
-interface UsageSnapshot {
-    ok: boolean;
-    fetchedAt: number;
-    plan: "Code Pro" | "Code Max" | "unknown";
-    requestsLimit: number | null;
-    requestsHardCap: number | null;
-    requestsWindowSeconds: number | null;
-    concurrencySoftLimit: number;
-    concurrencyHardCap: number;
-    requestsInWindow: number;
-    requestsRemaining: number | null;
-    concurrentSessions: number;
-    priorityLow: boolean;
-    boxedUntil: number | null;
-    boxedReason: string | null;
-    unitsDemoted: boolean;
-    demotedUntil: number | null;
-}
-/** Discriminated state of the circuit breaker. */
-type BreakerState = "closed" | "open" | "half_open";
-/** Stats snapshot for the dashboard gate panel. */
-interface GateStats {
-    active: number;
-    queued: number;
-    softLimit: number;
-    hardCap: number;
-    tier: "Code Pro" | "Code Max" | "unknown";
-    breaker: BreakerState;
-    boxed: boolean;
-    boxedReason: string | null;
-    boxedUntil: number | null;
-    priorityLow: boolean;
-    unitsDemoted: boolean;
-    demotedUntil: number | null;
-    requestsRemaining: number | null;
-    requestsInWindow: number;
-    requestsLimit: number | null;
-    windowSeconds: number | null;
-    usageOk: boolean;
-    lastUsageFetch: number | null;
-    /** Active permits grouped by intention. */
-    activeByIntention: Record<string, number>;
-    /** Queued waiters grouped by intention. */
-    queuedByIntention: Record<string, number>;
-    /** Reserved concurrency slots per intention. */
-    reservations: Record<string, number>;
-}
-
-/** Resolve the config directory path following OS conventions. */
-declare function resolveConfigDir(): string;
-/** Resolve the config file path (JSON single source of truth). */
-declare function resolveConfigPath(): string;
-/**
- * Fields removed from user config (hardcoded — app is Umans-specific):
- *   target              → "https://api.code.umans.ai"
- *   openai_path         → "chat/completions"
- *   warmer_path         → "/v1/models"
- *   rate_limit_window_seconds → derived from /v1/usage (inherent, not configurable)
- *   vision_target       → derived from target + "/v1/chat/completions"
- *   host                → hardcoded "127.0.0.1" (local-only; use SSH tunnel for remote access)
- */
-interface RawConfig {
-    port?: number;
-    max_captures?: number;
-    db_path?: string;
-    idle_timeout?: number;
-    upstream_protocol?: string;
-    /** When true, applies the full Claude Code stamp bundle on Anthropic requests (TTL, top_k, max_tokens, thinking, output_config, context_management). */
-    stamp_claude_code_enabled?: boolean;
-    /** When true, stamps reasoning_effort onto OpenAI-compatible requests (effort=max for umans-glm* models, effort=high for all others) and removes max_tokens/thinking. */
-    stamp_reasoning_effort_enabled?: boolean;
-    warmer_enabled?: boolean;
-    warmer_interval_ms?: number;
-    umans_api_key?: string;
-    usage_refresh_ms?: number;
-    models_refresh_ms?: number;
-    concurrency_hard_cap?: number;
-    concurrency_soft_limit?: number;
-    /** Pro-tier rolling-window request limit. -1 = unlimited (no limiter), 0 = auto-derive from /v1/usage, >0 = explicit limit. */
-    rate_limit_requests?: number;
-    queue_timeout_ms?: number;
-    max_queue_depth?: number;
-    release_cooldown_ms?: number;
-    breaker_threshold?: number;
-    breaker_window_ms?: number;
-    breaker_cooldown_ms?: number;
-    vision_strategy?: "never" | "catalog" | "always";
-    vision_model?: string;
-    vision_prompt?: string;
-    vision_prompt_version?: number;
-    vision_max_images?: number;
-    vision_max_description_tokens?: number;
-    vision_reasoning_effort?: "none" | "low" | "medium" | "high" | null;
-    vision_timeout_ms?: number;
-    vision_cache_size?: number;
-    vision_cache_ttl_ms?: number;
-    vision_cache_max_rows?: number;
-    vision_persistent_cache?: boolean;
-    vision_concurrency?: number;
-    vision_max_dimension?: number;
-    vision_jpeg_quality?: number;
-    vision_image_format?: "jpeg" | "png";
-    vision_image_detail?: "auto" | "low" | "high";
-    concurrency_main_reservation?: number;
-    concurrency_vision_reservation?: number;
-    /** Max captured request/response body size in bytes. 0 = unlimited. */
-    capture_body_max_bytes?: number;
-    /** Max depth of the write-behind response queue. Distinct from waiters queue. */
-    queue_max_depth?: number;
-    /** WebSocket backpressure limit in bytes. 0 = use Bun default. */
-    ws_backpressure_limit?: number;
-    /** Close WebSocket connections that exceed the backpressure limit. */
-    ws_close_on_backpressure_limit?: boolean;
-    /** Max pending vision requests to batch together. */
-    vision_pending_max_batch?: number;
-    /** Compress stored request/response bodies with zstd. Default true (on). */
-    compression_enabled?: boolean;
-    upstream_timeout_ms?: number;
-}
-/**
- * Input shape accepted by validateConfig/saveConfig. Numeric fields accept
- * strings because HTML form inputs and env vars produce strings. Coercion
- * to RawConfig happens inside validateConfig.
- */
-type RawConfigInput = {
-    [K in keyof RawConfig]?: NonNullable<RawConfig[K]> extends number ? RawConfig[K] | string : RawConfig[K];
-};
-/** Validation result. */
-interface ValidationResult {
-    ok: boolean;
-    errors: string[];
-    warnings: string[];
-    normalized: RawConfig;
-}
-/** Reload result returned by the reload API. */
-interface ReloadResult {
-    ok: boolean;
-    errors: string[];
-    warnings: string[];
-    applied: string[];
-    restartRequired: string[];
-    configPath: string;
-}
-/**
- * Validate a raw config object. Returns errors (blocking), warnings (non-blocking),
- * and a normalized copy with defaults filled in.
- */
-declare function validateConfig(raw: RawConfigInput): ValidationResult;
-/**
- * Write the default config template if no config file exists.
- */
-declare function ensureConfigFile(): string;
-/**
- * Load configuration.
- * Precedence: env vars > JSON config file > defaults.
- * Writes the default config on first run if no file exists.
- * Removed-from-config fields (target, openai_path, warmer_path, vision_target,
- * rate_limit_window_seconds) are hardcoded — app is Umans-specific.
- * Misconfigured numeric fields fall back to their defaults.
- */
-declare function loadConfig(env?: Record<string, string | undefined>): ProxyConfig;
-/**
- * Read the raw config.json from disk (for the config UI).
- * Returns defaults merged with the file contents (no env override).
- */
-declare function readConfigFile(): RawConfig;
-/**
- * Save a partial config to disk (validate first, merge with existing).
- * Returns validation result + the merged config that was written.
- */
-declare function saveConfig(patch: RawConfigInput): {
-    ok: boolean;
-    errors: string[];
-    warnings: string[];
-    written: RawConfig | null;
-};
-
-interface Permit {
-    release: () => void;
-}
-interface ConcurrencyGateOptions {
-    hardCap: number;
-    softLimit: number;
-    releaseCooldownMs: number;
-    breakerThreshold: number;
-    breakerWindowMs: number;
-    breakerCooldownMs: number;
-    maxQueueDepth: number;
-    queueTimeoutMs: number;
-    intentions?: Record<string, number>;
-}
-
-declare class ConcurrencyGate {
-    private readonly semaphore;
-    private readonly breaker;
-    private onStatsCb;
-    constructor(opts: ConcurrencyGateOptions);
-    /** Hot-reload reconfigurable parameters. Does NOT affect the soft limit
-     *  (which is driven by usage.onChange). Updates breaker/queue/cooldown. */
-    reconfigure(opts: Partial<ConcurrencyGateOptions>): void;
-    onStatsChange(cb: () => void): void;
-    getLimit(): number;
-    getIntentionActive(intention: string): number;
-    getIntentionQueued(intention: string): number;
-    resize(newLimit: number): void;
-    /** Update the hard cap (e.g. from /v1/usage reconciliation).
-     *  Clamps the soft limit down if it now exceeds the new hard cap.
-     *
-     *  Policy: `hard_cap` is a hard grant boundary, NOT a hard real-time ceiling.
-     *  Lowering the cap does NOT evict active permits. Transient over-cap states
-     *  are expected until in-flight permits complete naturally. */
-    setHardCap(newHardCap: number): void;
-    /** Update the persisted soft limit (from /v1/usage). Does NOT change the
-     *  effective limit — that's driven by usage.onChange with priorityLow adjustment. */
-    setSoftLimit(newSoftLimit: number): void;
-    acquire(opts?: {
-        weight?: number;
-        signal?: AbortSignal;
-        onAcquire?: () => void;
-        intention?: string;
-    }): Promise<Permit>;
-    record429(type: "concurrency" | "rate_limit" | "gateway"): void;
-    recordSuccess(): void;
-    getStats(snapshot: UsageSnapshot): GateStats;
-    shutdown(): void;
-    private emitStats;
-}
-
-/** Tristate capability: true = supports vision, false = does not, "via-handoff" = only via handoff. */
-type VisionTristate = true | false | "via-handoff";
-/** Lookup interface for vision-capability queries. Implemented by ModelsClient + ModelInfoClient. */
-interface VisionLookup {
-    getVisionSupport(modelName: string): VisionTristate | null;
-}
-
-/** A Bun WebSocket server instance. */
-interface BunServerWebSocket {
-    send(data: string): number;
-    close(code?: number, reason?: string): void;
-    readyState: number;
-}
-/**
- * Manages the set of connected WebSocket clients and broadcasts messages.
- * Decoupled from the server lifecycle so tests can stub it.
- */
-declare class WsBroadcaster {
-    private clients;
-    /** Add a client to the broadcast set. */
-    add(ws: BunServerWebSocket): void;
-    /** Remove a client from the broadcast set. */
-    remove(ws: BunServerWebSocket): void;
-    /** Broadcast a message to all connected clients. Swallows per-client errors. */
-    broadcast(msg: WsMessage): void;
-    /** Current number of connected clients. */
-    get size(): number;
-}
-
-/** A recorded vision call for debugging and dashboard visibility. */
-interface VisionCallRecord {
-    id: number;
-    timestamp: number;
-    captureId: number | null;
-    model: string;
-    target: string;
-    imageSize: number;
-    imageHash: string | null;
-    status: "ok" | "cache_hit" | "http_error" | "timeout" | "fetch_error" | "parse_error" | "empty" | "skipped" | "aborted";
-    httpStatus: number | null;
-    latencyMs: number;
-    description: string;
-    error: string | null;
-    incomingProtocol: string;
-    upstreamProtocol: string;
-    state: CaptureState;
-}
-
-/** Prepared statement parameter types. */
-interface InsertParams {
-    $method: string;
-    $path: string;
-    $url: string;
-    $rh: string;
-    $rb: string;
-    $rs: number;
-    $st: number;
-    $state: string;
-    $inp: string;
-    $outp: string;
-}
-interface UpdateParams {
-    $id: number;
-    $status: number;
-    $rh: string;
-    $rb: string;
-    $rs: number;
-    $ct: string;
-    $sse: number;
-    $dur: number;
-    $fin: number;
-    $status_source: "upstream" | "gate" | null;
-    $gate_reason: string | null;
-    $usage?: UsageMetrics | null;
-    $model?: string | null;
-}
-interface VisionInsertParams {
-    $method: string;
-    $path: string;
-    $url: string;
-    $rh: string;
-    $rb: string;
-    $rs: number;
-    $status: number | null;
-    $rh2: string;
-    $rb2: string;
-    $rs2: number;
-    $ct: string;
-    $dur: number;
-    $state: CaptureState;
-    $started_at: number;
-    $finished_at: number;
-    $inp: string;
-    $outp: string;
-    $model: string;
-    $parent_capture_id: number | null;
-    $vision_meta: string | null;
-    $provider: string | null;
-    $streaming: number | null;
-    $input_tokens: number | null;
-    $output_tokens: number | null;
-    $cache_creation_tokens: number | null;
-    $cache_read_tokens: number | null;
-    $total_input_tokens: number | null;
-    $total_output_tokens: number | null;
-    $thinking_tokens: number | null;
-    $ttft_ms: number | null;
-    $tps: number | null;
-    $usage_missing: number | null;
-    $metrics_extracted_at: number | null;
-}
-interface VisionUpdateParams {
-    $id: number;
-    $status: number | null;
-    $rh: string;
-    $rb: string;
-    $rs: number;
-    $ct: string;
-    $sse: number;
-    $dur: number;
-    $fin: number;
-    $status_source: "upstream" | "gate" | null;
-    $gate_reason: string | null;
-    $vision_meta: string | null;
-    $model: string | null;
-    $provider: string | null;
-    $streaming: number | null;
-    $input_tokens: number | null;
-    $output_tokens: number | null;
-    $cache_creation_tokens: number | null;
-    $cache_read_tokens: number | null;
-    $total_input_tokens: number | null;
-    $total_output_tokens: number | null;
-    $thinking_tokens: number | null;
-    $ttft_ms: number | null;
-    $tps: number | null;
-    $usage_missing: number | null;
-    $metrics_extracted_at: number | null;
-}
-/** Capture database — wraps a bun:sqlite Database with prepared statements. */
-declare class CaptureDB {
-    private db;
-    private stmtInsert;
-    private stmtUpdate;
-    private stmtDeleteOld;
-    private stmtGet;
-    private stmtList;
-    private stmtCount;
-    private stmtSetState;
-    private stmtUpdateRequestBody;
-    private stmtPerformanceStats;
-    private stmtInsertVision;
-    private stmtUpdateVision;
-    private stmtListVision;
-    private stmtClearVision;
-    private stmtListVisionRecords;
-    private readonly visionDescStore;
-    private rowCount;
-    readonly maxCaptures: number;
-    compressionEnabled: boolean;
-    constructor(config: Pick<ProxyConfig, "dbPath" | "maxCaptures"> & Partial<Pick<ProxyConfig, "compressionEnabled">>);
-    /** Mark captures stuck in "streaming" or "enqueued" from a previous run as "done".
-     *  Called once on startup so the dashboard doesn't show phantom "running" rows. */
-    private sweepStaleCaptures;
-    /** Insert a new capture row and enforce the ring buffer. Returns the new id. */
-    startCapture(params: InsertParams): number;
-    /** Update a capture row with response data. */
-    updateCapture(params: UpdateParams): void;
-    /** Transition a capture's state (enqueued → streaming → done). */
-    setState(id: number, state: "enqueued" | "streaming" | "done"): void;
-    /** Update request_body and request_size after in-flight modification (e.g. vision handoff). */
-    updateRequestBody(id: number, body: string, size: number): void;
-    /** Batch-update multiple captures in a single transaction. */
-    batchUpdate(items: Array<{
-        id: number;
-        res: Omit<UpdateParams, "$id">;
-    }>): Promise<void>;
-    /** Get a single capture by id (full row including bodies). */
-    get(id: number): CaptureRow | null;
-    /** List recent capture summaries (no body data). */
-    list(limit: number): CaptureRow[];
-    /** Compute per-model performance stats entirely in SQL (p10/p50/p95, sums, cached%).
-     *  Uses the v_latest_requests_per_model view + nearest-rank percentiles.
-     *  Returns PerformanceStatsRow[] — no JS post-processing needed. */
-    getPerformanceStats(): PerformanceStatsRow[];
-    /** Delete all captures. */
-    clear(): void;
-    /** Insert a vision-call capture row. Returns the new row id. */
-    insertVisionCapture(params: VisionInsertParams): number;
-    /** Update a vision-call capture row with final response data and mark it done. */
-    updateVisionCapture(params: VisionUpdateParams): void;
-    /** List recent vision-call capture summaries (is_vision=1). */
-    listVisionCaptures(limit: number): CaptureRow[];
-    /** Delete only vision-call captures (is_vision=1). */
-    clearVisionCaptures(): void;
-    /**
-     * Reconstruct VisionCallRecord[] from stored vision-call rows.
-     * The metadata is persisted as JSON in vision_meta by addRecord().
-     */
-    getVisionCallRecords(limit: number): VisionCallRecord[];
-    /** Close the database connection. */
-    close(): void;
-    /** Access the raw bun:sqlite Database (for economics queries). */
-    get rawDb(): Database;
-    /** Insert or update a vision description in the persistent store. */
-    upsertVisionDescription(params: {
-        $key: string;
-        $image_hash: string;
-        $model: string;
-        $prompt_version: number;
-        $description: string;
-        $now: number;
-    }): void;
-    /** Look up a vision description by key. Returns null if not found. */
-    getVisionDescription(key: string): {
-        description: string;
-        created_at: number;
-    } | null;
-    deleteVisionDescription(key: string): void;
-    evictVisionDescriptions(cutoff: number, maxRows: number): number;
-    /** List recent non-expired vision descriptions for cache warming. Returns up to `limit` entries. */
-    listVisionDescriptionsForWarming(limit: number, cutoff: number): Array<{
-        key: string;
-        description: string;
-    }>;
-}
-
-/** Tristate vision support as encoded by the upstream API. */
-type VisionSupport = boolean | "via-handoff";
-
-/** Rich model info from /v1/models/info — faithfully typed from the upstream API. */
-interface ModelInfo {
-    name: string;
-    display_name: string;
-    description: string;
-    base_model: {
-        name: string;
-        provider?: string;
-        family?: string;
-        oss_base?: string;
-    };
-    capabilities: {
-        max_completion_tokens: number;
-        recommended_max_tokens: number;
-        context_window: number;
-        supports_vision: VisionSupport;
-        supports_tools: boolean;
-        reasoning: {
-            supported: boolean;
-            can_disable: boolean;
-            levels: string[];
-            default_level: string | null;
-        };
-    };
-    benchmarks: Record<string, unknown>;
-    weights: {
-        precision: string | undefined;
-        hf_url: string | undefined;
-    };
-    stage?: string;
-    lifecycle?: {
-        playground_start_date?: string;
-    };
-}
-interface ModelEntry {
-    id: string;
-    context_length: number;
-    pricing: {
-        input: number;
-        output: number;
-    } | null;
-    weight: number;
-    info: ModelInfo | null;
-}
-interface ModelsClientOptions {
-    target: string;
-    apiKey?: string | null;
-    refreshMs: number;
-    /** Path appended to target for the model list. */
-    path?: string;
-    /** Path appended to target for the model info endpoint. */
-    infoPath?: string;
-}
-/**
- * Fetches /v1/models on a timer, derives weights, and exposes synchronous
- * lookups. Failures are best-effort: last-known-good is served with ok=false.
- */
-declare class ModelsClient implements VisionLookup {
-    private entries;
-    private fetchedAt;
-    private ok;
-    private timer;
-    private fetching;
-    private onChangeCb;
-    private readonly target;
-    private readonly apiKey;
-    private readonly refreshMs;
-    private readonly path;
-    private readonly infoPath;
-    constructor(opts: ModelsClientOptions);
-    start(): void;
-    stop(): void;
-    /** Subscribe to catalog updates (fired after each successful or failed refresh). */
-    onChange(cb: () => void): void;
-    /** True if the catalog has been successfully fetched at least once. */
-    isReady(): boolean;
-    /** Timestamp (ms) of the last successful fetch, or 0 if never. */
-    lastFetchedAt(): number;
-    /** Current fetch health. */
-    healthy(): boolean;
-    /**
-     * Look up the derived weight for a model id.
-     * Returns DEFAULT_MODEL_WEIGHT if the model is unknown or the catalog
-     * has not been fetched yet.
-     */
-    getWeight(modelId: string): number;
-    getVisionSupport(modelName: string): VisionTristate | null;
-    /** Get a model entry, or null if unknown. */
-    get(modelId: string): ModelEntry | null;
-    /** Snapshot of all known models (sorted by id). */
-    list(): ModelEntry[];
-    /**
-     * Fetch the model list from the upstream API.
-     * Deduplicates concurrent calls. Returns true on success, false on failure.
-     */
-    refresh(): Promise<boolean>;
-    private doFetch;
-}
-
-/** Abstraction over the capture persistence layer used by WriteQueue. */
-interface CaptureStore {
-    updateCapture(params: UpdateParams): void;
-    batchUpdate(items: Array<{
-        id: number;
-        res: Omit<UpdateParams, "$id">;
-    }>): Promise<void>;
-}
-/**
- * Batches response metadata updates and flushes them to the database
- * in a single transaction. Broadcasts WebSocket updates after each flush
- * via the optional onFlush callback.
- */
-declare class WriteQueue {
-    private queue;
-    private flushTimer;
-    private readonly flushIntervalMs;
-    private readonly flushBatch;
-    private readonly queueMaxDepth;
-    private store;
-    private onFlush?;
-    private config;
-    droppedCount: number;
-    constructor(store: CaptureStore, config: QueueConfig & ProtocolConfig, onFlush?: (messages: WsMessage[]) => void);
-    /** Queue a response metadata update for a capture. */
-    queueUpdate(id: number, reqMeta: RequestMeta, res: ResponseMeta): void;
-    get length(): number;
-    get hasTimer(): boolean;
-    /** Flush all queued updates to the database immediately.
-     *  On batchUpdate failure, re-queues the batch at the front so items are
-     *  not permanently lost. The drop path in queueUpdate() will activate
-     *  if the queue overflows after a failed flush. */
-    flushNow(): Promise<void>;
-}
-
-interface RateLimitConfig {
-    limit: number;
-    windowSeconds: number;
-}
-interface RateCheckResult {
-    allowed: boolean;
-    remaining: number;
-    retryAfterSeconds: number | null;
-}
-declare class SlidingWindowRateLimiter {
-    private entries;
-    private runningSum;
-    private readonly limit;
-    private readonly windowMs;
-    constructor(config: RateLimitConfig);
-    /** Record a request with the given weight. Returns whether it was allowed. */
-    check(weight?: number, now?: number): RateCheckResult;
-    /** Check whether a request with the given weight would be allowed, without recording. */
-    peek(weight?: number, now?: number): RateCheckResult;
-    private prune;
-    /** Total weight of entries currently in the window. */
-    count(now?: number): number;
-}
-
-declare class UmansUsageClient {
-    private snapshot;
-    private timer;
-    private fetching;
-    private readonly target;
-    private readonly apiKey;
-    private readonly refreshMs;
-    private onChangeCb;
-    constructor(config: Pick<ProxyConfig, "target" | "umansApiKey" | "usageRefreshMs">);
-    onChange(cb: (s: UsageSnapshot) => void): void;
-    start(): void;
-    stop(): void;
-    getSnapshot(): UsageSnapshot;
-    refresh(): Promise<void>;
-    /** One-shot fetch of /v1/usage to extract concurrency hard_cap + soft_limit.
-     *  Does NOT update live snapshot. */
-    fetchLimitsFromSource(): Promise<{
-        ok: true;
-        hardCap: number;
-        softLimit: number;
-    } | {
-        ok: false;
-        error: string;
-    }>;
-    /** One-shot fetch of /v1/usage to extract requests limits for rate_limit_requests validation.
-     *  Returns {limit, hardCap, windowSeconds} or null if not set (unlimited). */
-    fetchRequestsLimit(): Promise<{
-        ok: true;
-        limit: number | null;
-        hardCap: number | null;
-        windowSeconds: number | null;
-    } | {
-        ok: false;
-        error: string;
-    }>;
-    private applySnapshot;
-    private applyFailedSnapshot;
-}
-
-declare class ConnectionWarmer {
-    private readonly target;
-    private readonly intervalMs;
-    private readonly path;
-    private readonly upstreamProtocol;
-    private timer;
-    private lastTrafficAt;
-    private warmedOnce;
-    constructor(config: Pick<ProxyConfig, "target" | "warmerIntervalMs" | "warmerPath" | "upstreamProtocol">);
-    start(): void;
-    stop(): void;
-    /** Called by the proxy on every upstream request — connection is already warm. */
-    notifyTraffic(): void;
-    private ping;
-}
-
-/**
- * Stamp `ttl` onto Anthropic-style cache_control ephemeral blocks that lack one.
- * Mutates the body in place. Returns the count of blocks stamped (caller
- * re-serializes only when > 0). Non-array system (e.g. a plain string) is
- * skipped safely.
- */
-declare function stampCacheTtl(body: AnthropicBody, ttl: string): number;
-
-/** Options for creating a proxy server. */
-interface CreateProxyServerOptions {
-    /** Override env config. Pass a partial config to merge with defaults.
-     *  Note: `host` is hardcoded to `127.0.0.1` and cannot be overridden. */
-    config?: Omit<Partial<ProxyConfig>, "host">;
-    /** Use an existing CaptureDB instance instead of creating one. */
-    db?: CaptureDB;
-    /** Use an existing WsBroadcaster instead of creating one. */
-    ws?: WsBroadcaster;
-    /** Print the startup banner (default: true). */
-    banner?: boolean;
-}
-/** The running proxy server handle. */
-interface ProxyServer {
-    server: ReturnType<typeof Bun.serve>;
-    db: CaptureDB;
-    ws: WsBroadcaster;
-    queue: WriteQueue;
-    warmer: ConnectionWarmer | null;
-    gate: ConcurrencyGate;
-    usage: UmansUsageClient;
-    models: ModelsClient;
-    rate: SlidingWindowRateLimiter | null;
-    config: ProxyConfig;
-    /** Reload config from disk and apply hot-reloadable fields. */
-    reloadConfig(): ReloadResult;
-    shutdown(): Promise<void>;
-}
-/**
- * Create and start the LLM capture proxy server.
- *
- * This is the main programmatic entry point. It sets up the database,
- * WebSocket broadcaster, write-behind queue, viewer router, and proxy handler,
- * then starts listening on the configured port.
- */
-declare function createProxyServer(options?: CreateProxyServerOptions): ProxyServer;
-
-export { type BreakerState, type BunServerWebSocket, type CaptureConfig, CaptureDB, type CaptureRow, type CaptureSummary, ConcurrencyGate, ConnectionWarmer, type CreateProxyServerOptions, type GateConfig, type GateStats, type ProtocolConfig, type ProxyConfig, type ProxyServer, type QueueConfig, type RawConfig, type RawConfigInput, type ReloadResult, SlidingWindowRateLimiter, type StampConfig, type TimedChunk, UmansUsageClient, type UsageSnapshot, type ValidationResult, WriteQueue, WsBroadcaster, type WsMessage, createProxyServer, ensureConfigFile, loadConfig, readConfigFile, resolveConfigDir, resolveConfigPath, saveConfig, stampCacheTtl, validateConfig };