@juspay/neurolink 9.40.0 → 9.42.0

package/dist/proxy/oauthFetch.js

@@ -10,63 +10,12 @@
  *
  * @module proxy/oauthFetch
  */
-import { CLAUDE_CLI_USER_AGENT, MCP_TOOL_PREFIX, } from "../auth/anthropicOAuth.js";
+import { CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, MCP_TOOL_PREFIX, buildStableClaudeCodeBillingHeader, getOrCreateClaudeCodeIdentity, } from "../auth/anthropicOAuth.js";
 import { logger } from "../utils/logger.js";
-import { randomBytes, randomUUID } from "crypto";
 // Re-export constants for consumers that previously imported them alongside
 // the function from `providers/anthropic.ts`.
 export { CLAUDE_CLI_USER_AGENT, MCP_TOOL_PREFIX };
 // ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/** Cache fake user IDs per token prefix (1-hour TTL, max 1000 entries). */
-const userIdCache = new Map();
-const USER_ID_CACHE_TTL_MS = 3_600_000; // 1 hour
-const USER_ID_CACHE_MAX_SIZE = 1_000;
-/** Evict expired entries and enforce max size (LRU-approximation via insertion order). */
-function evictUserIdCache() {
-    const now = Date.now();
-    for (const [key, entry] of userIdCache) {
-        if (entry.expires <= now) {
-            userIdCache.delete(key);
-        }
-    }
-    // If still over capacity, remove oldest entries (Map preserves insertion order)
-    if (userIdCache.size > USER_ID_CACHE_MAX_SIZE) {
-        const excess = userIdCache.size - USER_ID_CACHE_MAX_SIZE;
-        let removed = 0;
-        for (const key of userIdCache.keys()) {
-            if (removed >= excess) {
-                break;
-            }
-            userIdCache.delete(key);
-            removed++;
-        }
-    }
-}
-function getOrCreateUserId(tokenPrefix) {
-    evictUserIdCache();
-    const cached = userIdCache.get(tokenPrefix);
-    if (cached && cached.expires > Date.now()) {
-        return cached.id;
-    }
-    const hex = randomBytes(32).toString("hex");
-    const id = `user_${hex}_account_${randomUUID()}_session_${randomUUID()}`;
-    userIdCache.set(tokenPrefix, {
-        id,
-        expires: Date.now() + USER_ID_CACHE_TTL_MS,
-    });
-    return id;
-}
-/** Compute a short hex hash of a string using Web Crypto (SHA-256). */
-async function shortSha256(data) {
-    const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data));
-    return Array.from(new Uint8Array(buf))
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("")
-        .substring(0, 5);
-}
-// ---------------------------------------------------------------------------
 // Main factory
 // ---------------------------------------------------------------------------
 /**
@@ -77,7 +26,7 @@ async function shortSha256(data) {
  * - Sets User-Agent to Claude CLI
  * - Adds ?beta=true query parameter to /v1/messages
  * - Injects billing header & agent block into system prompt
- * - Injects fake user ID into metadata
+ * - Injects Claude-Code-shaped user ID into metadata
  * - Adds Stainless SDK headers for fingerprint matching
  * - Disables thinking when tool_choice is forced
  *
@@ -154,7 +103,9 @@ export function createOAuthFetch(getToken, includeOptionalBetas = true, enableMc
         // Only add our betas if not already present in client's headers
         if (!skipBodyTransform) {
             // Direct NeuroLink usage — set full beta list
-            requiredBetas.push("claude-code-20250219", ...(includeOptionalBetas ? ["interleaved-thinking-2025-05-14"] : []), "prompt-caching-scope-2026-01-05");
+            requiredBetas.push(...(includeOptionalBetas
+                ? CLAUDE_CODE_OAUTH_BETAS.filter((beta) => beta !== "oauth-2025-04-20")
+                : []));
         }
         const allBetas = [...new Set([...existingBetas, ...requiredBetas])];
         const mergedBetas = allBetas.join(",");
@@ -165,6 +116,8 @@ export function createOAuthFetch(getToken, includeOptionalBetas = true, enableMc
         if (!skipBodyTransform) {
             // Only override user-agent for direct NeuroLink usage
             requestHeaders.set("user-agent", CLAUDE_CLI_USER_AGENT);
+            requestHeaders.set("anthropic-version", "2023-06-01");
+            requestHeaders.set("accept", "application/json");
         }
         requestHeaders.delete("x-api-key");
         // Identity / fingerprint headers (skip in passthrough — client sends its own)
@@ -248,41 +201,67 @@ export function createOAuthFetch(getToken, includeOptionalBetas = true, enableMc
                     parsed.tool_choice?.type === "tool") {
                     delete parsed.thinking;
                 }
-                // --- Inject billing header + agent block into system prompt ----
-                const version = "2.1.63";
-                const randomHex = Array.from(crypto.getRandomValues(new Uint8Array(2)))
-                    .map((b) => b.toString(16).padStart(2, "0"))
-                    .join("")
-                    .substring(0, 3);
-                const bodyString = JSON.stringify(parsed);
-                const cch = await shortSha256(bodyString);
-                const billingBlock = {
-                    type: "text",
-                    text: `x-anthropic-billing-header: cc_version=${version}.${randomHex}; cc_entrypoint=cli; cch=${cch};`,
-                };
                 const agentBlock = {
                     type: "text",
                     text: "You are a Claude agent, built on Anthropic's Claude Agent SDK.",
                 };
-                // Normalise `system` to an array and prepend billing + agent blocks
+                // Normalise `system` to an array and APPEND billing + agent blocks.
+                // IMPORTANT: We append (not prepend) to preserve the client's cache
+                // prefix chain. Anthropic's prompt caching uses prefix matching — if
+                // we insert anything before the client's system blocks, we invalidate
+                // all cached content (tools, system prompt, message history).
+                //
+                // Claude Code sends a billing block with a `cch=<hash>` value that
+                // changes on every request. We remove any existing billing/agent
+                // blocks from their positions and always append our stable
+                // Claude-Code-shaped versions at the end.
                 if (parsed.system) {
                     if (typeof parsed.system === "string") {
                         parsed.system = [{ type: "text", text: parsed.system }];
                     }
                     if (Array.isArray(parsed.system)) {
-                        parsed.system = [billingBlock, agentBlock, ...parsed.system];
+                        // Find and remove existing billing/agent blocks from wherever
+                        // the client placed them (typically at system[0])
+                        const billingIdx = parsed.system.findIndex((b) => typeof b.text === "string" &&
+                            b.text.includes("x-anthropic-billing-header"));
+                        const agentIdx = parsed.system.findIndex((b) => typeof b.text === "string" &&
+                            b.text.includes("Claude Agent SDK"));
+                        const billingBlock = {
+                            type: "text",
+                            text: buildStableClaudeCodeBillingHeader(parsed.system[billingIdx]?.text),
+                        };
+                        // Remove in reverse index order so indices stay valid
+                        const indicesToRemove = [billingIdx, agentIdx]
+                            .filter((i) => i >= 0)
+                            .sort((a, b) => b - a);
+                        for (const idx of indicesToRemove) {
+                            parsed.system.splice(idx, 1);
+                        }
+                        // Always append deterministic billing + agent blocks at the end
+                        parsed.system = [...parsed.system, billingBlock, agentBlock];
                     }
                 }
                 else {
+                    const billingBlock = {
+                        type: "text",
+                        text: buildStableClaudeCodeBillingHeader(),
+                    };
                     parsed.system = [billingBlock, agentBlock];
                 }
-                // --- Inject fake user ID into metadata -------------------------
-                const token = getToken();
-                const tokenPrefix = token.substring(0, Math.min(20, token.length));
+                // --- Inject Claude-Code-shaped identity into metadata ----------
+                // Prefer existing metadata.user_id (refresh-stable) over the access
+                // token prefix, which changes on every token rotation.
+                const stableId = parsed.metadata?.user_id ??
+                    getToken().substring(0, Math.min(20, getToken().length));
+                const identity = getOrCreateClaudeCodeIdentity(stableId, {
+                    existingUserId: parsed.metadata?.user_id,
+                    preferredSessionId: requestHeaders.get("x-claude-code-session-id") ?? undefined,
+                });
                 parsed.metadata = {
                     ...parsed.metadata,
-                    user_id: getOrCreateUserId(tokenPrefix),
+                    user_id: identity.metadataUserId,
                 };
+                requestHeaders.set("x-claude-code-session-id", identity.sessionId);
                 body = JSON.stringify(parsed);
             }
             catch {
@@ -292,6 +271,20 @@ export function createOAuthFetch(getToken, includeOptionalBetas = true, enableMc
         // Remove any inherited content-length — the body may have been transformed
         // above, so the original length is stale. Let fetch/undici recalculate it.
         requestHeaders.delete("content-length");
+        // Inject OTel traceparent so the proxy can link to this trace
+        try {
+            const { propagation: otelPropagation, context: otelContext } = await import("@opentelemetry/api");
+            const carrier = {};
+            otelPropagation.inject(otelContext.active(), carrier);
+            for (const [key, value] of Object.entries(carrier)) {
+                if (!requestHeaders.has(key)) {
+                    requestHeaders.set(key, value);
+                }
+            }
+        }
+        catch {
+            // OTel not available — skip silently
+        }
         // Make the request
         const response = await fetch(requestUrl?.toString() ||
             (input instanceof Request ? input.url : input.toString()), {

package/dist/proxy/proxyConfig.js

@@ -198,33 +198,47 @@ export function validateProxyConfig(config) {
     if (cfg.version !== undefined && typeof cfg.version !== "number") {
         errors.push(`"version" must be a number, got ${typeof cfg.version}`);
     }
-    if (!cfg.accounts ||
-        typeof cfg.accounts !== "object" ||
-        Array.isArray(cfg.accounts)) {
+    const hasAccounts = !!cfg.accounts &&
+        typeof cfg.accounts === "object" &&
+        !Array.isArray(cfg.accounts);
+    const hasRouting = !!cfg.routing &&
+        typeof cfg.routing === "object" &&
+        !Array.isArray(cfg.routing);
+    if (cfg.routing !== undefined && !hasRouting) {
+        errors.push('"routing" must be an object');
+        return errors;
+    }
+    if (!hasAccounts && !hasRouting) {
+        errors.push('Config must contain at least one of "accounts" or "routing"');
+        return errors;
+    }
+    if (cfg.accounts !== undefined && !hasAccounts) {
         errors.push('"accounts" must be an object mapping provider names to account arrays');
         return errors;
     }
-    const accounts = cfg.accounts;
-    let totalAccounts = 0;
-    for (const [provider, list] of Object.entries(accounts)) {
-        if (!Array.isArray(list)) {
-            errors.push(`accounts.${provider} must be an array, got ${typeof list}`);
-            continue;
-        }
-        totalAccounts += list.length;
-        for (let i = 0; i < list.length; i++) {
-            const acct = list[i];
-            if (!acct || typeof acct !== "object") {
-                errors.push(`accounts.${provider}[${i}] must be an object`);
+    if (hasAccounts) {
+        const accounts = cfg.accounts;
+        let totalAccounts = 0;
+        for (const [provider, list] of Object.entries(accounts)) {
+            if (!Array.isArray(list)) {
+                errors.push(`accounts.${provider} must be an array, got ${typeof list}`);
                 continue;
             }
-            if (typeof acct.apiKey !== "string" || acct.apiKey.length === 0) {
-                errors.push(`accounts.${provider}[${i}].apiKey is required and must be a non-empty string`);
+            totalAccounts += list.length;
+            for (let i = 0; i < list.length; i++) {
+                const acct = list[i];
+                if (!acct || typeof acct !== "object") {
+                    errors.push(`accounts.${provider}[${i}] must be an object`);
+                    continue;
+                }
+                if (typeof acct.apiKey !== "string" || acct.apiKey.length === 0) {
+                    errors.push(`accounts.${provider}[${i}].apiKey is required and must be a non-empty string`);
+                }
             }
         }
-    }
-    if (totalAccounts === 0) {
-        errors.push('"accounts" must contain at least one account');
+        if (totalAccounts === 0 && !hasRouting) {
+            errors.push('"accounts" must contain at least one account');
+        }
     }
     return errors;
 }
@@ -422,8 +436,10 @@ export async function loadProxyConfig(filePath, options = {}) {
     const raw = parsed;
     const accounts = {};
     const rawAccounts = raw.accounts;
-    for (const [provider, list] of Object.entries(rawAccounts)) {
-        accounts[provider] = list.map((item) => applyAccountDefaults(item));
+    if (rawAccounts && typeof rawAccounts === "object") {
+        for (const [provider, list] of Object.entries(rawAccounts)) {
+            accounts[provider] = list.map((item) => applyAccountDefaults(item));
+        }
     }
     // 7. Extract routing config
     const routing = parseRoutingConfig(raw.routing);
@@ -483,8 +499,12 @@ export async function parseProxyConfigString(content, options = {}) {
     const raw = parsed;
     const accounts = {};
     const rawAccounts = raw.accounts;
-    for (const [provider, list] of Object.entries(rawAccounts)) {
-        accounts[provider] = list.map((item) => applyAccountDefaults(item));
+    if (rawAccounts &&
+        typeof rawAccounts === "object" &&
+        !Array.isArray(rawAccounts)) {
+        for (const [provider, list] of Object.entries(rawAccounts)) {
+            accounts[provider] = list.map((item) => applyAccountDefaults(item));
+        }
     }
     const routing = parseRoutingConfig(raw.routing);
     const cloaking = validateCloakingConfig(raw.cloaking);

package/dist/proxy/proxyEnv.d.ts

@@ -0,0 +1,19 @@
+export type ProxyEnvSource = "cli" | "environment" | "default" | "none";
+export type ProxyEnvResolution = {
+    path?: string;
+    source: ProxyEnvSource;
+    required: boolean;
+};
+export type ProxyEnvLoadResult = {
+    loaded: boolean;
+    path?: string;
+    source: ProxyEnvSource;
+};
+type ProxyEnvOptions = {
+    explicitEnvFile?: string;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+};
+export declare function resolveProxyEnvFile(options?: ProxyEnvOptions): ProxyEnvResolution;
+export declare function loadProxyEnvFile(options?: ProxyEnvOptions): Promise<ProxyEnvLoadResult>;
+export {};

package/dist/proxy/proxyEnv.js

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+export function resolveProxyEnvFile(options = {}) {
+    const env = options.env ?? process.env;
+    const homeDir = options.homeDir ?? homedir();
+    if (options.explicitEnvFile?.trim()) {
+        return {
+            path: resolve(options.explicitEnvFile.trim()),
+            source: "cli",
+            required: true,
+        };
+    }
+    if (env.NEUROLINK_ENV_FILE?.trim()) {
+        return {
+            path: resolve(env.NEUROLINK_ENV_FILE.trim()),
+            source: "environment",
+            required: true,
+        };
+    }
+    const defaultPath = resolve(homeDir, ".neurolink", ".env");
+    if (existsSync(defaultPath)) {
+        return {
+            path: defaultPath,
+            source: "default",
+            required: false,
+        };
+    }
+    return {
+        source: "none",
+        required: false,
+    };
+}
+export async function loadProxyEnvFile(options = {}) {
+    const resolution = resolveProxyEnvFile(options);
+    const env = options.env ?? process.env;
+    if (!resolution.path) {
+        return {
+            loaded: false,
+            source: "none",
+        };
+    }
+    if (!existsSync(resolution.path)) {
+        if (resolution.required) {
+            throw new Error(`Proxy env file not found: ${resolution.path}`);
+        }
+        return {
+            loaded: false,
+            source: resolution.source,
+        };
+    }
+    try {
+        const { config } = await import("dotenv");
+        const result = config({
+            path: resolution.path,
+            override: true,
+            quiet: true,
+        });
+        if (result.error) {
+            throw result.error;
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to load proxy env file ${resolution.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    env.NEUROLINK_ENV_FILE = resolution.path;
+    return {
+        loaded: true,
+        path: resolution.path,
+        source: resolution.source,
+    };
+}

package/dist/proxy/proxyFetch.js

@@ -4,9 +4,51 @@
  * Lightweight implementation extracted from research of major proxy packages
  */
 import { logger } from "../utils/logger.js";
-import { SpanStatusCode } from "@opentelemetry/api";
+import { SpanStatusCode, propagation, context } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { shouldBypassProxy } from "./utils/noProxyUtils.js";
+async function getLangfuseContext() {
+    try {
+        // Dynamic import to avoid hard dependency — getLangfuseContext is only
+        // available when the observability module is loaded.
+        const mod = await import("../services/server/ai/observability/instrumentation.js");
+        return mod.getLangfuseContext?.();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Inject OTel trace context (traceparent/tracestate) and NeuroLink session context
+ * into outgoing request headers. This enables:
+ * - The NeuroLink proxy to link proxy spans as children of the calling SDK's trace
+ * - Conversation-level session/user attribution on proxy spans
+ */
+async function injectTraceContext(init) {
+    const carrier = {};
+    propagation.inject(context.active(), carrier);
+    // Also inject NeuroLink session context from Langfuse AsyncLocalStorage
+    const langfuseContext = await getLangfuseContext();
+    if (langfuseContext?.sessionId) {
+        carrier["x-neurolink-session-id"] = langfuseContext.sessionId;
+    }
+    if (langfuseContext?.userId) {
+        carrier["x-neurolink-user-id"] = langfuseContext.userId;
+    }
+    if (langfuseContext?.conversationId) {
+        carrier["x-neurolink-conversation-id"] = langfuseContext.conversationId;
+    }
+    if (Object.keys(carrier).length === 0) {
+        return init ?? {};
+    }
+    const existingHeaders = new Headers(init?.headers);
+    for (const [key, value] of Object.entries(carrier)) {
+        if (!existingHeaders.has(key)) {
+            existingHeaders.set(key, value);
+        }
+    }
+    return { ...init, headers: existingHeaders };
+}
 const fetchTracer = tracers.http;
 /**
  * Extract hostname from a URL string for safe logging (no auth tokens or paths).
@@ -317,6 +359,8 @@ export function createProxyFetch() {
     if (!httpsProxy && !httpProxy && !allProxy && !socksProxy) {
         logger.debug("[Proxy Fetch] No proxy environment variables found - using standard fetch");
         return async (input, init) => {
+            // Inject OTel traceparent so the proxy can link to this trace
+            const enrichedInit = await injectTraceContext(init);
             const reqId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
             const startTs = Date.now();
             const url = typeof input === "string"
@@ -325,17 +369,17 @@ export function createProxyFetch() {
                     ? input.href
                     : input.url;
             if (logger.shouldLog("debug")) {
-                const { size: bodySize, type: bodyType } = parseBody(init?.body);
+                const { size: bodySize, type: bodyType } = parseBody(enrichedInit?.body);
                 logger.debug("[Observability] HTTP request to LLM provider", {
                     requestId: reqId,
                     url,
-                    method: init?.method || "POST",
+                    method: enrichedInit?.method || "POST",
                     bodySize,
                     bodyType,
                 });
             }
             try {
-                const response = await fetchWithRetry(input, init);
+                const response = await fetchWithRetry(input, enrichedInit);
                 if (logger.shouldLog("debug")) {
                     const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
                     logger.debug("[Observability] HTTP response from LLM provider", {
@@ -371,6 +415,8 @@ export function createProxyFetch() {
     logger.debug(`[Proxy Fetch] NO_PROXY: ${noProxy || "not set"}`);
     // Return enhanced proxy-aware fetch function
     return async (input, init) => {
+        // Inject OTel traceparent so the proxy can link to this trace
+        init = await injectTraceContext(init);
         const requestId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
         const requestStartTime = Date.now();
         // Determine target URL

package/dist/proxy/proxyTracer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Proxy Request Tracer
+ *
+ * Creates and manages OTel spans for the proxy request lifecycle.
+ * Provides a clean API for claudeProxyRoutes to trace each phase:
+ *   receive -> account_selection -> upstream (per retry) -> stream -> end
+ *
+ * Uses the existing instrumentation infrastructure:
+ * - getTracer() from instrumentation.ts for span creation
+ * - setLangfuseContext() for Langfuse enrichment
+ * - OtelBridge for context propagation to/from upstream
+ * - SpanAttributes from spanTypes.ts for attribute naming
+ * - calculateCost() from pricing.ts for cost tracking
+ * - TelemetryService for metrics recording
+ */
+import { type Span } from "@opentelemetry/api";
+type ProxyRequestContext = {
+    requestId: string;
+    method: string;
+    path: string;
+    model: string;
+    stream: boolean;
+    toolCount: number;
+    sessionId?: string;
+    userAgent?: string;
+    clientApp?: string;
+};
+type AccountSelectionContext = {
+    strategy: string;
+    accountsTotal: number;
+    accountsHealthy: number;
+    selectedAccount: string;
+    accountType: string;
+    rateLimitBefore5h?: number;
+    rateLimitBefore7d?: number;
+};
+type UpstreamAttemptContext = {
+    attempt: number;
+    account: string;
+    polyfillHeaders: boolean;
+    polyfillBody: boolean;
+    upstreamUrl: string;
+};
+type UsageContext = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    reasoningTokens?: number;
+    rateLimitAfter5h?: number;
+    rateLimitAfter7d?: number;
+};
+declare class ProxyTracer {
+    private readonly rootSpan;
+    private readonly proxyTracer;
+    private readonly bridge;
+    private readonly requestId;
+    private readonly model;
+    private readonly startTime;
+    private readonly isStream;
+    private accountEmail?;
+    private usage?;
+    private mode;
+    private constructor();
+    /**
+     * Create a root span for a proxy request and set Langfuse context.
+     *
+     * If the incoming request carries a `traceparent` header, the root span
+     * will be linked to the caller's trace via OtelBridge.extractContext().
+     */
+    static startRequest(ctx: ProxyRequestContext, incomingHeaders?: Record<string, string>): ProxyTracer;
+    /** Span covering the initial request receive and parse phase. */
+    startReceive(): Span;
+    /** Span covering account selection logic (fill-first / round-robin). */
+    startAccountSelection(): Span;
+    /** Span covering a single upstream attempt. One per retry. */
+    startUpstreamAttempt(ctx: UpstreamAttemptContext): Span;
+    /** Span covering the SSE stream relay phase. */
+    startStream(): Span;
+    /** Record account selection outcome on the root span. */
+    setAccountSelection(ctx: AccountSelectionContext): void;
+    /** Record token usage and cost on the root span. */
+    setUsage(ctx: UsageContext): void;
+    /** Record an error on the root span. */
+    setError(errorType: string, errorMessage: string): void;
+    /** Record whether the request was handled in full or passthrough mode. */
+    setMode(mode: "full" | "passthrough" | "passthrough-cli"): void;
+    /**
+     * Record that the proxy substituted a different model than was requested.
+     * Sets span attributes and increments the substitution metric counter.
+     */
+    setModelSubstitution(requestedModel: string, actualModel: string): void;
+    /** Log the incoming client request body (redacted). */
+    logRequestBody(body: string): void;
+    /** Log the incoming client request headers (redacted). */
+    logRequestHeaders(headers: Record<string, string>): void;
+    /** Log the upstream request body (redacted, as sent to Anthropic). */
+    logUpstreamRequestBody(body: string): void;
+    /** Log the upstream request headers (redacted). */
+    logUpstreamRequestHeaders(headers: Record<string, string>): void;
+    /** Log the upstream response headers (redacted). */
+    logUpstreamResponseHeaders(headers: Record<string, string>): void;
+    /** Log the upstream response body (redacted). */
+    logUpstreamResponseBody(body: string): void;
+    /** Log SSE stream events (each event has type, timestamp, data). */
+    logStreamEvents(events: Array<{
+        type: string;
+        timestamp: number;
+        data: string;
+    }>): void;
+    /** Record an upstream retry attempt. */
+    recordRetry(account: string, reason: string): void;
+    /** Record request and/or response body sizes for bandwidth tracking. */
+    recordBodySizes(requestBytes?: number, responseBytes?: number): void;
+    /** Return the OTel trace/span IDs for this request (for log correlation). */
+    getTraceContext(): {
+        traceId: string;
+        spanId: string;
+    };
+    /** Return the captured usage (set by setUsage). */
+    getUsage(): UsageContext | undefined;
+    /** End the root span with final HTTP status and duration, and emit OTEL metrics. */
+    end(responseStatus: number, durationMs: number): void;
+    /** Record metrics via TelemetryService (call after setUsage). */
+    recordMetrics(): void;
+    /**
+     * Get trace context headers for propagation to the upstream Anthropic request.
+     * Injects the current trace's `traceparent` / `tracestate` into a new header map.
+     */
+    getTraceHeaders(): Record<string, string>;
+}
+export { ProxyTracer };
+export type { ProxyRequestContext, AccountSelectionContext, UpstreamAttemptContext, UsageContext, };