@juspay/neurolink 9.41.0 → 9.42.1

package/dist/proxy/proxyFetch.js

@@ -4,9 +4,62 @@
  * 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";
+import { createHash } from "node:crypto";
+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
+ */
+function mergeTraceHeaders(input, init) {
+    const existingHeaders = new Headers(input instanceof Request ? input.headers : undefined);
+    if (init?.headers) {
+        const initHeaders = new Headers(init.headers);
+        for (const [key, value] of initHeaders.entries()) {
+            existingHeaders.set(key, value);
+        }
+    }
+    return existingHeaders;
+}
+async function injectTraceContext(input, 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 = mergeTraceHeaders(input, init);
+    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).
@@ -279,6 +332,234 @@ async function createProxyAgent(proxyUrl) {
             throw new Error(`Unsupported proxy protocol: ${parsed.protocol}`);
     }
 }
+function sanitizeProxyUrl(url) {
+    return maskProxyUrl(url) ?? "NOT_SET";
+}
+function getTargetUrl(input) {
+    return typeof input === "string"
+        ? input
+        : input instanceof URL
+            ? input.href
+            : input.url;
+}
+function createDirectFetchHandler() {
+    return async (input, init) => {
+        const enrichedInit = await injectTraceContext(input, init);
+        const reqId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        const startTs = Date.now();
+        const url = getTargetUrl(input);
+        if (logger.shouldLog("debug")) {
+            const { size: bodySize, type: bodyType } = parseBody(enrichedInit?.body);
+            logger.debug("[Observability] HTTP request to LLM provider", {
+                requestId: reqId,
+                url,
+                method: enrichedInit?.method || "POST",
+                bodySize,
+                bodyType,
+            });
+        }
+        try {
+            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", {
+                    requestId: reqId,
+                    url,
+                    status: response.status,
+                    statusText: response.statusText,
+                    durationMs: Date.now() - startTs,
+                    contentLength: responseSize,
+                    hasContent: !!responseBody,
+                    bodyType: responseType,
+                    responseHeaders,
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            logger.debug("[Observability] HTTP request failed", {
+                requestId: reqId,
+                url,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTs,
+            });
+            throw error;
+        }
+    };
+}
+async function executeProxiedFetch(input, init, proxyEnv) {
+    const { httpsProxy, httpProxy, allProxy, socksProxy, noProxy } = proxyEnv;
+    init = await injectTraceContext(input, init);
+    const requestId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    const requestStartTime = Date.now();
+    const targetUrl = getTargetUrl(input);
+    if (logger.shouldLog("debug")) {
+        const { size: bodySize, type: bodyType } = parseBody(init?.body);
+        logger.debug("[Observability] HTTP request to LLM provider", {
+            requestId,
+            url: targetUrl,
+            method: init?.method || "POST",
+            bodySize,
+            bodyType,
+        });
+    }
+    logger.debug(`[Proxy Fetch] ENHANCED REQUEST START`, {
+        requestId,
+        targetUrl,
+        timestamp: new Date().toISOString(),
+        httpProxy: sanitizeProxyUrl(httpProxy),
+        httpsProxy: sanitizeProxyUrl(httpsProxy),
+        allProxy: sanitizeProxyUrl(allProxy),
+        socksProxy: sanitizeProxyUrl(socksProxy),
+        noProxy: noProxy || "NOT_SET",
+        initMethod: init?.method || "GET",
+    });
+    // Clone the request before any proxy attempt so that if the proxy path
+    // consumes the body stream and then fails, the fallback still has an intact
+    // body to send.
+    const requestClone = input instanceof Request ? input.clone() : null;
+    try {
+        const proxyUrl = selectProxyUrl(targetUrl);
+        if (proxyUrl) {
+            const url = new URL(targetUrl);
+            logger.debug(`[Proxy Fetch] 🔗 ENHANCED URL ANALYSIS`, {
+                requestId,
+                targetUrl,
+                urlHostname: url.hostname,
+                urlProtocol: url.protocol,
+                urlPort: url.port,
+                selectedProxyUrl: sanitizeProxyUrl(proxyUrl),
+                timestamp: new Date().toISOString(),
+            });
+            logger.debug(`[Proxy Fetch] 🎯 ENHANCED PROXY AGENT CREATION`, {
+                requestId,
+                proxyUrl: sanitizeProxyUrl(proxyUrl),
+                targetHostname: url.hostname,
+                targetProtocol: url.protocol,
+                aboutToCreateProxyAgent: true,
+                timestamp: new Date().toISOString(),
+            });
+            const globalWithCache = globalThis;
+            if (!globalWithCache.__NL_PROXY_AGENT_CACHE__) {
+                globalWithCache.__NL_PROXY_AGENT_CACHE__ = new Map();
+            }
+            const agentCache = globalWithCache.__NL_PROXY_AGENT_CACHE__;
+            const cacheKey = createHash("sha256")
+                .update(maskProxyUrl(proxyUrl) ?? proxyUrl)
+                .digest("hex");
+            const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
+            agentCache.set(cacheKey, dispatcher);
+            logger.debug(`[Proxy Fetch] ✅ ENHANCED PROXY AGENT CREATED`, {
+                requestId,
+                hasDispatcher: !!dispatcher,
+                dispatcherType: typeof dispatcher,
+                dispatcherConstructor: dispatcher?.constructor?.name || "unknown",
+                timestamp: new Date().toISOString(),
+            });
+            let fetchInput;
+            let fetchInit = { ...init };
+            if (input instanceof Request) {
+                fetchInput = input.url;
+                fetchInit = {
+                    method: input.method,
+                    headers: input.headers,
+                    body: input.body,
+                    ...init,
+                };
+            }
+            else {
+                fetchInput = input;
+            }
+            const undici = await import("undici");
+            const response = await undici.fetch(fetchInput, {
+                ...fetchInit,
+                dispatcher,
+            });
+            if (logger.shouldLog("debug")) {
+                const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
+                logger.debug("[Observability] HTTP response from LLM provider", {
+                    requestId,
+                    url: targetUrl,
+                    status: response?.status,
+                    statusText: response?.statusText,
+                    durationMs: Date.now() - requestStartTime,
+                    contentLength: responseSize,
+                    hasContent: !!responseBody,
+                    bodyType: responseType,
+                    proxied: true,
+                    responseHeaders,
+                });
+            }
+            logger.debug(`[Proxy Fetch] ENHANCED PROXY SUCCESS`, {
+                requestId,
+                responseStatus: response?.status,
+                responseOk: response?.ok,
+                proxyUsed: true,
+                timestamp: new Date().toISOString(),
+            });
+            return response;
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.debug("[Observability] HTTP request failed", {
+            requestId,
+            url: targetUrl,
+            error: errorMessage,
+            durationMs: Date.now() - requestStartTime,
+        });
+        logger.debug(`[Proxy Fetch] ENHANCED ERROR ANALYSIS`, {
+            requestId,
+            error: errorMessage,
+            errorType: error instanceof Error ? error.constructor.name : typeof error,
+            willFallback: true,
+            timestamp: new Date().toISOString(),
+        });
+        logger.warn(`[Proxy Fetch] Enhanced proxy failed (${errorMessage}), falling back to direct connection`);
+    }
+    logger.debug(`[Proxy Fetch] ENHANCED FALLBACK TO STANDARD FETCH`, {
+        requestId,
+        fallbackReason: "No proxy configured or proxy failed",
+        timestamp: new Date().toISOString(),
+    });
+    // Use the cloned request for the fallback so that the body stream is not
+    // already consumed from the proxy attempt above.
+    const fallbackInput = (input instanceof Request ? (requestClone ?? input) : input);
+    try {
+        const response = await fetchWithRetry(fallbackInput, init);
+        if (logger.shouldLog("debug")) {
+            const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
+            logger.debug("[Observability] HTTP response from LLM provider", {
+                requestId,
+                url: targetUrl,
+                status: response.status,
+                statusText: response.statusText,
+                durationMs: Date.now() - requestStartTime,
+                contentLength: responseSize,
+                hasContent: !!responseBody,
+                bodyType: responseType,
+                proxied: false,
+                responseHeaders,
+            });
+        }
+        return response;
+    }
+    catch (fallbackError) {
+        const fallbackMessage = fallbackError instanceof Error
+            ? fallbackError.message
+            : String(fallbackError);
+        logger.debug("[Observability] HTTP request failed", {
+            requestId,
+            url: targetUrl,
+            error: fallbackMessage,
+            durationMs: Date.now() - requestStartTime,
+        });
+        throw fallbackError;
+    }
+}
+function createProxiedFetchHandler(proxyEnv) {
+    return async (input, init) => executeProxiedFetch(input, init, proxyEnv);
+}
 // ==================== ENHANCED PROXY FETCH FUNCTION ====================
 /**
  * Create a proxy-aware fetch function with enhanced capabilities
@@ -291,9 +572,14 @@ export function createProxyFetch() {
     const allProxy = process.env.ALL_PROXY || process.env.all_proxy;
     const socksProxy = process.env.SOCKS_PROXY || process.env.socks_proxy;
     const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+    const proxyEnv = {
+        httpsProxy,
+        httpProxy,
+        allProxy,
+        socksProxy,
+        noProxy,
+    };
     // ENHANCED LOGGING: Capture ALL proxy-related environment variables — credentials redacted
-    // Reuse module-level maskProxyUrl, defaulting to "NOT_SET" for undefined values
-    const sanitizeProxyUrl = (url) => maskProxyUrl(url) ?? "NOT_SET";
     if (logger.shouldLog("debug")) {
         const allProxyRelatedEnvVars = Object.keys(process.env)
             .filter((key) => key.toLowerCase().includes("proxy"))
@@ -316,52 +602,7 @@ export function createProxyFetch() {
     // If no proxy configured, return instrumented standard fetch
     if (!httpsProxy && !httpProxy && !allProxy && !socksProxy) {
         logger.debug("[Proxy Fetch] No proxy environment variables found - using standard fetch");
-        return async (input, init) => {
-            const reqId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-            const startTs = Date.now();
-            const url = typeof input === "string"
-                ? input
-                : input instanceof URL
-                    ? input.href
-                    : input.url;
-            if (logger.shouldLog("debug")) {
-                const { size: bodySize, type: bodyType } = parseBody(init?.body);
-                logger.debug("[Observability] HTTP request to LLM provider", {
-                    requestId: reqId,
-                    url,
-                    method: init?.method || "POST",
-                    bodySize,
-                    bodyType,
-                });
-            }
-            try {
-                const response = await fetchWithRetry(input, init);
-                if (logger.shouldLog("debug")) {
-                    const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                    logger.debug("[Observability] HTTP response from LLM provider", {
-                        requestId: reqId,
-                        url,
-                        status: response.status,
-                        statusText: response.statusText,
-                        durationMs: Date.now() - startTs,
-                        contentLength: responseSize,
-                        hasContent: !!responseBody,
-                        bodyType: responseType,
-                        responseHeaders,
-                    });
-                }
-                return response;
-            }
-            catch (error) {
-                logger.debug("[Observability] HTTP request failed", {
-                    requestId: reqId,
-                    url,
-                    error: error instanceof Error ? error.message : String(error),
-                    durationMs: Date.now() - startTs,
-                });
-                throw error;
-            }
-        };
+        return createDirectFetchHandler();
     }
     logger.debug(`[Proxy Fetch] Configuring enhanced proxy with multiple protocol support`);
     logger.debug(`[Proxy Fetch] HTTP_PROXY: ${sanitizeProxyUrl(httpProxy)}`);
@@ -369,174 +610,7 @@ export function createProxyFetch() {
     logger.debug(`[Proxy Fetch] ALL_PROXY: ${sanitizeProxyUrl(allProxy)}`);
     logger.debug(`[Proxy Fetch] SOCKS_PROXY: ${sanitizeProxyUrl(socksProxy)}`);
     logger.debug(`[Proxy Fetch] NO_PROXY: ${noProxy || "not set"}`);
-    // Return enhanced proxy-aware fetch function
-    return async (input, init) => {
-        const requestId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-        const requestStartTime = Date.now();
-        // Determine target URL
-        const targetUrl = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input.url;
-        // Request logging with sensitive header redaction — gated behind debug check
-        if (logger.shouldLog("debug")) {
-            const { size: bodySize, type: bodyType } = parseBody(init?.body);
-            logger.debug("[Observability] HTTP request to LLM provider", {
-                requestId,
-                url: targetUrl,
-                method: init?.method || "POST",
-                bodySize,
-                bodyType,
-            });
-        }
-        logger.debug(`[Proxy Fetch] ENHANCED REQUEST START`, {
-            requestId,
-            targetUrl,
-            timestamp: new Date().toISOString(),
-            httpProxy: sanitizeProxyUrl(httpProxy),
-            httpsProxy: sanitizeProxyUrl(httpsProxy),
-            allProxy: sanitizeProxyUrl(allProxy),
-            socksProxy: sanitizeProxyUrl(socksProxy),
-            initMethod: init?.method || "GET",
-        });
-        try {
-            // Enhanced proxy selection with NO_PROXY bypass and multiple protocols
-            const proxyUrl = selectProxyUrl(targetUrl);
-            if (proxyUrl) {
-                const url = new URL(targetUrl);
-                const sanitizedProxy = sanitizeProxyUrl(proxyUrl);
-                logger.debug(`[Proxy Fetch] 🔗 ENHANCED URL ANALYSIS`, {
-                    requestId,
-                    targetUrl,
-                    urlHostname: url.hostname,
-                    urlProtocol: url.protocol,
-                    urlPort: url.port,
-                    selectedProxyUrl: sanitizedProxy,
-                    timestamp: new Date().toISOString(),
-                });
-                logger.debug(`[Proxy Fetch] 🎯 ENHANCED PROXY AGENT CREATION`, {
-                    requestId,
-                    proxyUrl: sanitizedProxy,
-                    targetHostname: url.hostname,
-                    targetProtocol: url.protocol,
-                    aboutToCreateProxyAgent: true,
-                    timestamp: new Date().toISOString(),
-                });
-                // Create/reuse proxy agent (HTTP/HTTPS/SOCKS)
-                const agentCache = globalThis.__NL_PROXY_AGENT_CACHE__ ??
-                    (globalThis.__NL_PROXY_AGENT_CACHE__ = new Map());
-                const cacheKey = maskProxyUrl(proxyUrl) ?? proxyUrl; // mask credentials in cache key
-                const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
-                agentCache.set(cacheKey, dispatcher);
-                logger.debug(`[Proxy Fetch] ✅ ENHANCED PROXY AGENT CREATED`, {
-                    requestId,
-                    hasDispatcher: !!dispatcher,
-                    dispatcherType: typeof dispatcher,
-                    dispatcherConstructor: dispatcher?.constructor?.name || "unknown",
-                    timestamp: new Date().toISOString(),
-                });
-                // Handle Request objects by extracting URL and merging properties
-                let fetchInput;
-                let fetchInit = { ...init };
-                if (input instanceof Request) {
-                    fetchInput = input.url;
-                    fetchInit = {
-                        method: input.method,
-                        headers: input.headers,
-                        body: input.body,
-                        ...init, // Allow init to override Request properties
-                    };
-                }
-                else {
-                    fetchInput = input;
-                }
-                // Use undici fetch with enhanced dispatcher (supports HTTP/HTTPS/SOCKS)
-                const undici = await import("undici");
-                const response = await undici.fetch(fetchInput, {
-                    ...fetchInit,
-                    dispatcher: dispatcher,
-                });
-                if (logger.shouldLog("debug")) {
-                    const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                    logger.debug("[Observability] HTTP response from LLM provider", {
-                        requestId,
-                        url: targetUrl,
-                        status: response?.status,
-                        statusText: response?.statusText,
-                        durationMs: Date.now() - requestStartTime,
-                        contentLength: responseSize,
-                        hasContent: !!responseBody,
-                        bodyType: responseType,
-                        proxied: true,
-                        responseHeaders,
-                    });
-                }
-                logger.debug(`[Proxy Fetch] ENHANCED PROXY SUCCESS`, {
-                    requestId,
-                    responseStatus: response?.status,
-                    responseOk: response?.ok,
-                    proxyUsed: true,
-                    timestamp: new Date().toISOString(),
-                });
-                return response;
-            }
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.debug("[Observability] HTTP request failed", {
-                requestId,
-                url: targetUrl,
-                error: errorMessage,
-                durationMs: Date.now() - requestStartTime,
-            });
-            logger.debug(`[Proxy Fetch] ENHANCED ERROR ANALYSIS`, {
-                requestId,
-                error: errorMessage,
-                errorType: error instanceof Error ? error.constructor.name : typeof error,
-                willFallback: true,
-                timestamp: new Date().toISOString(),
-            });
-            logger.warn(`[Proxy Fetch] Enhanced proxy failed (${errorMessage}), falling back to direct connection`);
-        }
-        // Fallback to standard fetch
-        logger.debug(`[Proxy Fetch] ENHANCED FALLBACK TO STANDARD FETCH`, {
-            requestId,
-            fallbackReason: "No proxy configured or proxy failed",
-            timestamp: new Date().toISOString(),
-        });
-        try {
-            const response = await fetchWithRetry(input, init);
-            if (logger.shouldLog("debug")) {
-                const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                logger.debug("[Observability] HTTP response from LLM provider", {
-                    requestId,
-                    url: targetUrl,
-                    status: response.status,
-                    statusText: response.statusText,
-                    durationMs: Date.now() - requestStartTime,
-                    contentLength: responseSize,
-                    hasContent: !!responseBody,
-                    bodyType: responseType,
-                    proxied: false,
-                    responseHeaders,
-                });
-            }
-            return response;
-        }
-        catch (fallbackError) {
-            const fallbackMessage = fallbackError instanceof Error
-                ? fallbackError.message
-                : String(fallbackError);
-            logger.debug("[Observability] HTTP request failed", {
-                requestId,
-                url: targetUrl,
-                error: fallbackMessage,
-                durationMs: Date.now() - requestStartTime,
-            });
-            throw fallbackError;
-        }
-    };
+    return createProxiedFetchHandler(proxyEnv);
 }
 /**
  * Mask credentials in a proxy URL for safe logging/reporting.

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, };