@juspay/neurolink 7.37.0 → 7.38.0

package/dist/providers/openAI.d.ts

@@ -11,12 +11,35 @@ import type { NeuroLink } from "../neurolink.js";
 export declare class OpenAIProvider extends BaseProvider {
     private model;
     constructor(modelName?: string, neurolink?: NeuroLink);
+    /**
+     * Check if this provider supports tool/function calling
+     */
+    supportsTools(): boolean;
     getProviderName(): AIProviderName;
     getDefaultModel(): string;
     /**
      * Returns the Vercel AI SDK model instance for OpenAI
      */
     getAISDKModel(): LanguageModelV1;
+    /**
+     * OpenAI-specific tool validation and filtering
+     * Filters out tools that might cause streaming issues
+     */
+    private validateAndFilterToolsForOpenAI;
+    /**
+     * Validate Zod schema structure
+     */
+    private validateZodSchema;
+    /**
+     * Validate tool structure for OpenAI compatibility
+     * More lenient validation to avoid filtering out valid tools
+     */
+    private isValidToolStructure;
+    /**
+     * Validate tool parameters for OpenAI compatibility
+     * Ensures the tool has either valid Zod schema or valid JSON schema
+     */
+    private isValidToolParameters;
     handleProviderError(error: unknown): Error;
     /**
      * executeGenerate method removed - generation is now handled by BaseProvider.

package/dist/providers/openAI.js

@@ -10,6 +10,7 @@ import { validateApiKey, createOpenAIConfig, getProviderModel, } from "../utils/
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
+import { isZodSchema } from "../utils/schemaConversion.js";
 // Configuration helpers - now using consolidated utility
 const getOpenAIApiKey = () => {
     return validateApiKey(createOpenAIConfig());
@@ -32,14 +33,22 @@ export class OpenAIProvider extends BaseProvider {
         });
         // Initialize model
         this.model = openai(this.modelName);
-        logger.debug("OpenAIProviderV2 initialized", {
+        logger.debug("OpenAIProvider constructor called", {
             model: this.modelName,
             provider: this.providerName,
+            supportsTools: this.supportsTools(),
+            className: this.constructor.name,
         });
     }
     // ===================
     // ABSTRACT METHOD IMPLEMENTATIONS
     // ===================
+    /**
+     * Check if this provider supports tool/function calling
+     */
+    supportsTools() {
+        return true; // Re-enable tools now that we understand the issue
+    }
     getProviderName() {
         return AIProviderName.OPENAI;
     }
@@ -52,6 +61,128 @@ export class OpenAIProvider extends BaseProvider {
     getAISDKModel() {
         return this.model;
     }
+    /**
+     * OpenAI-specific tool validation and filtering
+     * Filters out tools that might cause streaming issues
+     */
+    validateAndFilterToolsForOpenAI(tools) {
+        const validTools = {};
+        for (const [name, tool] of Object.entries(tools)) {
+            try {
+                // Basic validation - ensure tool has required structure
+                if (tool && typeof tool === "object") {
+                    // Check if tool has description (required by OpenAI)
+                    if (tool.description && typeof tool.description === "string") {
+                        // Keep the original tool structure - AI SDK will handle Zod schema conversion internally
+                        const processedTool = { ...tool };
+                        // Validate that Zod schemas are properly structured for AI SDK processing
+                        if (tool.parameters && isZodSchema(tool.parameters)) {
+                            logger.debug(`OpenAI: Tool ${name} has Zod schema - AI SDK will handle conversion`);
+                            // Basic validation that the Zod schema has the required structure
+                            this.validateZodSchema(name, tool.parameters);
+                        }
+                        // Include the tool with original Zod schema for AI SDK processing
+                        if (this.isValidToolStructure(processedTool)) {
+                            validTools[name] = processedTool;
+                        }
+                        else {
+                            logger.warn(`OpenAI: Filtering out tool with invalid structure: ${name}`, {
+                                parametersType: typeof processedTool.parameters,
+                                hasDescription: !!processedTool.description,
+                                hasExecute: !!processedTool.execute,
+                            });
+                        }
+                    }
+                    else {
+                        logger.warn(`OpenAI: Filtering out tool without description: ${name}`);
+                    }
+                }
+                else {
+                    logger.warn(`OpenAI: Filtering out invalid tool: ${name}`);
+                }
+            }
+            catch (error) {
+                logger.warn(`OpenAI: Error validating tool ${name}:`, error);
+            }
+        }
+        return validTools;
+    }
+    /**
+     * Validate Zod schema structure
+     */
+    validateZodSchema(toolName, schema) {
+        try {
+            const zodSchema = schema;
+            if (zodSchema._def && zodSchema._def.typeName) {
+                logger.debug(`OpenAI: Zod schema for ${toolName} appears valid`, {
+                    typeName: zodSchema._def.typeName,
+                });
+            }
+            else {
+                logger.warn(`OpenAI: Zod schema for ${toolName} missing typeName - may cause issues`);
+            }
+        }
+        catch (zodValidationError) {
+            logger.warn(`OpenAI: Zod schema validation failed for ${toolName}:`, zodValidationError);
+            // Continue anyway - let AI SDK handle it
+        }
+    }
+    /**
+     * Validate tool structure for OpenAI compatibility
+     * More lenient validation to avoid filtering out valid tools
+     */
+    isValidToolStructure(tool) {
+        if (!tool || typeof tool !== "object") {
+            return false;
+        }
+        const toolObj = tool;
+        // Ensure tool has description and execute function
+        if (!toolObj.description || typeof toolObj.description !== "string") {
+            return false;
+        }
+        if (!toolObj.execute || typeof toolObj.execute !== "function") {
+            return false;
+        }
+        return this.isValidToolParameters(toolObj.parameters);
+    }
+    /**
+     * Validate tool parameters for OpenAI compatibility
+     * Ensures the tool has either valid Zod schema or valid JSON schema
+     */
+    isValidToolParameters(parameters) {
+        if (!parameters) {
+            // For OpenAI, tools without parameters need an empty object schema
+            return true;
+        }
+        // Check if it's a Zod schema - these are valid
+        if (isZodSchema(parameters)) {
+            return true;
+        }
+        // Check if it's a JSON schema
+        if (typeof parameters !== "object" || parameters === null) {
+            return false;
+        }
+        const params = parameters;
+        // If it's a JSON schema, it should have type "object" for OpenAI
+        if (params.type && params.type !== "object") {
+            return false;
+        }
+        // OpenAI requires schemas to have properties field, even if empty
+        // If there's no properties field, the schema is incomplete
+        if (params.type === "object" && !params.properties) {
+            logger.warn(`Tool parameter schema missing properties field:`, params);
+            return false;
+        }
+        // If properties exist, they should be an object
+        if (params.properties && typeof params.properties !== "object") {
+            return false;
+        }
+        // If required exists, it should be an array
+        if (params.required && !Array.isArray(params.required)) {
+            return false;
+        }
+        return true;
+    }
     handleProviderError(error) {
         if (error instanceof TimeoutError) {
             throw new NetworkError(error.message, this.providerName);
@@ -90,9 +221,48 @@ export class OpenAIProvider extends BaseProvider {
         try {
             // Get tools consistently with generate method
             const shouldUseTools = !options.disableTools && this.supportsTools();
-            const tools = shouldUseTools ? await this.getAllTools() : {};
+            const allTools = shouldUseTools ? await this.getAllTools() : {};
+            // OpenAI-specific fix: Validate tools format and filter out problematic ones
+            let tools = this.validateAndFilterToolsForOpenAI(allTools);
+            // OpenAI has limits on the number of tools per request - limit to 3 tools max for testing
+            const MAX_TOOLS = 3;
+            if (Object.keys(tools).length > MAX_TOOLS) {
+                logger.warn(`OpenAI: Too many tools (${Object.keys(tools).length}), limiting to ${MAX_TOOLS} tools`);
+                const toolEntries = Object.entries(tools);
+                tools = Object.fromEntries(toolEntries.slice(0, MAX_TOOLS));
+            }
+            // Count tools with Zod schemas for debugging
+            const zodToolsCount = Object.values(allTools).filter((tool) => tool &&
+                typeof tool === "object" &&
+                tool.parameters &&
+                isZodSchema(tool.parameters)).length;
+            logger.info("OpenAI streaming tools", {
+                shouldUseTools,
+                allToolsCount: Object.keys(allTools).length,
+                filteredToolsCount: Object.keys(tools).length,
+                zodToolsCount,
+                toolNames: Object.keys(tools),
+                filteredOutTools: Object.keys(allTools).filter((name) => !tools[name]),
+            });
             // Build message array from options
             const messages = buildMessagesArray(options);
+            // Debug the actual request being sent to OpenAI
+            logger.debug(`OpenAI: streamText request parameters:`, {
+                modelName: this.modelName,
+                messagesCount: messages.length,
+                temperature: options.temperature,
+                maxTokens: options.maxTokens,
+                toolsCount: Object.keys(tools).length,
+                toolChoice: shouldUseTools && Object.keys(tools).length > 0 ? "auto" : "none",
+                maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
+                firstToolExample: Object.keys(tools).length > 0
+                    ? {
+                        name: Object.keys(tools)[0],
+                        description: tools[Object.keys(tools)[0]]?.description,
+                        parametersType: typeof tools[Object.keys(tools)[0]]?.parameters,
+                    }
+                    : "no-tools",
+            });
             const result = await streamText({
                 model: this.model,
                 messages: messages,
@@ -100,19 +270,166 @@ export class OpenAIProvider extends BaseProvider {
                 maxTokens: options.maxTokens, // No default limit - unlimited unless specified
                 tools,
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
-                toolChoice: shouldUseTools ? "auto" : "none",
+                toolChoice: shouldUseTools && Object.keys(tools).length > 0 ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                onStepFinish: ({ toolCalls, toolResults }) => {
+                    logger.info("Tool execution completed", { toolResults, toolCalls });
+                    // Handle tool execution storage
+                    this.handleToolExecutionStorage(toolCalls, toolResults, options).catch((error) => {
+                        logger.warn("[OpenAIProvider] Failed to store tool executions", {
+                            provider: this.providerName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    });
+                },
             });
             timeoutController?.cleanup();
-            // Transform stream to match StreamResult interface using BaseProvider method
-            const transformedStream = this.createTextStream(result);
+            // Debug the actual result structure
+            logger.debug(`OpenAI: streamText result structure:`, {
+                resultKeys: Object.keys(result),
+                hasTextStream: !!result.textStream,
+                hasToolCalls: !!result.toolCalls,
+                hasToolResults: !!result.toolResults,
+                resultType: typeof result,
+            });
+            // Transform string stream to content object stream using fullStream
+            const transformedStream = async function* () {
+                try {
+                    logger.debug(`OpenAI: Starting stream transformation`, {
+                        hasTextStream: !!result.textStream,
+                        hasFullStream: !!result.fullStream,
+                        resultKeys: Object.keys(result),
+                        toolsEnabled: shouldUseTools,
+                        toolsCount: Object.keys(tools).length,
+                    });
+                    let chunkCount = 0;
+                    let contentYielded = 0;
+                    // Try fullStream first (handles both text and tool calls), fallback to textStream
+                    const streamToUse = result.fullStream || result.textStream;
+                    if (!streamToUse) {
+                        logger.error("OpenAI: No stream available in result", {
+                            resultKeys: Object.keys(result),
+                        });
+                        return;
+                    }
+                    logger.debug(`OpenAI: Stream source selected:`, {
+                        usingFullStream: !!result.fullStream,
+                        usingTextStream: !!result.textStream && !result.fullStream,
+                        streamSourceType: result.fullStream ? "fullStream" : "textStream",
+                    });
+                    for await (const chunk of streamToUse) {
+                        chunkCount++;
+                        logger.debug(`OpenAI: Processing chunk ${chunkCount}:`, {
+                            chunkType: typeof chunk,
+                            chunkValue: typeof chunk === "string"
+                                ? chunk.substring(0, 50)
+                                : "not-string",
+                            chunkKeys: chunk && typeof chunk === "object"
+                                ? Object.keys(chunk)
+                                : "not-object",
+                            hasText: chunk && typeof chunk === "object" && "text" in chunk,
+                            hasTextDelta: chunk && typeof chunk === "object" && "textDelta" in chunk,
+                            hasType: chunk && typeof chunk === "object" && "type" in chunk,
+                            chunkTypeValue: chunk && typeof chunk === "object" && "type" in chunk
+                                ? chunk.type
+                                : "no-type",
+                        });
+                        let contentToYield = null;
+                        // Handle different chunk types from fullStream
+                        if (chunk && typeof chunk === "object") {
+                            // Log the full chunk structure for debugging (debug mode only)
+                            if (process.env.NEUROLINK_DEBUG === "true") {
+                                logger.debug(`OpenAI: Full chunk structure:`, {
+                                    chunkKeys: Object.keys(chunk),
+                                    fullChunk: JSON.stringify(chunk).substring(0, 500),
+                                });
+                            }
+                            if ("type" in chunk && chunk.type === "error") {
+                                // Handle error chunks when tools are enabled
+                                const errorChunk = chunk;
+                                logger.error(`OpenAI: Error chunk received:`, {
+                                    errorType: errorChunk.type,
+                                    errorDetails: errorChunk.error,
+                                    fullChunk: JSON.stringify(chunk),
+                                });
+                                // Throw a more descriptive error for tool-related issues
+                                const errorMessage = errorChunk.error &&
+                                    typeof errorChunk.error === "object" &&
+                                    "message" in errorChunk.error
+                                    ? String(errorChunk.error.message)
+                                    : "OpenAI API error when tools are enabled";
+                                throw new Error(`OpenAI streaming error with tools: ${errorMessage}. Try disabling tools with --disableTools`);
+                            }
+                            else if ("type" in chunk &&
+                                chunk.type === "text-delta" &&
+                                "textDelta" in chunk) {
+                                // Text delta from fullStream
+                                contentToYield = chunk.textDelta;
+                                logger.debug(`OpenAI: Found text-delta:`, {
+                                    textDelta: contentToYield,
+                                });
+                            }
+                            else if ("text" in chunk) {
+                                // Direct text chunk
+                                contentToYield = chunk.text;
+                                logger.debug(`OpenAI: Found direct text:`, {
+                                    text: contentToYield,
+                                });
+                            }
+                            else {
+                                // Log unhandled chunks in debug mode only
+                                if (process.env.NEUROLINK_DEBUG === "true") {
+                                    logger.debug(`OpenAI: Unhandled object chunk:`, {
+                                        chunkKeys: Object.keys(chunk),
+                                        chunkType: chunk.type || "no-type",
+                                        fullChunk: JSON.stringify(chunk).substring(0, 500),
+                                    });
+                                }
+                            }
+                        }
+                        else if (typeof chunk === "string") {
+                            // Direct string chunk from textStream
+                            contentToYield = chunk;
+                            logger.debug(`OpenAI: Found string chunk:`, {
+                                content: contentToYield,
+                            });
+                        }
+                        else {
+                            logger.warn(`OpenAI: Unhandled chunk type:`, {
+                                type: typeof chunk,
+                                value: String(chunk).substring(0, 100),
+                            });
+                        }
+                        if (contentToYield) {
+                            contentYielded++;
+                            logger.debug(`OpenAI: Yielding content ${contentYielded}:`, {
+                                content: contentToYield.substring(0, 50),
+                                length: contentToYield.length,
+                            });
+                            yield { content: contentToYield };
+                        }
+                    }
+                    logger.debug(`OpenAI: Stream transformation completed`, {
+                        totalChunks: chunkCount,
+                        contentYielded,
+                        success: contentYielded > 0,
+                    });
+                    if (contentYielded === 0) {
+                        logger.warn(`OpenAI: No content was yielded from stream despite processing ${chunkCount} chunks`);
+                    }
+                }
+                catch (streamError) {
+                    logger.error(`OpenAI: Stream transformation error:`, streamError);
+                    throw streamError;
+                }
+            };
             // Create analytics promise that resolves after stream completion
             const analyticsPromise = streamAnalyticsCollector.createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
                 requestId: `openai-stream-${Date.now()}`,
                 streamingMode: true,
             });
             return {
-                stream: transformedStream,
+                stream: transformedStream(),
                 provider: this.providerName,
                 model: this.modelName,
                 analytics: analyticsPromise,

package/dist/providers/openaiCompatible.js

@@ -166,6 +166,14 @@ export class OpenAICompatibleProvider extends BaseProvider {
                 tools: options.tools,
                 toolChoice: "auto",
                 abortSignal: timeoutController?.controller.signal,
+                onStepFinish: ({ toolCalls, toolResults }) => {
+                    this.handleToolExecutionStorage(toolCalls, toolResults, options).catch((error) => {
+                        logger.warn("[OpenAiCompatibleProvider] Failed to store tool executions", {
+                            provider: this.providerName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    });
+                },
             });
             timeoutController?.cleanup();
             // Transform stream to match StreamResult interface

package/dist/providers/sagemaker/language-model.d.ts

@@ -131,7 +131,7 @@ export declare class SageMakerLanguageModel implements LanguageModelV1 {
         provider: string;
         specificationVersion: string;
         endpointName: string;
-        modelType: "huggingface" | "mistral" | "custom" | "claude" | "llama" | "jumpstart" | undefined;
+        modelType: "custom" | "huggingface" | "mistral" | "claude" | "llama" | "jumpstart" | undefined;
         region: string;
     };
     /**
@@ -178,7 +178,7 @@ export declare class SageMakerLanguageModel implements LanguageModelV1 {
         provider: string;
         specificationVersion: string;
         endpointName: string;
-        modelType: "huggingface" | "mistral" | "custom" | "claude" | "llama" | "jumpstart" | undefined;
+        modelType: "custom" | "huggingface" | "mistral" | "claude" | "llama" | "jumpstart" | undefined;
         region: string;
     };
 }

package/dist/sdk/toolRegistration.js

@@ -5,6 +5,7 @@
 import { logger } from "../utils/logger.js";
 import { createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
+import { convertZodToJsonSchema, isZodSchema, } from "../utils/schemaConversion.js";
 /**
  * Configuration constants for tool validation
  */
@@ -73,7 +74,9 @@ export function createMCPServerFromTools(serverId, tools, metadata) {
         mcpTools.push({
             name,
             description: tool.description || name,
-            inputSchema: {},
+            inputSchema: tool.parameters
+                ? convertSchemaToJsonSchema(tool.parameters)
+                : {},
         });
     }
     // SMART DEFAULTS: Use utility to eliminate manual MCPServerInfo creation
@@ -89,6 +92,20 @@ export function createMCPServerFromTools(serverId, tools, metadata) {
         isCustomTool: false,
     });
 }
+/**
+ * Helper to convert schema parameters to JSON Schema format
+ */
+function convertSchemaToJsonSchema(schema) {
+    if (isZodSchema(schema)) {
+        return convertZodToJsonSchema(schema);
+    }
+    // If it's already a JSON Schema object, return as-is
+    if (schema && typeof schema === "object") {
+        return schema;
+    }
+    // Return empty object if no schema
+    return {};
+}
 /**
  * Helper to create a tool with type safety
  */

package/dist/types/common.d.ts

@@ -73,3 +73,101 @@ export declare function getErrorMessage(error: unknown): string;
  * Safe error conversion
  */
 export declare function toErrorInfo(error: unknown): ErrorInfo;
+/**
+ * NeuroLink Native Event System Types
+ */
+/**
+ * Tool execution event for real-time streaming
+ */
+export interface ToolExecutionEvent {
+    type: "tool:start" | "tool:end";
+    tool: string;
+    input?: unknown;
+    result?: unknown;
+    error?: string;
+    timestamp: number;
+    duration?: number;
+    executionId: string;
+}
+/**
+ * Tool execution summary for completed executions
+ */
+export interface ToolExecutionSummary {
+    tool: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    executionId: string;
+    metadata?: {
+        serverId?: string;
+        toolCategory?: "direct" | "custom" | "mcp";
+        isExternal?: boolean;
+    };
+}
+/**
+ * Stream event types for real-time communication
+ */
+export interface StreamEvent {
+    type: "stream:chunk" | "stream:complete" | "stream:error";
+    content?: string;
+    metadata?: JsonObject;
+    timestamp: number;
+}
+/**
+ * Enhanced NeuroLink event types
+ * Flexible interface to support both typed and legacy event patterns
+ */
+export interface NeuroLinkEvents {
+    "tool:start": unknown;
+    "tool:end": unknown;
+    "stream:start": unknown;
+    "stream:end": unknown;
+    "stream:chunk": unknown;
+    "stream:complete": unknown;
+    "stream:error": unknown;
+    "generation:start": unknown;
+    "generation:end": unknown;
+    "response:start": unknown;
+    "response:end": unknown;
+    "externalMCP:serverConnected": unknown;
+    "externalMCP:serverDisconnected": unknown;
+    "externalMCP:serverFailed": unknown;
+    "externalMCP:toolDiscovered": unknown;
+    "externalMCP:toolRemoved": unknown;
+    "externalMCP:serverAdded": unknown;
+    "externalMCP:serverRemoved": unknown;
+    "tools-register:start": unknown;
+    "tools-register:end": unknown;
+    connected: unknown;
+    message: unknown;
+    error: unknown;
+    log: unknown;
+    [key: string]: unknown;
+}
+/**
+ * TypeScript utility for typed EventEmitter
+ * Flexible interface to support both typed and legacy event patterns
+ */
+export interface TypedEventEmitter<TEvents extends Record<string, unknown>> {
+    on<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): this;
+    emit<K extends keyof TEvents>(event: K, ...args: unknown[]): boolean;
+    off<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): this;
+    removeAllListeners<K extends keyof TEvents>(event?: K): this;
+    listenerCount<K extends keyof TEvents>(event: K): number;
+    listeners<K extends keyof TEvents>(event: K): Array<(...args: unknown[]) => void>;
+}
+/**
+ * Tool execution context for tracking
+ */
+export interface ToolExecutionContext {
+    executionId: string;
+    tool: string;
+    startTime: number;
+    endTime?: number;
+    result?: unknown;
+    error?: string;
+    metadata?: JsonObject;
+}

package/dist/types/conversation.d.ts

@@ -32,6 +32,8 @@ export interface SessionMemory {
     sessionId: string;
     /** User identifier (optional) */
     userId?: string;
+    /** Auto-generated conversation title (created on first user message) */
+    title?: string;
     /** Direct message storage - ready for immediate AI consumption */
     messages: ChatMessage[];
     /** When this session was created */
@@ -61,10 +63,26 @@ export interface ConversationMemoryStats {
  * Chat message format for conversation history
  */
 export interface ChatMessage {
-    /** Role of the message sender */
-    role: "user" | "assistant" | "system";
+    /** Role/type of the message */
+    role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
     /** Content of the message */
     content: string;
+    /** Message ID (optional) - for new format */
+    id?: string;
+    /** Timestamp (optional) - for new format */
+    timestamp?: string;
+    /** Tool name (optional) - for tool_call/tool_result messages */
+    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;
+    };
 }
 /**
  * Content format for multimodal messages (used internally)
@@ -129,6 +147,36 @@ export type SessionIdentifier = {
     sessionId: string;
     userId?: string;
 };
+/**
+ * Lightweight session metadata for efficient session listing
+ * Contains only essential information without heavy message arrays
+ */
+export interface SessionMetadata {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * New Redis conversation storage object format
+ * Contains conversation metadata and history in a single object
+ */
+export type RedisConversationObject = {
+    /** Unique conversation identifier (UUID v4) */
+    id: string;
+    /** Auto-generated conversation title */
+    title: string;
+    /** Session identifier */
+    sessionId: string;
+    /** User identifier */
+    userId: string;
+    /** When this conversation was first created */
+    createdAt: string;
+    /** When this conversation was last updated */
+    updatedAt: string;
+    /** Array of conversation messages */
+    messages: ChatMessage[];
+};
 /**
  * Redis storage configuration
  */
@@ -143,6 +191,8 @@ export type RedisStorageConfig = {
     db?: number;
     /** Key prefix for Redis keys (default: 'neurolink:conversation:') */
     keyPrefix?: string;
+    /** Key prefix for user sessions mapping (default: derived from keyPrefix) */
+    userSessionsKeyPrefix?: string;
     /** Time-to-live in seconds (default: 86400, 24 hours) */
     ttl?: number;
     /** Additional Redis connection options */