@juspay/neurolink 9.10.0 → 9.11.0

package/dist/types/conversation.d.ts

@@ -71,6 +71,14 @@ export type ConversationMemoryConfig = {
         maxToolOutputBytes?: number;
         /** Tool output max lines (default: 2000) */
         maxToolOutputLines?: number;
+        /**
+         * When true, buildContextMessages() returns the head/tail preview instead of
+         * the full tool output for tool_result messages. Default: false (full output sent to LLM).
+         * When false (default), the AI receives the complete tool output in content.
+         * When true, the AI receives the truncated preview and can use the retrieve_context
+         * tool to access full output if needed.
+         */
+        sendToolPreview?: boolean;
         /** File read budget as fraction of remaining context (default: 0.60) */
         fileReadBudgetPercent?: number;
     };
@@ -167,6 +175,64 @@ export type StreamEventSequence = {
     /** Event-specific data */
     [key: string]: unknown;
 };
+/** Structured metadata for tool_result messages. */
+export type ToolResultData = {
+    /** Whether the tool execution succeeded */
+    success?: boolean;
+    /** Expression that was evaluated (for calculation tools) */
+    expression?: string;
+    /**
+     * The tool execution result.
+     * @deprecated Read from ChatMessage.content instead. This field is dynamically
+     * populated from content for backward compatibility and will be removed in a future version.
+     */
+    result?: unknown;
+    /** Result type hint */
+    type?: string;
+    /** Error message if execution failed */
+    error?: string;
+};
+/** Metadata associated with a ChatMessage. */
+export type ChatMessageMetadata = {
+    /** Is this a summary message? */
+    isSummary?: boolean;
+    /** First message ID that this summary covers */
+    summarizesFrom?: string;
+    /** Last message ID that this summary covers */
+    summarizesTo?: string;
+    /** Was this message truncated due to token limits? */
+    truncated?: boolean;
+    /** Source of the message (e.g., provider name, user input) */
+    source?: string;
+    /** Language of the message content */
+    language?: string;
+    /** Confidence score for AI-generated content */
+    confidence?: number;
+    /**
+     * Numeric timestamp for internal tracking and efficient comparisons.
+     * Format: Unix epoch milliseconds (number).
+     * Complements the ISO string `ChatMessage.timestamp` field.
+     * Use this for sorting, filtering, and performance-critical operations.
+     */
+    timestamp?: number;
+    /** Model used to generate this message */
+    modelUsed?: string;
+    /** Unique signature identifying thought/reasoning patterns */
+    thoughtSignature?: string;
+    /** Hash of the thinking/reasoning content for deduplication */
+    thoughtHash?: string;
+    /** Whether extended thinking was used for this message */
+    thinkingExpanded?: boolean;
+    /**
+     * Head/tail preview of a large tool output.
+     * Only present on tool_result messages where the output exceeded truncation limits.
+     * When `sendToolPreview` is enabled in config, `buildContextMessages()` returns
+     * this value as the message content instead of the full output.
+     */
+    toolOutputPreview?: string;
+    /** Original byte size of the full tool output before any truncation */
+    originalSize?: number;
+};
 /**
  * Chat message format for conversation history
  */
@@ -188,14 +254,8 @@ export type ChatMessage = {
     tool?: string;
     /** Tool arguments (optional) - for tool_call messages */
     args?: Record<string, unknown>;
-    /** Tool result (optional) - for tool_result messages */
-    result?: {
-        success?: boolean;
-        expression?: string;
-        result?: unknown;
-        type?: string;
-        error?: string;
-    };
+    /** Tool result metadata (optional) - for tool_result messages */
+    result?: ToolResultData;
     /**
      * Event sequence for rich history reconstruction
      * Stores ordered events (text-chunk, ui-component, tool calls, HITL, etc.)
@@ -203,38 +263,8 @@ export type ChatMessage = {
      * @since 8.21.0
      */
     events?: StreamEventSequence[];
-    /** Message metadata (NEW - for token-based memory) */
-    metadata?: {
-        /** Is this a summary message? */
-        isSummary?: boolean;
-        /** First message ID that this summary covers */
-        summarizesFrom?: string;
-        /** Last message ID that this summary covers */
-        summarizesTo?: string;
-        /** Was this message truncated due to token limits? */
-        truncated?: boolean;
-        /** Source of the message (e.g., provider name, user input) */
-        source?: string;
-        /** Language of the message content */
-        language?: string;
-        /** Confidence score for AI-generated content */
-        confidence?: number;
-        /**
-         * Numeric timestamp for internal tracking and efficient comparisons.
-         * Format: Unix epoch milliseconds (number).
-         * Complements the ISO string `ChatMessage.timestamp` field.
-         * Use this for sorting, filtering, and performance-critical operations.
-         */
-        timestamp?: number;
-        /** Model used to generate this message */
-        modelUsed?: string;
-        /** Unique signature identifying thought/reasoning patterns */
-        thoughtSignature?: string;
-        /** Hash of the thinking/reasoning content for deduplication */
-        thoughtHash?: string;
-        /** Whether extended thinking was used for this message */
-        thinkingExpanded?: boolean;
-    };
+    /** Message metadata */
+    metadata?: ChatMessageMetadata;
     /** UUID identifying this condensation group */
     condenseId?: string;
     /** Points to summary that replaces this message */
@@ -323,6 +353,8 @@ export type StoreConversationTurnOptions = {
     providerDetails?: ProviderDetails;
     enableSummarization?: boolean;
     events?: StreamEventSequence[];
+    /** Observability request identifier for log correlation */
+    requestId?: string;
     /** API-reported token usage from provider response */
     tokenUsage?: {
         inputTokens?: number;

package/dist/types/conversationMemoryInterface.d.ts

@@ -17,11 +17,15 @@ export type IConversationMemoryManager = {
     /** Get session by ID */
     getSession(sessionId: string, userId?: string): SessionMemory | undefined | Promise<SessionMemory | undefined>;
     /** Build context messages for AI prompt injection */
-    buildContextMessages(sessionId: string, userId?: string, enableSummarization?: boolean): Promise<ChatMessage[]> | ChatMessage[];
+    buildContextMessages(sessionId: string, userId?: string, enableSummarization?: boolean, requestId?: string): Promise<ChatMessage[]> | ChatMessage[];
     /** Clear a specific session */
     clearSession(sessionId: string, userId?: string): Promise<boolean> | boolean;
     /** Clear all sessions */
     clearAllSessions(): Promise<void> | void;
     /** Get memory statistics */
     getStats(): Promise<ConversationMemoryStats> | ConversationMemoryStats;
+    /** Get raw messages array for a session (no context filtering or summarization) */
+    getSessionMessages(sessionId: string, userId?: string): Promise<ChatMessage[]>;
+    /** Replace the entire messages array for a session */
+    setSessionMessages(sessionId: string, messages: ChatMessage[], userId?: string): Promise<void>;
 };

package/dist/types/generateTypes.d.ts

@@ -355,6 +355,26 @@ export type GenerateOptions = {
      * ```
      */
     rag?: RAGConfig;
+    /**
+     * Maximum budget in USD for this session. When the accumulated cost of all
+     * generate() calls on this NeuroLink instance exceeds this value, subsequent
+     * calls will throw a budget-exceeded error before making the API request.
+     *
+     * @example
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Summarize this" },
+     *   maxBudgetUsd: 1.00
+     * });
+     * ```
+     */
+    maxBudgetUsd?: number;
+    /**
+     * Optional request identifier for observability and log correlation.
+     * When provided, this ID is forwarded to spans, logs, and telemetry so
+     * callers can correlate generation traces back to their own request lifecycle.
+     */
+    requestId?: string;
     /**
      * File reference registry for on-demand file processing.
      *
@@ -820,6 +840,12 @@ export type TextGenerationOptions = {
         /** Thinking level (Gemini 3: minimal|low|medium|high). Ignored for Anthropic. */
         thinkingLevel?: "minimal" | "low" | "medium" | "high";
     };
+    /**
+     * Optional request identifier for observability and log correlation.
+     * When provided, this ID is forwarded to spans, logs, and telemetry so
+     * callers can correlate generation traces back to their own request lifecycle.
+     */
+    requestId?: string;
 };
 /**
  * Text generation result (consolidated from core types)

package/dist/types/modelTypes.d.ts

@@ -89,8 +89,8 @@ export declare const ModelConfigSchema: z.ZodObject<{
     releaseDate: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    capabilities: string[];
     displayName: string;
+    capabilities: string[];
     deprecated: boolean;
     pricing: {
         input: number;
@@ -100,8 +100,8 @@ export declare const ModelConfigSchema: z.ZodObject<{
     releaseDate: string;
 }, {
     id: string;
-    capabilities: string[];
     displayName: string;
+    capabilities: string[];
     deprecated: boolean;
     pricing: {
         input: number;
@@ -135,8 +135,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         releaseDate: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -146,8 +146,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         releaseDate: string;
     }, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -159,10 +159,12 @@ export declare const ModelRegistrySchema: z.ZodObject<{
     aliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
+    version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -171,15 +173,15 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    version: string;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }, {
+    version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -188,8 +190,6 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    version: string;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }>;

package/dist/types/multimodal.d.ts

@@ -316,6 +316,8 @@ export type MultimodalChatMessage = {
     role: "user" | "assistant" | "system";
     /** Content of the message - can be text or multimodal content array */
     content: string | MessageContent[];
+    /** Provider-specific options (e.g. Anthropic cache_control) */
+    providerOptions?: Record<string, unknown>;
 };
 /**
  * Multimodal message structure for provider adapters

package/dist/types/observability.d.ts

@@ -97,6 +97,16 @@ export type LangfuseConfig = {
      * @default false
      */
     autoDetectExternalProvider?: boolean;
+    /**
+     * If true, NeuroLink will NOT register its own LangfuseSpanProcessor with the
+     * global TracerProvider when using external provider mode. Only the ContextEnricher
+     * will be registered. Use this when the host application already registers a
+     * LangfuseSpanProcessor (e.g., via a DeferredSpanProcessor) to prevent duplicate
+     * trace exports to Langfuse.
+     *
+     * @default false
+     */
+    skipLangfuseSpanProcessor?: boolean;
     /**
      * Enable auto-detection of operation names from span names.
      *

package/dist/types/sdkTypes.d.ts

@@ -13,7 +13,7 @@ export type { AnalyticsData, TokenUsage } from "./analytics.js";
 export type { BaseCommandArgs, CommandResult, GenerateCommandArgs, GenerateResult as CLIGenerateResult, MCPCommandArgs, ModelsCommandArgs, StreamChunk, } from "./cli.js";
 export type { ErrorInfo, FunctionParameters, JsonArray, JsonObject, JsonValue, ProcessResult, Result, TestFunction, TestResult, Unknown, UnknownArray, UnknownRecord, } from "./common.js";
 export type { Content, ImageContent, MultimodalMessage, ProcessedImage, ProviderImageFormat, ProviderMultimodalPayload, TextContent, VisionCapability, } from "./content.js";
-export type { ChatMessage, ConversationMemoryConfig, ConversationMemoryError, ConversationMemoryEvents, MessageContent, MultimodalChatMessage, RedisConversationObject, RedisStorageConfig, SessionIdentifier, SessionMemory, SessionMetadata, StoreConversationTurnOptions, } from "./conversation.js";
+export type { ChatMessage, ChatMessageMetadata, ToolResultData, ConversationMemoryConfig, ConversationMemoryError, ConversationMemoryEvents, MessageContent, MultimodalChatMessage, RedisConversationObject, RedisStorageConfig, SessionIdentifier, SessionMemory, SessionMetadata, StoreConversationTurnOptions, } from "./conversation.js";
 export type { DomainConfig, DomainConfigOptions, DomainEvaluationCriteria, DomainTemplate, DomainType, DomainValidationRule, } from "./domainTypes.js";
 export type { EnhancedEvaluationResult, EvaluationContext, EvaluationCriteria, EvaluationData, EvaluationRequest, } from "./evaluation.js";
 export type { ExternalMCPConfigValidation, ExternalMCPManagerConfig, ExternalMCPOperationResult, ExternalMCPServerEvents, ExternalMCPServerHealth, ExternalMCPServerInstance, ExternalMCPServerStatus, ExternalMCPToolContext, ExternalMCPToolInfo, ExternalMCPToolResult, } from "./externalMcp.js";

package/dist/utils/conversationMemory.d.ts

@@ -19,14 +19,14 @@ export declare function getConversationMessages(conversationMemory: Conversation
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined): Promise<void>;
+export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined, requestId?: string): Promise<void>;
 /**
  * Build context messages from pointer onwards (token-based memory)
  * Returns summary message (if exists) + all messages after the summarized pointer
  * @param session - Session memory with pointer
  * @returns Context messages to send to LLM
  */
-export declare function buildContextFromPointer(session: SessionMemory): ChatMessage[];
+export declare function buildContextFromPointer(session: SessionMemory, requestId?: string): ChatMessage[];
 /**
  * Create summarization prompt from message history
  * Used by both in-memory and Redis conversation managers
@@ -60,9 +60,10 @@ export declare function getEffectiveTokenThreshold(provider: string, model: stri
  * @param config - Conversation memory configuration containing provider/model settings
  * @param previousSummary - Optional previous summary to build upon
  * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @param requestId - Optional request ID for request-scoped tracing
  * @returns Summary text or null if generation fails
  */
-export declare function generateSummary(messages: ChatMessage[], config: Partial<ConversationMemoryConfig>, logPrefix?: string, previousSummary?: string): Promise<string | null>;
+export declare function generateSummary(messages: ChatMessage[], config: Partial<ConversationMemoryConfig>, logPrefix?: string, previousSummary?: string, requestId?: string): Promise<string | null>;
 /**
  * Check if Redis is available for conversation memory.
  * Migrated from the deprecated conversationMemoryUtils.ts.

package/dist/utils/conversationMemory.js

@@ -74,8 +74,9 @@ export async function getConversationMessages(conversationMemory, options) {
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp) {
+export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp, requestId) {
     logger.debug("[conversationMemoryUtils] storeConversationTurn called", {
+        requestId,
         hasMemory: !!conversationMemory,
         memoryType: conversationMemory?.constructor?.name || "NONE",
         hasContext: !!originalOptions.context,
@@ -90,6 +91,7 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
     const sessionId = context.sessionId;
     const userId = typeof context.userId === "string" ? context.userId : undefined;
     logger.debug("[conversationMemoryUtils] Extracted session details from context", {
+        requestId,
         sessionId,
         userId,
         contextKeys: Object.keys(context),
@@ -135,6 +137,7 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
             startTimeStamp,
             providerDetails,
             enableSummarization: originalOptions.enableSummarization,
+            requestId,
             tokenUsage: result.usage
                 ? {
                     inputTokens: result.usage.input,
@@ -146,6 +149,7 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
                 : undefined,
         });
         logger.debug("[conversationMemoryUtils] Conversation turn stored successfully", {
+            requestId,
             sessionId,
             userId,
             memoryType: conversationMemory.constructor.name,
@@ -154,11 +158,14 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         });
     }
     catch (error) {
+        const details = error?.details;
         logger.warn("[conversationMemoryUtils] Failed to store conversation turn", {
             sessionId,
             userId,
             memoryType: conversationMemory.constructor.name,
             error: error instanceof Error ? error.message : String(error),
+            innerError: details?.error || "none",
+            errorCode: error?.code || "unknown",
             stack: error instanceof Error ? error.stack : undefined,
         });
     }
@@ -169,8 +176,17 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
  * @param session - Session memory with pointer
  * @returns Context messages to send to LLM
  */
-export function buildContextFromPointer(session) {
+export function buildContextFromPointer(session, requestId) {
     if (!session.summarizedUpToMessageId || !session.summarizedMessage) {
+        // Log context built for LLM (no summary)
+        const totalChars = session.messages.reduce((sum, msg) => sum + msg.content.length, 0);
+        logger.info("[ConversationMemory] Context built for LLM", {
+            requestId,
+            sessionId: session.sessionId,
+            contextMessages: session.messages.length,
+            summaryPrepended: false,
+            estimatedTokens: Math.ceil(totalChars / 4),
+        });
         return session.messages;
     }
     // find a better way to wirte this
@@ -181,6 +197,15 @@ export function buildContextFromPointer(session) {
             pointer: session.summarizedUpToMessageId,
             totalMessages: session.messages.length,
         });
+        // Log context built for LLM (pointer not found fallback)
+        const totalChars = session.messages.reduce((sum, msg) => sum + msg.content.length, 0);
+        logger.info("[ConversationMemory] Context built for LLM", {
+            requestId,
+            sessionId: session.sessionId,
+            contextMessages: session.messages.length,
+            summaryPrepended: false,
+            estimatedTokens: Math.ceil(totalChars / 4),
+        });
         return session.messages;
     }
     const messagesAfterPointer = session.messages.slice(pointerIndex + 1);
@@ -202,7 +227,17 @@ export function buildContextFromPointer(session) {
         totalMessages: session.messages.length,
         summaryLength: session.summarizedMessage.length,
     });
-    return [summaryMessage, ...messagesAfterPointer];
+    const contextMessages = [summaryMessage, ...messagesAfterPointer];
+    // Log context built for LLM with structural metadata
+    const totalChars = contextMessages.reduce((sum, msg) => sum + msg.content.length, 0);
+    logger.info("[ConversationMemory] Context built for LLM", {
+        requestId,
+        sessionId: session.sessionId,
+        contextMessages: contextMessages.length,
+        summaryPrepended: true,
+        estimatedTokens: Math.ceil(totalChars / 4),
+    });
+    return contextMessages;
 }
 /**
  * Create summarization prompt from message history
@@ -282,16 +317,19 @@ export function getEffectiveTokenThreshold(provider, model, envOverride, session
  * @param config - Conversation memory configuration containing provider/model settings
  * @param previousSummary - Optional previous summary to build upon
  * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @param requestId - Optional request ID for request-scoped tracing
  * @returns Summary text or null if generation fails
  */
-export async function generateSummary(messages, config, logPrefix = "[ConversationMemory]", previousSummary) {
+export async function generateSummary(messages, config, logPrefix = "[ConversationMemory]", previousSummary, requestId) {
     const summarizationPrompt = createSummarizationPrompt(messages, previousSummary);
     const summarizer = new NeuroLink({
         conversationMemory: { enabled: false },
     });
     try {
         if (!config.summarizationProvider || !config.summarizationModel) {
-            logger.error(`${logPrefix} Missing summarization provider`);
+            logger.error(`${logPrefix} Missing summarization provider`, {
+                requestId,
+            });
             return null;
         }
         const summaryResult = await summarizer.generate({
@@ -303,7 +341,7 @@ export async function generateSummary(messages, config, logPrefix = "[Conversati
         return summaryResult.content || null;
     }
     catch (error) {
-        logger.error(`${logPrefix} Error generating summary`, { error });
+        logger.error(`${logPrefix} Error generating summary`, { requestId, error });
         return null;
     }
 }

package/dist/utils/errorHandling.d.ts

@@ -247,6 +247,11 @@ export declare class CircuitBreaker {
 /**
  * Detect AbortError from any source (DOMException, plain Error, or message-based).
  * Used to short-circuit retry/fallback loops when an abort signal fires.
+ *
+ * Uses `includes()` for message checks because provider error handlers
+ * (e.g., googleVertex.formatProviderError) wrap the original AbortError
+ * in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
+ * which destroys the exact message match.
  */
 export declare function isAbortError(error: unknown): boolean;
 /**

package/dist/utils/errorHandling.js

@@ -823,6 +823,11 @@ export class CircuitBreaker {
 /**
  * Detect AbortError from any source (DOMException, plain Error, or message-based).
  * Used to short-circuit retry/fallback loops when an abort signal fires.
+ *
+ * Uses `includes()` for message checks because provider error handlers
+ * (e.g., googleVertex.formatProviderError) wrap the original AbortError
+ * in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
+ * which destroys the exact message match.
  */
 export function isAbortError(error) {
     if (error instanceof DOMException && error.name === "AbortError") {
@@ -832,8 +837,8 @@ export function isAbortError(error) {
         return true;
     }
     if (error instanceof Error &&
-        (error.message === "This operation was aborted" ||
-            error.message === "The operation was aborted" ||
+        (error.message?.includes("This operation was aborted") ||
+            error.message?.includes("The operation was aborted") ||
             error.message?.includes("The user aborted a request"))) {
         return true;
     }

package/dist/utils/logger.d.ts

@@ -63,8 +63,15 @@ declare class NeuroLinkLogger {
      * @returns Formatted prefix string like "[2025-08-18T13:45:30.123Z] [NEUROLINK:ERROR]"
      */
     private getLogPrefix;
+    /**
+     * Safely serialize data to fully expanded JSON string.
+     * Handles circular references and non-serializable values.
+     * Zero truncation — all nested objects and arrays are fully expanded.
+     */
+    private serializeData;
     /**
      * Outputs a log entry to the console based on the log level.
+     * Data is fully serialized to JSON — no [Object] or [Array] truncation.
      *
      * @param level - The log level (debug, info, warn, error).
      * @param prefix - The formatted log prefix.
@@ -189,6 +196,7 @@ export declare const logger: {
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
     table: (data: unknown) => void;
+    shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;

package/dist/utils/logger.js

@@ -95,8 +95,61 @@ class NeuroLinkLogger {
     getLogPrefix(timestamp, level) {
         return `[${timestamp}] [NEUROLINK:${UPPERCASE_LOG_LEVELS[level]}]`;
     }
+    /**
+     * Safely serialize data to fully expanded JSON string.
+     * Handles circular references and non-serializable values.
+     * Zero truncation — all nested objects and arrays are fully expanded.
+     */
+    serializeData(data) {
+        if (data === undefined || data === null) {
+            return String(data);
+        }
+        if (typeof data !== "object") {
+            return String(data);
+        }
+        try {
+            return JSON.stringify(data, (_key, value) => {
+                if (value instanceof Error) {
+                    return {
+                        name: value.name,
+                        message: value.message,
+                        stack: value.stack,
+                    };
+                }
+                return value;
+            });
+        }
+        catch {
+            // Handle circular references using a stack-based approach
+            // to avoid false "[Circular]" on diamond (shared) references
+            const ancestors = [];
+            try {
+                return JSON.stringify(data, function (_key, value) {
+                    if (value instanceof Error) {
+                        return {
+                            name: value.name,
+                            message: value.message,
+                            stack: value.stack,
+                        };
+                    }
+                    if (typeof value === "object" && value !== null) {
+                        // Only flag actual circular (ancestor) references
+                        if (ancestors.includes(value)) {
+                            return "[Circular]";
+                        }
+                        ancestors.push(value);
+                    }
+                    return value;
+                });
+            }
+            catch {
+                return "[Unserializable Object]";
+            }
+        }
+    }
     /**
      * Outputs a log entry to the console based on the log level.
+     * Data is fully serialized to JSON — no [Object] or [Array] truncation.
      *
      * @param level - The log level (debug, info, warn, error).
      * @param prefix - The formatted log prefix.
@@ -111,7 +164,7 @@ class NeuroLinkLogger {
             error: console.error,
         }[level];
         if (data !== undefined && data !== null) {
-            logMethod(prefix, message, data);
+            logMethod(prefix, message, this.serializeData(data));
         }
         else {
             logMethod(prefix, message);
@@ -338,6 +391,8 @@ export const logger = {
     table: (data) => {
         neuroLinkLogger.table(data);
     },
+    // Expose log-level check for gating expensive operations
+    shouldLog: (level) => neuroLinkLogger.shouldLog(level),
     // Expose structured logging methods
     setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
     getLogs: (level) => neuroLinkLogger.getLogs(level),