@juspay/neurolink 9.54.5 → 9.54.7

package/dist/client/sseClient.js

@@ -7,7 +7,10 @@
  *
  * @module @neurolink/client/sseClient
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { logger } from "../utils/logger.js";
+import { withClientSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // SSE Client Implementation
 // =============================================================================
@@ -69,6 +72,32 @@ export class NeuroLinkSSE {
      * Stream from an endpoint using SSE
      */
     async stream(path, options = {}, callbacks = {}) {
+        return withClientSpan({
+            name: "neurolink.client.sse.stream",
+            tracer: tracers.http,
+            attributes: {
+                "http.method": options.body ? "POST" : "GET",
+                "http.route": path,
+                "http.url": this.buildUrl(path),
+                "sse.auto_reconnect": this.config.autoReconnect,
+                "sse.native_event_source": this.config.useNativeEventSource,
+            },
+        }, async (span) => {
+            // Wrap onError callback so the span is marked failed on stream errors
+            const wrappedCallbacks = {
+                ...callbacks,
+                onError: (error) => {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error?.message ?? "SSE stream error",
+                    });
+                    callbacks.onError?.(error);
+                },
+            };
+            return this._streamInternal(path, options, wrappedCallbacks);
+        });
+    }
+    async _streamInternal(path, options = {}, callbacks = {}) {
         const url = this.buildUrl(path);
         const isGetRequest = !options.body;
         // Use native EventSource for GET requests when configured and available

package/dist/client/streamingClient.d.ts

@@ -49,6 +49,7 @@ export declare class SSEClient {
         body?: unknown;
         headers?: Record<string, string>;
     }): Promise<void>;
+    private _connectSSE;
     /**
      * Disconnect from SSE endpoint
      */
@@ -131,6 +132,7 @@ export declare class WebSocketStreamingClient {
      * Connect to WebSocket server
      */
     connect(): Promise<void>;
+    private _connectWS;
     /**
      * Disconnect from WebSocket server
      */

package/dist/client/streamingClient.js

@@ -8,6 +8,8 @@
  */
 import { logger } from "../utils/logger.js";
 import { combineSignals, sleep } from "./httpClient.js";
+import { withClientSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // Types
 // =============================================================================
@@ -61,6 +63,16 @@ export class SSEClient {
      * Connect to SSE endpoint
      */
     async connect(requestOptions = {}) {
+        return withClientSpan({
+            name: "neurolink.client.streaming.sse.connect",
+            tracer: tracers.http,
+            attributes: {
+                "http.url": this.url,
+                "http.method": requestOptions.body ? "POST" : "GET",
+            },
+        }, async () => this._connectSSE(requestOptions));
+    }
+    async _connectSSE(requestOptions = {}) {
         if (this.state === "connected" || this.state === "connecting") {
             return;
         }
@@ -393,6 +405,13 @@ export class WebSocketStreamingClient {
      * Connect to WebSocket server
      */
     async connect() {
+        return withClientSpan({
+            name: "neurolink.client.streaming.ws.connect",
+            tracer: tracers.http,
+            attributes: { "http.url": this.options.url },
+        }, async () => this._connectWS());
+    }
+    async _connectWS() {
         if (typeof WebSocket === "undefined") {
             throw new Error("WebSocket is not available. Please use a polyfill for non-browser environments.");
         }

package/dist/client/wsClient.d.ts

@@ -7,7 +7,7 @@
  *
  * @module @neurolink/client/wsClient
  */
-import type { ClientStreamCallbacks, ClientStreamEvent as StreamEvent, ClientStreamResult as StreamResult, ClientApiError, WebSocketEventHandlers, ClientClientWebSocketState, ClientWebSocketMessage, ClientWebSocketConfig } from "../types/index.js";
+import type { ClientStreamCallbacks, WebSocketEventHandlers, ClientClientWebSocketState, ClientWebSocketMessage, ClientWebSocketConfig } from "../types/index.js";
 /**
  * WebSocket streaming client for NeuroLink
  *
@@ -43,6 +43,12 @@ export declare class NeuroLinkWebSocket {
     private eventHandlers;
     private subscriptions;
     private pendingAuth;
+    /**
+     * Active OTel span for the current WebSocket connection lifecycle.
+     * Created at connect() and ended on close/error so we capture connection
+     * lifetime, reconnect counts, and error attribution in Langfuse.
+     */
+    private connectionSpan;
     /**
      * Local flag to suppress reconnection during an explicit disconnect().
      * Unlike mutating config.autoReconnect, this preserves the user's
@@ -119,4 +125,3 @@ export declare class NeuroLinkWebSocket {
  * ```
  */
 export declare function createWebSocketClient(config: ClientWebSocketConfig): NeuroLinkWebSocket;
-export type { ClientStreamCallbacks, StreamEvent, StreamResult, ClientApiError, };

package/dist/client/wsClient.js

@@ -7,6 +7,8 @@
  *
  * @module @neurolink/client/wsClient
  */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // WebSocket Client
 // =============================================================================
@@ -45,6 +47,12 @@ export class NeuroLinkWebSocket {
     eventHandlers = {};
     subscriptions = new Map();
     pendingAuth = false;
+    /**
+     * Active OTel span for the current WebSocket connection lifecycle.
+     * Created at connect() and ended on close/error so we capture connection
+     * lifetime, reconnect counts, and error attribution in Langfuse.
+     */
+    connectionSpan = null;
     /**
      * Local flag to suppress reconnection during an explicit disconnect().
      * Unlike mutating config.autoReconnect, this preserves the user's
@@ -89,6 +97,28 @@ export class NeuroLinkWebSocket {
         this.disconnectRequested = false;
         this.eventHandlers = handlers ?? {};
         this.setState("connecting");
+        // End any orphaned span from a prior connect() attempt (e.g., re-entrant call
+        // while a previous attempt was still connecting).
+        if (this.connectionSpan) {
+            this.connectionSpan.setAttribute("ws.superseded", true);
+            this.connectionSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: "Connection attempt superseded by new connect() call",
+            });
+            this.connectionSpan.end();
+            this.connectionSpan = null;
+        }
+        // Start an OTel span that tracks the lifetime of this connection attempt.
+        // Ended in onclose/onerror/disconnect so metrics capture connection
+        // duration and error attribution.
+        this.connectionSpan = tracers.http.startSpan("neurolink.client.ws.connect", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "http.url": this.config.baseUrl,
+                "ws.auto_reconnect": this.config.autoReconnect,
+                "ws.reconnect_attempt": this.reconnectAttempts,
+            },
+        });
         // Build WebSocket URL (credentials are sent via headers, not query params,
         // to avoid leaking secrets in server logs, browser history, and HTTP referers)
         const url = new URL(this.config.baseUrl);
@@ -107,15 +137,25 @@ export class NeuroLinkWebSocket {
         // credentials are sent as the first message after the connection opens.
         const isNode = typeof globalThis.process !== "undefined" &&
             typeof globalThis.process.versions?.node === "string";
-        if (isNode && Object.keys(authHeaders).length > 0) {
-            // The `ws` npm package accepts a second `options` object with a `headers`
-            // property.  The DOM WebSocket type does not model this, so we cast
-            // through `unknown` to satisfy TypeScript while remaining correct at
-            // runtime under Node.js.
-            this.ws = new WebSocket(url.toString(), { headers: authHeaders });
+        try {
+            if (isNode && Object.keys(authHeaders).length > 0) {
+                this.ws = new WebSocket(url.toString(), { headers: authHeaders });
+            }
+            else {
+                this.ws = new WebSocket(url.toString());
+            }
         }
-        else {
-            this.ws = new WebSocket(url.toString());
+        catch (error) {
+            if (this.connectionSpan) {
+                this.connectionSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                this.connectionSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                this.connectionSpan.end();
+                this.connectionSpan = null;
+            }
+            throw error;
         }
         this.pendingAuth = !isNode && (!!this.config.apiKey || !!this.config.token);
         this.setupEventListeners();
@@ -134,6 +174,15 @@ export class NeuroLinkWebSocket {
             this.ws = null;
         }
         this.setState("disconnected");
+        // Let onclose finalize the span — it fires from ws.close(1000,...) and
+        // has the close code context.  We only end here if ws is already null
+        // (e.g. connect was never called) to avoid leaking.
+        if (this.connectionSpan && !this.ws) {
+            this.connectionSpan.setAttribute("ws.close_reason", "client_disconnect");
+            this.connectionSpan.setStatus({ code: SpanStatusCode.OK });
+            this.connectionSpan.end();
+            this.connectionSpan = null;
+        }
     }
     /**
      * Send a message through WebSocket
@@ -144,7 +193,7 @@ export class NeuroLinkWebSocket {
         }
         else {
             // Queue message for when connected
-            if (this.messageQueue.length < this.config.queueSize) {
+            if (this.messageQueue.length < (this.config.queueSize ?? 100)) {
                 this.messageQueue.push(message);
             }
         }
@@ -199,6 +248,9 @@ export class NeuroLinkWebSocket {
         this.ws.onopen = () => {
             this.setState("connected");
             this.reconnectAttempts = 0;
+            if (this.connectionSpan) {
+                this.connectionSpan.setAttribute("ws.connected", true);
+            }
             // In browser environments, send credentials as the first message
             // since the browser WebSocket API does not support custom headers.
             if (this.pendingAuth && this.ws) {
@@ -223,6 +275,24 @@ export class NeuroLinkWebSocket {
             this.setState("disconnected");
             this.stopHeartbeat();
             this.eventHandlers.onClose?.(event.code, event.reason);
+            if (this.connectionSpan) {
+                this.connectionSpan.setAttribute("ws.close_code", event.code);
+                if (event.reason) {
+                    this.connectionSpan.setAttribute("ws.close_reason", event.reason);
+                }
+                // 1000 = normal closure; other codes are abnormal.
+                if (event.code === 1000) {
+                    this.connectionSpan.setStatus({ code: SpanStatusCode.OK });
+                }
+                else {
+                    this.connectionSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: `WebSocket closed with code ${event.code}${event.reason ? `: ${event.reason}` : ""}`,
+                    });
+                }
+                this.connectionSpan.end();
+                this.connectionSpan = null;
+            }
             // Only attempt reconnection when auto-reconnect is enabled AND this
             // was not an intentional disconnect (code 1000 or explicit call).
             if (this.config.autoReconnect &&
@@ -235,6 +305,16 @@ export class NeuroLinkWebSocket {
             this.setState("error");
             const error = new Error("WebSocket connection error");
             this.eventHandlers.onError?.(error);
+            if (this.connectionSpan) {
+                this.connectionSpan.recordException(error);
+                this.connectionSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                // Do not end here — onclose will fire next and end the span with
+                // the precise close code. Keeping the span open until close gives
+                // us the full connection lifetime on Langfuse.
+            }
         };
         this.ws.onmessage = (event) => {
             try {
@@ -303,7 +383,7 @@ export class NeuroLinkWebSocket {
             if (this.isConnected()) {
                 this.send({ type: "ping" });
             }
-        }, this.config.heartbeatInterval);
+        }, this.config.heartbeatInterval ?? 30000);
     }
     stopHeartbeat() {
         if (this.heartbeatTimer) {

package/dist/context/budgetChecker.js

@@ -9,6 +9,7 @@
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { estimateMessagesTokens, estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
+import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /** Default compaction threshold (80% of available input) */
 const DEFAULT_COMPACTION_THRESHOLD = 0.8;
 /** Estimated tokens per tool definition */
@@ -21,9 +22,10 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
  * against available input space.
  */
 export function checkContextBudget(params) {
+    const { traceId, parentSpanId } = getActiveTraceContext();
     const span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.budgetCheck", {
         "context.operation": "budgetCheck",
-    });
+    }, parentSpanId, traceId);
     const startTime = Date.now();
     try {
         const { provider, model, maxTokens, systemPrompt, conversationMessages, currentPrompt, toolDefinitions, fileAttachments, compactionThreshold = DEFAULT_COMPACTION_THRESHOLD, } = params;

package/dist/context/contextCompactor.js

@@ -12,6 +12,9 @@ import { estimateMessagesTokens } from "../utils/tokenEstimation.js";
 import { logger } from "../utils/logger.js";
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
+import { getActiveTraceContext } from "../telemetry/traceContext.js";
+import { withSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
 import { deduplicateFileReads } from "./stages/fileReadDeduplicator.js";
 import { truncateWithSlidingWindow } from "./stages/slidingWindowTruncator.js";
@@ -39,166 +42,183 @@ export class ContextCompactor {
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
     async compact(messages, targetTokens, memoryConfig, requestId) {
-        let span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.compact", {
-            "context.operation": "compact",
-            "context.targetTokens": targetTokens,
-        });
-        const spanStartTime = Date.now();
-        try {
-            const provider = this.config.provider || undefined;
-            const tokensBefore = estimateMessagesTokens(messages, provider);
-            const stagesUsed = [];
-            let currentMessages = [...messages];
-            logger.info("[Compaction] Starting", {
-                requestId,
-                estimatedTokens: tokensBefore,
-                budgetTokens: targetTokens,
-            });
-            // Stage 1: Tool Output Pruning
-            if (this.config.enablePrune &&
-                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                const pruneResult = pruneToolOutputs(currentMessages, {
-                    protectTokens: this.config.pruneProtectTokens,
-                    minimumSavings: this.config.pruneMinimumSavings,
-                    protectedTools: this.config.pruneProtectedTools,
-                    provider,
-                });
-                if (pruneResult.pruned) {
-                    currentMessages = pruneResult.messages;
-                    stagesUsed.push("prune");
-                }
-                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                logger.info("[Compaction] Stage 1 (prune)", {
+        return withSpan({
+            name: "neurolink.context.compact",
+            tracer: tracers.context,
+            attributes: {
+                "context.target_tokens": targetTokens,
+                "context.message_count": messages.length,
+            },
+        }, async () => {
+            const { traceId, parentSpanId } = getActiveTraceContext();
+            let span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.compact", {
+                "context.operation": "compact",
+                "context.targetTokens": targetTokens,
+            }, parentSpanId, traceId);
+            const spanStartTime = Date.now();
+            try {
+                const provider = this.config.provider || undefined;
+                const tokensBefore = estimateMessagesTokens(messages, provider);
+                const stagesUsed = [];
+                let currentMessages = [...messages];
+                logger.info("[Compaction] Starting", {
                     requestId,
-                    ran: pruneResult.pruned,
-                    tokensBefore: stageTokensBefore,
-                    tokensAfter: stageTokensAfter,
-                    saved: stageTokensBefore - stageTokensAfter,
+                    estimatedTokens: tokensBefore,
+                    budgetTokens: targetTokens,
                 });
-            }
-            // Stage 2: File Read Deduplication
-            if (this.config.enableDeduplicate &&
-                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                const dedupResult = deduplicateFileReads(currentMessages);
-                if (dedupResult.deduplicated) {
-                    currentMessages = dedupResult.messages;
-                    stagesUsed.push("deduplicate");
-                }
-                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                logger.info("[Compaction] Stage 2 (deduplicate)", {
-                    requestId,
-                    ran: dedupResult.deduplicated,
-                    tokensBefore: stageTokensBefore,
-                    tokensAfter: stageTokensAfter,
-                    saved: stageTokensBefore - stageTokensAfter,
-                });
-            }
-            // Stage 3: LLM Summarization
-            if (this.config.enableSummarize &&
-                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                try {
-                    const summarizeResult = await withTimeout(summarizeMessages(currentMessages, {
-                        provider: this.config.summarizationProvider,
-                        model: this.config.summarizationModel,
-                        keepRecentRatio: this.config.keepRecentRatio,
-                        memoryConfig,
-                        targetTokens,
-                    }), 120_000, "LLM summarization timed out after 120s");
-                    if (summarizeResult.summarized) {
-                        currentMessages = summarizeResult.messages;
-                        stagesUsed.push("summarize");
+                // Stage 1: Tool Output Pruning
+                if (this.config.enablePrune &&
+                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                    const pruneResult = pruneToolOutputs(currentMessages, {
+                        protectTokens: this.config.pruneProtectTokens,
+                        minimumSavings: this.config.pruneMinimumSavings,
+                        protectedTools: this.config.pruneProtectedTools,
+                        provider,
+                    });
+                    if (pruneResult.pruned) {
+                        currentMessages = pruneResult.messages;
+                        stagesUsed.push("prune");
                     }
                     const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                    logger.info("[Compaction] Stage 3 (summarize)", {
+                    logger.info("[Compaction] Stage 1 (prune)", {
                         requestId,
-                        ran: summarizeResult.summarized,
+                        ran: pruneResult.pruned,
                         tokensBefore: stageTokensBefore,
                         tokensAfter: stageTokensAfter,
                         saved: stageTokensBefore - stageTokensAfter,
                     });
                 }
-                catch (error) {
-                    const err = error instanceof Error ? error : new Error(String(error));
-                    logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
+                // Stage 2: File Read Deduplication
+                if (this.config.enableDeduplicate &&
+                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                    const dedupResult = deduplicateFileReads(currentMessages);
+                    if (dedupResult.deduplicated) {
+                        currentMessages = dedupResult.messages;
+                        stagesUsed.push("deduplicate");
+                    }
+                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                    logger.info("[Compaction] Stage 2 (deduplicate)", {
                         requestId,
-                        error: err.message,
-                        errorName: err.name,
+                        ran: dedupResult.deduplicated,
                         tokensBefore: stageTokensBefore,
-                        tokensAfter: stageTokensBefore,
-                        saved: 0,
-                    });
-                    // Record failure on the compaction span for trace visibility
-                    span = SpanSerializer.updateAttributes(span, {
-                        "compaction.stage3.error": err.message,
-                        "compaction.stage3.errorName": err.name,
-                        "compaction.stage3.tokensBefore": stageTokensBefore,
-                        "compaction.stage3_failed": true,
+                        tokensAfter: stageTokensAfter,
+                        saved: stageTokensBefore - stageTokensAfter,
                     });
-                    // Fall through to Stage 4 truncation as before
                 }
-            }
-            // Stage 4: Sliding Window Truncation (fallback)
-            if (this.config.enableTruncate &&
-                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                const truncResult = truncateWithSlidingWindow(currentMessages, {
-                    fraction: this.config.truncationFraction,
-                    currentTokens: stageTokensBefore,
-                    targetTokens: targetTokens,
-                    provider: provider,
-                    adaptiveBuffer: 0.15,
-                    maxIterations: 6,
-                });
-                if (truncResult.truncated) {
-                    currentMessages = truncResult.messages;
-                    stagesUsed.push("truncate");
+                // Stage 3: LLM Summarization
+                if (this.config.enableSummarize &&
+                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                    try {
+                        const summarizeResult = await withTimeout(summarizeMessages(currentMessages, {
+                            provider: this.config.summarizationProvider,
+                            model: this.config.summarizationModel,
+                            keepRecentRatio: this.config.keepRecentRatio,
+                            memoryConfig,
+                            targetTokens,
+                        }), 120_000, "LLM summarization timed out after 120s");
+                        if (summarizeResult.summarized) {
+                            currentMessages = summarizeResult.messages;
+                            stagesUsed.push("summarize");
+                        }
+                        const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                        logger.info("[Compaction] Stage 3 (summarize)", {
+                            requestId,
+                            ran: summarizeResult.summarized,
+                            tokensBefore: stageTokensBefore,
+                            tokensAfter: stageTokensAfter,
+                            saved: stageTokensBefore - stageTokensAfter,
+                        });
+                    }
+                    catch (error) {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
+                            requestId,
+                            error: err.message,
+                            errorName: err.name,
+                            tokensBefore: stageTokensBefore,
+                            tokensAfter: stageTokensBefore,
+                            saved: 0,
+                        });
+                        // Record failure on the compaction span for trace visibility
+                        span = SpanSerializer.updateAttributes(span, {
+                            "compaction.stage3.error": err.message,
+                            "compaction.stage3.errorName": err.name,
+                            "compaction.stage3.tokensBefore": stageTokensBefore,
+                            "compaction.stage3_failed": true,
+                        });
+                        // Fall through to Stage 4 truncation as before
+                    }
                 }
-                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                logger.info("[Compaction] Stage 4 (truncate)", {
+                // Stage 4: Sliding Window Truncation (fallback)
+                if (this.config.enableTruncate &&
+                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                    const truncResult = truncateWithSlidingWindow(currentMessages, {
+                        fraction: this.config.truncationFraction,
+                        currentTokens: stageTokensBefore,
+                        targetTokens: targetTokens,
+                        provider: provider,
+                        adaptiveBuffer: 0.15,
+                        maxIterations: 6,
+                    });
+                    if (truncResult.truncated) {
+                        currentMessages = truncResult.messages;
+                        stagesUsed.push("truncate");
+                    }
+                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                    logger.info("[Compaction] Stage 4 (truncate)", {
+                        requestId,
+                        ran: truncResult.truncated,
+                        tokensBefore: stageTokensBefore,
+                        tokensAfter: stageTokensAfter,
+                        saved: stageTokensBefore - stageTokensAfter,
+                    });
+                }
+                const tokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Complete", {
                     requestId,
-                    ran: truncResult.truncated,
-                    tokensBefore: stageTokensBefore,
-                    tokensAfter: stageTokensAfter,
-                    saved: stageTokensBefore - stageTokensAfter,
+                    tokensBefore,
+                    tokensAfter,
+                    totalSaved: tokensBefore - tokensAfter,
+                    stagesUsed,
+                    durationMs: Date.now() - spanStartTime,
                 });
+                const result = {
+                    compacted: stagesUsed.length > 0,
+                    stagesUsed,
+                    tokensBefore,
+                    tokensAfter,
+                    tokensSaved: tokensBefore - tokensAfter,
+                    messages: currentMessages,
+                };
+                span.durationMs = Date.now() - spanStartTime;
+                const compactionSucceeded = tokensAfter <= targetTokens;
+                const finalStatus = compactionSucceeded
+                    ? SpanStatus.OK
+                    : SpanStatus.WARNING;
+                const finalMessage = compactionSucceeded
+                    ? undefined
+                    : `Compaction insufficient: ${tokensAfter} tokens remain (target: ${targetTokens})`;
+                const endedSpan = SpanSerializer.endSpan(SpanSerializer.updateAttributes(span, {
+                    "context.stage": stagesUsed.join(",") || "none",
+                    "context.tokensBefore": tokensBefore,
+                    "context.tokensAfter": tokensAfter,
+                    "context.tokensSaved": tokensBefore - tokensAfter,
+                }), finalStatus, finalMessage);
+                getMetricsAggregator().recordSpan(endedSpan);
+                return result;
+            }
+            catch (error) {
+                span.durationMs = Date.now() - spanStartTime;
+                const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                endedSpan.statusMessage =
+                    error instanceof Error ? error.message : String(error);
+                getMetricsAggregator().recordSpan(endedSpan);
+                throw error;
             }
-            const tokensAfter = estimateMessagesTokens(currentMessages, provider);
-            logger.info("[Compaction] Complete", {
-                requestId,
-                tokensBefore,
-                tokensAfter,
-                totalSaved: tokensBefore - tokensAfter,
-                stagesUsed,
-                durationMs: Date.now() - spanStartTime,
-            });
-            const result = {
-                compacted: stagesUsed.length > 0,
-                stagesUsed,
-                tokensBefore,
-                tokensAfter,
-                tokensSaved: tokensBefore - tokensAfter,
-                messages: currentMessages,
-            };
-            span.durationMs = Date.now() - spanStartTime;
-            const endedSpan = SpanSerializer.endSpan(SpanSerializer.updateAttributes(span, {
-                "context.stage": stagesUsed.join(",") || "none",
-                "context.tokensBefore": tokensBefore,
-                "context.tokensAfter": tokensAfter,
-                "context.tokensSaved": tokensBefore - tokensAfter,
-            }), SpanStatus.OK);
-            getMetricsAggregator().recordSpan(endedSpan);
-            return result;
-        }
-        catch (error) {
-            span.durationMs = Date.now() - spanStartTime;
-            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
-            endedSpan.statusMessage =
-                error instanceof Error ? error.message : String(error);
-            getMetricsAggregator().recordSpan(endedSpan);
-            throw error;
-        }
+        }); // end withSpan
     }
 }