@juspay/neurolink 9.10.0 → 9.11.0

package/dist/proxy/proxyFetch.js

@@ -6,36 +6,118 @@
 import { logger } from "../utils/logger.js";
 import { shouldBypassProxy } from "./utils/noProxyUtils.js";
 /**
- * Mask credentials in proxy URLs for secure logging
- * Replaces user:password@ with [CREDENTIALS_MASKED]@
+ * Retry-aware fetch wrapper for transient network errors (ECONNRESET, ETIMEDOUT, socket hang up).
+ * Protects all LLM API calls and token refreshes that go through createProxyFetch().
  */
-function maskProxyCredentials(proxyUrl) {
-    if (!proxyUrl || proxyUrl === "NOT_SET") {
-        return proxyUrl || "NOT_SET";
+async function fetchWithRetry(url, init, maxRetries = 3, baseDelay = 500) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fetch(url, init);
+        }
+        catch (error) {
+            const err = error;
+            const isRetryable = err?.code === "ECONNRESET" ||
+                err?.code === "ETIMEDOUT" ||
+                err?.message?.includes("socket hang up") ||
+                err?.message?.includes("network socket disconnected");
+            if (!isRetryable || attempt === maxRetries) {
+                throw error;
+            }
+            const delay = baseDelay * Math.pow(2, attempt);
+            logger.debug(`[fetchWithRetry] Transient error (${err?.code || err?.message}), retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
+            await new Promise((r) => setTimeout(r, delay));
+        }
     }
-    try {
-        // Handle URLs with credentials: http://user:password@proxy:port
-        const credentialPattern = /(:\/\/)([^@:]+):([^@]+)@/;
-        if (credentialPattern.test(proxyUrl)) {
-            return proxyUrl.replace(credentialPattern, "$1[CREDENTIALS_MASKED]@");
+    throw new Error("fetchWithRetry exhausted"); // unreachable
+}
+/**
+ * Parse request body to readable format for debug logging
+ */
+function parseBody(body) {
+    if (!body) {
+        return { parsed: null, size: 0, type: "empty" };
+    }
+    if (typeof body === "string") {
+        try {
+            return { parsed: JSON.parse(body), size: body.length, type: "json" };
+        }
+        catch {
+            return { parsed: body, size: body.length, type: "text" };
         }
-        // Return original URL if no credentials found
-        return proxyUrl;
     }
-    catch {
-        // If URL parsing fails, still mask potential credentials pattern
-        return proxyUrl.replace(/(:\/\/)([^@:]+):([^@]+)@/, "$1[CREDENTIALS_MASKED]@");
+    if (body instanceof ArrayBuffer) {
+        return {
+            parsed: "[ArrayBuffer]",
+            size: body.byteLength,
+            type: "arraybuffer",
+        };
     }
+    if (body instanceof Uint8Array) {
+        return { parsed: "[Uint8Array]", size: body.length, type: "uint8array" };
+    }
+    return { parsed: "[Stream]", size: -1, type: "stream" };
 }
 /**
- * Mask all proxy credentials in an environment variables object
+ * Sensitive header names whose values should be redacted in logs
+ */
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "x-api-key",
+    "api-key",
+    "x-goog-api-key",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+]);
+/**
+ * Extract all headers as plain object with sensitive values redacted
  */
-function maskProxyEnvVars(envVars) {
-    const masked = {};
-    for (const [key, value] of Object.entries(envVars)) {
-        masked[key] = maskProxyCredentials(value);
+function getAllHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    const entries = headers instanceof Headers
+        ? [...headers.entries()]
+        : Array.isArray(headers)
+            ? headers
+            : Object.entries(headers);
+    return Object.fromEntries(entries.map(([key, value]) => SENSITIVE_HEADERS.has(key.toLowerCase())
+        ? [key, `${value.substring(0, 4)}***`]
+        : [key, value]));
+}
+/**
+ * Clone response and read body + headers for debug logging
+ */
+async function readResponseBody(response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = SENSITIVE_HEADERS.has(key.toLowerCase())
+            ? `${value.substring(0, 4)}***`
+            : value;
+    });
+    try {
+        const cloned = response.clone();
+        const text = await cloned.text();
+        try {
+            return {
+                parsed: JSON.parse(text),
+                size: text.length,
+                type: "json",
+                headers,
+            };
+        }
+        catch {
+            return { parsed: text, size: text.length, type: "text", headers };
+        }
+    }
+    catch {
+        return {
+            parsed: "[unable to read body]",
+            size: -1,
+            type: "error",
+            headers,
+        };
     }
-    return masked;
 }
 // ==================== LIGHTWEIGHT PROXY IMPLEMENTATIONS ====================
 // ParsedProxyConfig interface moved to ../types/utilities.js
@@ -61,11 +143,22 @@ function parseProxyUrl(proxyUrl) {
         return config;
     }
     catch (error) {
+        // Sanitize proxy URL to avoid leaking credentials in logs/errors
+        let safeUrl;
+        try {
+            const u = new URL(proxyUrl);
+            u.username = "";
+            u.password = "";
+            safeUrl = u.toString();
+        }
+        catch {
+            safeUrl = "[invalid-url]";
+        }
         logger.error("[Proxy] Failed to parse proxy URL", {
-            proxyUrl: maskProxyCredentials(proxyUrl),
+            proxyUrl: safeUrl,
             error,
         });
-        throw new Error(`Invalid proxy URL: ${maskProxyCredentials(proxyUrl)}`);
+        throw new Error(`Invalid proxy URL: ${safeUrl}`);
     }
 }
 /**
@@ -160,55 +253,117 @@ 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;
-    // ENHANCED LOGGING: Capture ALL enhanced proxy-related environment variables with credential masking
-    logger.debug("[Proxy Fetch] 🔍 ENHANCED_PROXY_ENV_DETECTION", {
-        // Enhanced proxy environment variables (credentials masked)
-        httpProxy: maskProxyCredentials(httpProxy || "NOT_SET"),
-        httpsProxy: maskProxyCredentials(httpsProxy || "NOT_SET"),
-        allProxy: maskProxyCredentials(allProxy || "NOT_SET"),
-        socksProxy: maskProxyCredentials(socksProxy || "NOT_SET"),
-        noProxy: noProxy || "NOT_SET", // NO_PROXY doesn't contain credentials
-        // Legacy variables for compatibility (credentials masked)
-        originalNodejsHttpProxy: maskProxyCredentials(process.env.nodejs_http_proxy || "NOT_SET"),
-        originalNodejsHttpsProxy: maskProxyCredentials(process.env.nodejs_https_proxy || "NOT_SET"),
-        // All potential proxy-related environment variables (credentials masked)
-        allProxyRelatedEnvVars: maskProxyEnvVars(Object.keys(process.env)
+    // 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"))
             .reduce((acc, key) => {
-            acc[key] = process.env[key] || "NOT_SET";
+            const val = process.env[key] || "NOT_SET";
+            acc[key] =
+                key.toLowerCase() === "no_proxy" ? val : sanitizeProxyUrl(val);
             return acc;
-        }, {})),
-        message: "Enhanced proxy environment detection with SOCKS, authentication, and NO_PROXY support (credentials masked for security)",
-    });
-    // If no proxy configured, return standard fetch
+        }, {});
+        logger.debug("[Proxy Fetch] ENHANCED_PROXY_ENV_DETECTION", {
+            httpProxy: sanitizeProxyUrl(httpProxy),
+            httpsProxy: sanitizeProxyUrl(httpsProxy),
+            allProxy: sanitizeProxyUrl(allProxy),
+            socksProxy: sanitizeProxyUrl(socksProxy),
+            noProxy: noProxy || "NOT_SET",
+            allProxyRelatedEnvVars,
+            message: "Enhanced proxy environment detection — credentials redacted",
+        });
+    }
+    // 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 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 { parsed: requestBody, size: bodySize, type: bodyType, } = parseBody(init?.body);
+                logger.debug("[Observability] HTTP request to LLM provider", {
+                    requestId: reqId,
+                    url,
+                    method: init?.method || "POST",
+                    headers: getAllHeaders(init?.headers),
+                    body: requestBody,
+                    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,
+                        headers: responseHeaders,
+                        body: responseBody,
+                        bodySize: responseSize,
+                        bodyType: responseType,
+                    });
+                }
+                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;
+            }
+        };
     }
     logger.debug(`[Proxy Fetch] Configuring enhanced proxy with multiple protocol support`);
-    logger.debug(`[Proxy Fetch] HTTP_PROXY: ${maskProxyCredentials(httpProxy || "not set")}`);
-    logger.debug(`[Proxy Fetch] HTTPS_PROXY: ${maskProxyCredentials(httpsProxy || "not set")}`);
-    logger.debug(`[Proxy Fetch] ALL_PROXY: ${maskProxyCredentials(allProxy || "not set")}`);
-    logger.debug(`[Proxy Fetch] SOCKS_PROXY: ${maskProxyCredentials(socksProxy || "not set")}`);
+    logger.debug(`[Proxy Fetch] HTTP_PROXY: ${sanitizeProxyUrl(httpProxy)}`);
+    logger.debug(`[Proxy Fetch] HTTPS_PROXY: ${sanitizeProxyUrl(httpsProxy)}`);
+    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;
-        logger.debug(`[Proxy Fetch] 🚀 ENHANCED REQUEST START`, {
+        // Request logging with sensitive header redaction — gated behind debug check
+        if (logger.shouldLog("debug")) {
+            const { parsed: requestBody, size: bodySize, type: bodyType, } = parseBody(init?.body);
+            logger.debug("[Observability] HTTP request to LLM provider", {
+                requestId,
+                url: targetUrl,
+                method: init?.method || "POST",
+                headers: getAllHeaders(init?.headers),
+                body: requestBody,
+                bodySize,
+                bodyType,
+            });
+        }
+        logger.debug(`[Proxy Fetch] ENHANCED REQUEST START`, {
             requestId,
             targetUrl,
             timestamp: new Date().toISOString(),
-            httpProxy: httpProxy || "NOT_SET",
-            httpsProxy: httpsProxy || "NOT_SET",
-            allProxy: allProxy || "NOT_SET",
-            socksProxy: socksProxy || "NOT_SET",
-            initHeaders: init?.headers || "NO_HEADERS",
+            httpProxy: sanitizeProxyUrl(httpProxy),
+            httpsProxy: sanitizeProxyUrl(httpsProxy),
+            allProxy: sanitizeProxyUrl(allProxy),
+            socksProxy: sanitizeProxyUrl(socksProxy),
             initMethod: init?.method || "GET",
         });
         try {
@@ -216,18 +371,19 @@ export function createProxyFetch() {
             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: maskProxyCredentials(proxyUrl), // Hide credentials in logs
+                    selectedProxyUrl: sanitizedProxy,
                     timestamp: new Date().toISOString(),
                 });
                 logger.debug(`[Proxy Fetch] 🎯 ENHANCED PROXY AGENT CREATION`, {
                     requestId,
-                    proxyUrl: maskProxyCredentials(proxyUrl), // Hide credentials
+                    proxyUrl: sanitizedProxy,
                     targetHostname: url.hostname,
                     targetProtocol: url.protocol,
                     aboutToCreateProxyAgent: true,
@@ -236,8 +392,9 @@ export function createProxyFetch() {
                 // Create/reuse proxy agent (HTTP/HTTPS/SOCKS)
                 const agentCache = globalThis.__NL_PROXY_AGENT_CACHE__ ??
                     (globalThis.__NL_PROXY_AGENT_CACHE__ = new Map());
-                const dispatcher = agentCache.get(proxyUrl) || (await createProxyAgent(proxyUrl));
-                agentCache.set(proxyUrl, dispatcher);
+                const cacheKey = maskProxyUrl(proxyUrl) ?? proxyUrl; // credentials stripped for key
+                const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
+                agentCache.set(cacheKey, dispatcher);
                 logger.debug(`[Proxy Fetch] ✅ ENHANCED PROXY AGENT CREATED`, {
                     requestId,
                     hasDispatcher: !!dispatcher,
@@ -266,20 +423,40 @@ export function createProxyFetch() {
                     ...fetchInit,
                     dispatcher: dispatcher,
                 });
-                logger.debug(`[Proxy Fetch] 🎉 ENHANCED PROXY SUCCESS`, {
+                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,
+                        headers: responseHeaders,
+                        body: responseBody,
+                        bodySize: responseSize,
+                        bodyType: responseType,
+                        proxied: true,
+                    });
+                }
+                logger.debug(`[Proxy Fetch] ENHANCED PROXY SUCCESS`, {
                     requestId,
                     responseStatus: response?.status,
                     responseOk: response?.ok,
                     proxyUsed: true,
                     timestamp: new Date().toISOString(),
                 });
-                logger.debug(`[Proxy Fetch] ✅ Request proxied successfully via enhanced proxy`);
                 return response;
             }
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.debug(`[Proxy Fetch] 💥 ENHANCED ERROR ANALYSIS`, {
+            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,
@@ -289,14 +466,63 @@ export function createProxyFetch() {
             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`, {
+        logger.debug(`[Proxy Fetch] ENHANCED FALLBACK TO STANDARD FETCH`, {
             requestId,
             fallbackReason: "No proxy configured or proxy failed",
             timestamp: new Date().toISOString(),
         });
-        return fetch(input, init);
+        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,
+                    headers: responseHeaders,
+                    body: responseBody,
+                    bodySize: responseSize,
+                    bodyType: responseType,
+                    proxied: false,
+                });
+            }
+            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;
+        }
     };
 }
+/**
+ * Mask credentials in a proxy URL for safe logging/reporting.
+ */
+function maskProxyUrl(url) {
+    if (!url) {
+        return null;
+    }
+    try {
+        const u = new URL(url);
+        if (u.username || u.password) {
+            u.username = "***";
+            u.password = "***";
+        }
+        return u.toString();
+    }
+    catch {
+        return "[invalid-url]";
+    }
+}
 /**
  * Get enhanced proxy status information
  */
@@ -308,10 +534,10 @@ export function getProxyStatus() {
     const noProxy = process.env.NO_PROXY || process.env.no_proxy;
     return {
         enabled: !!(httpsProxy || httpProxy || allProxy || socksProxy),
-        httpProxy: httpProxy || null,
-        httpsProxy: httpsProxy || null,
-        allProxy: allProxy || null,
-        socksProxy: socksProxy || null,
+        httpProxy: maskProxyUrl(httpProxy),
+        httpsProxy: maskProxyUrl(httpsProxy),
+        allProxy: maskProxyUrl(allProxy),
+        socksProxy: maskProxyUrl(socksProxy),
         noProxy: noProxy || null,
         method: "enhanced-proxy-agent",
         capabilities: [

package/dist/services/server/ai/observability/instrumentation.js

@@ -394,11 +394,20 @@ export function initializeOpenTelemetry(config) {
                     const provider = globalProvider;
                     // Add ContextEnricher for trace name enrichment
                     provider.addSpanProcessor(new ContextEnricher());
-                    // Also add LangfuseSpanProcessor so traces are sent to Langfuse
-                    provider.addSpanProcessor(langfuseProcessor);
+                    // Only add LangfuseSpanProcessor if the host has not already registered one.
+                    // When skipLangfuseSpanProcessor is true, the host (e.g. Curator) already
+                    // registers its own LangfuseSpanProcessor via a DeferredSpanProcessor, so
+                    // adding another one here would cause duplicate trace exports to Langfuse.
+                    const skipLangfuse = config.skipLangfuseSpanProcessor === true;
+                    if (!skipLangfuse) {
+                        provider.addSpanProcessor(langfuseProcessor);
+                    }
                     logger.info(`${LOG_PREFIX} Auto-registered processors with global TracerProvider`, {
-                        processors: ["ContextEnricher", "LangfuseSpanProcessor"],
+                        processors: skipLangfuse
+                            ? ["ContextEnricher"]
+                            : ["ContextEnricher", "LangfuseSpanProcessor"],
                         reason: "External provider mode with auto-registration",
+                        skippedLangfuseSpanProcessor: skipLangfuse,
                     });
                 }
                 else {

package/dist/telemetry/telemetryService.d.ts

@@ -17,6 +17,7 @@ export declare class TelemetryService {
     private aiRequestDuration?;
     private aiTokensUsed?;
     private aiProviderErrors?;
+    private aiCostUsd?;
     private mcpToolCalls?;
     private connectionCounter?;
     private responseTimeHistogram?;
@@ -32,7 +33,7 @@ export declare class TelemetryService {
     private initializeMetrics;
     initialize(): Promise<void>;
     traceAIRequest<T>(provider: string, operation: () => Promise<T>, operationType?: string): Promise<T>;
-    recordAIRequest(provider: string, model: string, tokens: number, duration: number): void;
+    recordAIRequest(provider: string, model: string, tokens: number, duration: number, cost?: number): void;
     recordAIError(provider: string, error: Error): void;
     recordMCPToolCall(toolName: string, duration: number, success: boolean): void;
     recordConnection(type: "websocket" | "sse" | "http"): void;

package/dist/telemetry/telemetryService.js

@@ -16,6 +16,7 @@ export class TelemetryService {
     aiRequestDuration;
     aiTokensUsed;
     aiProviderErrors;
+    aiCostUsd;
     mcpToolCalls;
     connectionCounter;
     responseTimeHistogram;
@@ -79,6 +80,9 @@ export class TelemetryService {
         this.aiTokensUsed = this.meter.createCounter("ai_tokens_used_total", {
             description: "Total number of AI tokens used",
         });
+        this.aiCostUsd = this.meter.createCounter("ai_cost_usd_total", {
+            description: "Total accumulated AI cost in USD",
+        });
         this.aiProviderErrors = this.meter.createCounter("ai_provider_errors_total", {
             description: "Total number of AI provider errors",
         });
@@ -136,7 +140,7 @@ export class TelemetryService {
         }
     }
     // Metrics Recording (NO-OP when disabled)
-    recordAIRequest(provider, model, tokens, duration) {
+    recordAIRequest(provider, model, tokens, duration, cost) {
         // Track runtime metrics
         this.requestCount++;
         this.totalResponseTime += duration;
@@ -148,6 +152,9 @@ export class TelemetryService {
         this.aiRequestCounter.add(1, labels);
         this.aiRequestDuration?.record(duration, labels);
         this.aiTokensUsed?.add(tokens, labels);
+        if (cost !== undefined && Number.isFinite(cost) && cost > 0) {
+            this.aiCostUsd?.add(cost, labels);
+        }
     }
     recordAIError(provider, error) {
         // Track runtime metrics

package/dist/types/contextTypes.d.ts

@@ -343,7 +343,9 @@ export type BudgetFileInput = {
     /** Optional file type hint for type-aware token estimation */
     fileType?: string;
 };
-/** Options for tool output truncation. */
+/**
+ * @deprecated Use ToolOutputPreviewOptions instead.
+ */
 export type TruncateOptions = {
     maxBytes?: number;
     maxLines?: number;
@@ -351,13 +353,35 @@ export type TruncateOptions = {
     saveToDisk?: boolean;
     saveDir?: string;
 };
-/** Result of tool output truncation. */
+/**
+ * @deprecated Use ToolOutputPreviewResult instead.
+ */
 export type TruncateResult = {
     content: string;
     truncated: boolean;
     savedPath?: string;
     originalSize: number;
 };
+/** Options for tool output preview generation. */
+export type ToolOutputPreviewOptions = {
+    /** Maximum bytes for the preview (default: 50KB) */
+    maxBytes?: number;
+    /** Maximum lines for the preview (default: 2000) */
+    maxLines?: number;
+    /** Fraction of preview budget allocated to the head (default: 0.25) */
+    headRatio?: number;
+    /** Fraction of preview budget allocated to the tail (default: 0.75) */
+    tailRatio?: number;
+};
+/** Result of tool output preview generation. */
+export type ToolOutputPreviewResult = {
+    /** The preview string (or full output if under limits) */
+    preview: string;
+    /** Whether truncation was applied */
+    truncated: boolean;
+    /** Original byte size of the full output */
+    originalSize: number;
+};
 /** Result of tool pair repair. */
 export type RepairResult = {
     repaired: boolean;