@juspay/neurolink 12.49.19 → 12.50.0

package/dist/core/conversationMemoryManager.js

@@ -11,6 +11,7 @@ import { tracers, withSpan } from "../telemetry/index.js";
 import { ConversationMemoryError } from "../types/index.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { logger } from "../utils/logger.js";
+import { assistantTurnIdentity, isTurnAlreadyStored, userTurnIdentity, } from "../utils/conversationTurnIdentity.js";
 import { extractIsErrorText } from "../utils/toolResultStatus.js";
 export class ConversationMemoryManager {
     sessions = new Map();
@@ -82,11 +83,14 @@ export class ConversationMemoryManager {
                     session = this.createNewSession(options.sessionId, options.userId);
                     this.sessions.set(options.sessionId, session);
                 }
+                if (isTurnAlreadyStored(session.messages, options.turnId)) {
+                    return;
+                }
                 const tokenThreshold = options.providerDetails
                     ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, session.tokenThreshold)
                     : this.config.tokenThreshold || 50000;
-                const userMsg = await this.validateAndPrepareMessage(options.userMessage, "user", tokenThreshold);
-                const assistantMsg = await this.validateAndPrepareMessage(options.aiResponse, "assistant", tokenThreshold);
+                const userMsg = await this.validateAndPrepareMessage(options.userMessage, "user", tokenThreshold, userTurnIdentity(options));
+                const assistantMsg = await this.validateAndPrepareMessage(options.aiResponse, "assistant", tokenThreshold, assistantTurnIdentity(options));
                 if (options.events && options.events.length > 0) {
                     assistantMsg.events = options.events;
                 }
@@ -147,8 +151,8 @@ export class ConversationMemoryManager {
      * Validate and prepare a message before adding to session
      * Truncates if message exceeds token limit
      */
-    async validateAndPrepareMessage(content, role, threshold) {
-        const id = randomUUID();
+    async validateAndPrepareMessage(content, role, threshold, identity) {
+        const id = identity?.id ?? randomUUID();
         const tokenCount = TokenUtils.estimateTokenCount(content);
         const maxMessageSize = Math.floor(threshold * MEMORY_THRESHOLD_PERCENTAGE);
         if (tokenCount > maxMessageSize) {
@@ -166,6 +170,7 @@ export class ConversationMemoryManager {
                 content: truncated,
                 timestamp: new Date().toISOString(),
                 metadata: {
+                    ...identity?.metadata,
                     truncated: true,
                 },
             };
@@ -175,6 +180,7 @@ export class ConversationMemoryManager {
             role,
             content,
             timestamp: new Date().toISOString(),
+            ...(identity?.metadata ? { metadata: identity.metadata } : {}),
         };
     }
     /**

package/dist/core/nativeGenerateLoop.d.ts

@@ -28,6 +28,11 @@ import type { NativeGenerateLoopArgs, NativeGenerateLoopResult, StepResult, Step
  * how a caller forces a tool on step 3 only. A hook that returns no
  * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
  *
+ * A forced single-tool choice, from the hook or from the turn, that names a
+ * tool outside `declaredTools` is warned about and not sent. A hook's choice
+ * is then treated as "no override" and the rule decides; the turn's own
+ * choice becomes `"auto"`. Without `declaredTools` nothing is checked.
+ *
  * A hook that THROWS is logged and treated as "no override": the steps
  * already billed are kept and the rule decides. An abort of the turn while
  * the hook is pending is not a hook failure and is re-thrown. The two are

package/dist/core/nativeGenerateLoop.js

@@ -32,6 +32,60 @@ const isForcedToolChoice = (choice) => {
     }
     return false;
 };
+/**
+ * The tool a choice forces by name, when it forces one. Both wire mappers
+ * honour exactly `{ type: "tool", toolName }` with a non-empty name, so
+ * that is the only shape that names a function on the wire.
+ */
+const forcedToolName = (choice) => {
+    if (typeof choice !== "object" || choice === null) {
+        return undefined;
+    }
+    const { type, toolName } = choice;
+    return type === "tool" && typeof toolName === "string" && toolName !== ""
+        ? toolName
+        : undefined;
+};
+/**
+ * The name a choice forces when `declaredTools` is known and lacks it, else
+ * undefined. Own keys only: the live record may have a null prototype or be
+ * keyed by a name such as "constructor".
+ */
+const undeclaredForcedToolName = (choice, declaredTools) => {
+    if (!declaredTools) {
+        return undefined;
+    }
+    const name = forcedToolName(choice);
+    return name !== undefined && !Object.hasOwn(declaredTools, name)
+        ? name
+        : undefined;
+};
+/**
+ * A forced choice for a tool the request does not declare is dropped for the
+ * step rather than sent, so a stale hook or a platform-gated tool degrades
+ * the turn to the model's own choice instead of failing it with a 400.
+ */
+const warnUndeclaredForcedTool = (toolName, step, source) => {
+    logger.warn(source === "prepareStep"
+        ? `prepareStep forced tool "${toolName}" at step ${step}, but the request does not declare it; ignoring the override for this step`
+        : `toolChoice forces tool "${toolName}" at step ${step}, but the request does not declare it; using "auto" for this step`, { toolName, step, source });
+};
+/**
+ * The names this request actually carries, in the record shape
+ * `declaredTools` takes. The loop sends `args.tools`, built once by the
+ * caller; `args.toolsRecord` can hold more (discovery hydrates into it, and
+ * this loop never re-declares), so only `tools` answers "is it offered".
+ * Null prototype: a tool may be named `__proto__` or `constructor`.
+ */
+const declaredToolRecord = (tools) => {
+    const declared = Object.create(null);
+    for (const tool of tools ?? []) {
+        if (typeof tool.name === "string") {
+            declared[tool.name] = true;
+        }
+    }
+    return declared;
+};
 /**
  * `toolChoiceSteps` is a count of leading steps, so anything but a
  * non-negative integer is meaningless. Fall back to the default with a WARN
@@ -127,6 +181,11 @@ const abortReason = (signal) => {
  * how a caller forces a tool on step 3 only. A hook that returns no
  * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
  *
+ * A forced single-tool choice, from the hook or from the turn, that names a
+ * tool outside `declaredTools` is warned about and not sent. A hook's choice
+ * is then treated as "no override" and the rule decides; the turn's own
+ * choice becomes `"auto"`. Without `declaredTools` nothing is checked.
+ *
  * A hook that THROWS is logged and treated as "no override": the steps
  * already billed are kept and the rule decides. An abort of the turn while
  * the hook is pending is not a hook failure and is re-thrown. The two are
@@ -156,16 +215,27 @@ export async function resolveStepToolChoice(input) {
         }
         warnIgnoredPrepareStepFields(prepared);
         if (prepared?.toolChoice !== undefined) {
-            return prepared.toolChoice;
+            const undeclaredPrepared = undeclaredForcedToolName(prepared.toolChoice, input.declaredTools);
+            if (undeclaredPrepared === undefined) {
+                return prepared.toolChoice;
+            }
+            warnUndeclaredForcedTool(undeclaredPrepared, input.step, "prepareStep");
         }
     }
     if (input.base === undefined) {
         return undefined;
     }
-    if (!isForcedToolChoice(input.base) ||
-        input.step < normalizeToolChoiceSteps(input.toolChoiceSteps)) {
+    if (!isForcedToolChoice(input.base)) {
+        return input.base;
+    }
+    if (input.step >= normalizeToolChoiceSteps(input.toolChoiceSteps)) {
+        return "auto";
+    }
+    const undeclaredBase = undeclaredForcedToolName(input.base, input.declaredTools);
+    if (undeclaredBase === undefined) {
         return input.base;
     }
+    warnUndeclaredForcedTool(undeclaredBase, input.step, "base");
     return "auto";
 }
 /**
@@ -356,6 +426,7 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
                 steps: stepRecords,
                 maxSteps: args.maxSteps,
                 model: args.modelId,
+                declaredTools: declaredToolRecord(args.tools),
                 ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
             })
             : undefined;

package/dist/core/redisConversationMemoryManager.js

@@ -15,6 +15,7 @@ import { withTimeout } from "../utils/errorHandling.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
 import { logger } from "../utils/logger.js";
+import { assistantTurnIdentity, isTurnAlreadyStored, turnMessageFields, userTurnIdentity, } from "../utils/conversationTurnIdentity.js";
 import { extractIsErrorText } from "../utils/toolResultStatus.js";
 import { deserializeConversation, encodeStoredMessages, getSessionMessagesKey, MESSAGES_KEY_SUFFIX, isSessionMessagesKey, parseStoredMessages, serializeConversationMetadata, usesSplitMessageStorage, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
 const redisTracer = tracers.redis;
@@ -393,6 +394,9 @@ export class RedisConversationMemoryManager {
                 const redisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId);
                 const conversationData = await this.redisClient.get(redisKey);
                 let conversation = await this.hydrateMessages(deserializeConversation(conversationData), redisKey);
+                if (isTurnAlreadyStored(conversation?.messages ?? [], options.turnId)) {
+                    return;
+                }
                 // Split-storage bookkeeping: whether this session already keeps its
                 // messages in the companion LIST, and how many it held before this
                 // turn — so only the new ones are appended rather than rewriting the
@@ -457,7 +461,7 @@ export class RedisConversationMemoryManager {
                     ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, conversation.tokenThreshold)
                     : this.config.tokenThreshold || 50000;
                 const userMsg = {
-                    id: randomUUID(),
+                    ...turnMessageFields(userTurnIdentity(options)),
                     timestamp: options.startTimeStamp?.toISOString() || this.generateTimestamp(),
                     role: "user",
                     content: options.userMessage,
@@ -471,14 +475,11 @@ export class RedisConversationMemoryManager {
                     conversation.messages.push(...options.skillMessages);
                 }
                 const assistantMsg = {
-                    id: randomUUID(),
+                    ...turnMessageFields(assistantTurnIdentity(options, options.thoughtSignature)),
                     timestamp: this.generateTimestamp(),
                     role: "assistant",
                     content: options.aiResponse,
                     events: options.events || undefined,
-                    ...(options.thoughtSignature && {
-                        metadata: { thoughtSignature: options.thoughtSignature },
-                    }),
                 };
                 conversation.messages.push(assistantMsg);
                 // Store API-reported token counts if available

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { DecisionCallerOptions, DecisionLimitsQuery, DecisionLimitsReading, DecisionOptions, DecisionResult, AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -2120,6 +2120,57 @@ export declare class NeuroLink {
      * @returns Array of ChatMessage objects, or empty array if session doesn't exist
      */
     getSessionMessages(sessionId: string, userId?: string): Promise<ChatMessage[]>;
+    /**
+     * Record one finished turn from a transport that does not go through
+     * generate()/stream() — a voice call — into the same conversation memory
+     * typed chat uses: same key, same manager, same summarization and title
+     * handling, same optional long-term memory write.
+     *
+     * Identity is never defaulted: `userId` is required, because typed chat falls
+     * back to a shared placeholder user when it is missing and a spoken turn must
+     * never be filed there. Recording the same `turnId` twice stores it once, so
+     * a caller can retry after an ambiguous failure.
+     *
+     * A turn with a blank user message, or a blank response and no tool events,
+     * is not stored (an empty assistant message makes some providers reject the
+     * next request); the result says which. Storage failures throw — the caller
+     * decides whether to retry or to carry on without the turn.
+     *
+     * @throws NeuroLinkError (INVALID_PARAMETERS) for a bad sessionId or userId
+     * @throws NeuroLinkError (MISSING_CONFIGURATION) when conversation memory is not enabled
+     * @throws ConversationMemoryError (STORAGE_ERROR) when the store rejects the write
+     */
+    recordConversationTurn(options: RecordConversationTurnOptions): Promise<RecordConversationTurnResult>;
+    /**
+     * The most recent user/assistant messages of a conversation, bounded, for
+     * seeding a model that has no history of its own — a voice model at call
+     * start. Summaries, pinned skills, tool traffic and blank messages are left
+     * out; the oldest messages are dropped first when `maxChars` would be
+     * exceeded. Best effort: a missing conversation, disabled memory or a read
+     * failure yields an empty seed and never throws, because a call must start
+     * either way.
+     */
+    getConversationSeed(options: ConversationSeedOptions): Promise<ConversationSeedMessage[]>;
+    /**
+     * Whether a conversation already holds messages under this user. A client
+     * may name the conversation a call appends to; the server accepts the name
+     * only when this is true for the user the session is verified as.
+     */
+    conversationExists(options: {
+        sessionId: string;
+        userId: string;
+    }): Promise<boolean>;
+    /**
+     * Whether a stored conversation is owned by someone other than `userId`.
+     *
+     * The Redis manager includes the user in the key, so a different user simply
+     * never finds the conversation. The in-process manager keys sessions by id
+     * alone and only records the owner, so ownership is checked here: a session
+     * that exists with no recorded owner, or another one, is not `userId`'s.
+     */
+    private isOwnedByAnotherUser;
+    /** Shared identity check for the voice-memory methods. */
+    private static assertConversationIdentity;
     /**
      * Replace the entire messages array for a session.
      * @param sessionId - The session ID to update

package/dist/neurolink.js

@@ -9342,6 +9342,9 @@ Current user's request: ${currentInput}`;
                     ...(pendingSkillMessages.length > 0
                         ? { skillMessages: pendingSkillMessages }
                         : {}),
+                    ...(enhancedOptions.modality
+                        ? { modality: enhancedOptions.modality }
+                        : {}),
                 });
                 this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                 logger.debug("[NeuroLink.stream] Stored conversation turn with events", {
@@ -12757,6 +12760,198 @@ Current user's request: ${currentInput}`;
         }
         return await this.conversationMemory.getSessionMessages(sessionId, userId);
     }
+    /**
+     * Record one finished turn from a transport that does not go through
+     * generate()/stream() — a voice call — into the same conversation memory
+     * typed chat uses: same key, same manager, same summarization and title
+     * handling, same optional long-term memory write.
+     *
+     * Identity is never defaulted: `userId` is required, because typed chat falls
+     * back to a shared placeholder user when it is missing and a spoken turn must
+     * never be filed there. Recording the same `turnId` twice stores it once, so
+     * a caller can retry after an ambiguous failure.
+     *
+     * A turn with a blank user message, or a blank response and no tool events,
+     * is not stored (an empty assistant message makes some providers reject the
+     * next request); the result says which. Storage failures throw — the caller
+     * decides whether to retry or to carry on without the turn.
+     *
+     * @throws NeuroLinkError (INVALID_PARAMETERS) for a bad sessionId or userId
+     * @throws NeuroLinkError (MISSING_CONFIGURATION) when conversation memory is not enabled
+     * @throws ConversationMemoryError (STORAGE_ERROR) when the store rejects the write
+     */
+    async recordConversationTurn(options) {
+        const { sessionId, userId, turnId } = options;
+        NeuroLink.assertConversationIdentity(sessionId, userId);
+        const identity = { sessionId, userId, ...(turnId ? { turnId } : {}) };
+        if (!options.userMessage.trim()) {
+            return { recorded: false, reason: "empty-user-message", ...identity };
+        }
+        const hasToolEvents = (options.events ?? []).some((event) => event.type === "tool:start" || event.type === "tool:end");
+        if (!options.aiResponse.trim() && !hasToolEvents) {
+            return { recorded: false, reason: "empty-response", ...identity };
+        }
+        await this.initializeConversationMemoryForGeneration(options.requestId ?? `record-turn-${Date.now()}`, Date.now(), process.hrtime.bigint());
+        if (!this.conversationMemory) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (await this.isOwnedByAnotherUser(sessionId, userId)) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.INVALID_PARAMETERS,
+                message: "The conversation belongs to another user",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        const memStoreStart = Date.now();
+        try {
+            await this.conversationMemory.storeConversationTurn({
+                sessionId,
+                userId,
+                userMessage: options.userMessage,
+                aiResponse: options.aiResponse,
+                startTimeStamp: options.startTime,
+                ...(options.provider && options.model
+                    ? {
+                        providerDetails: {
+                            provider: options.provider,
+                            model: options.model,
+                        },
+                    }
+                    : {}),
+                enableSummarization: options.enableSummarization,
+                events: options.events?.length ? options.events : undefined,
+                requestId: options.requestId,
+                ...(options.modality ? { modality: options.modality } : {}),
+                ...(turnId ? { turnId } : {}),
+                ...(options.interrupted ? { interrupted: true } : {}),
+                ...(options.callEnded ? { callEnded: true } : {}),
+            });
+            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "record" }, Date.now() - memStoreStart, SpanStatus.OK);
+        }
+        catch (error) {
+            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "record" }, Date.now() - memStoreStart, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        if (this.shouldWriteMemory(options.memory, userId, options.aiResponse)) {
+            this.storeMemoryInBackground({
+                prompt: options.userMessage,
+                response: options.aiResponse.trim(),
+                userId,
+                sessionId,
+                provider: options.provider ?? "",
+                model: options.model,
+            }, options.memory, { sessionId });
+        }
+        return { recorded: true, ...identity };
+    }
+    /**
+     * The most recent user/assistant messages of a conversation, bounded, for
+     * seeding a model that has no history of its own — a voice model at call
+     * start. Summaries, pinned skills, tool traffic and blank messages are left
+     * out; the oldest messages are dropped first when `maxChars` would be
+     * exceeded. Best effort: a missing conversation, disabled memory or a read
+     * failure yields an empty seed and never throws, because a call must start
+     * either way.
+     */
+    async getConversationSeed(options) {
+        const { sessionId, userId } = options;
+        const maxTurns = Math.max(0, Math.floor(options.maxTurns ?? 10));
+        const maxChars = Math.max(0, Math.floor(options.maxChars ?? 6000));
+        try {
+            NeuroLink.assertConversationIdentity(sessionId, userId);
+            const stored = await this.getSessionMessages(sessionId, userId);
+            const spoken = [];
+            for (const message of stored) {
+                if ((message.role !== "user" && message.role !== "assistant") ||
+                    message.metadata?.isSummary ||
+                    message.metadata?.isSkill ||
+                    typeof message.content !== "string" ||
+                    !message.content.trim()) {
+                    continue;
+                }
+                spoken.push({
+                    role: message.role,
+                    content: message.content,
+                    ...(message.metadata?.modality
+                        ? { modality: message.metadata.modality }
+                        : {}),
+                });
+            }
+            const recent = spoken.slice(-(maxTurns * 2));
+            let used = 0;
+            let firstKept = recent.length;
+            for (let index = recent.length - 1; index >= 0; index -= 1) {
+                used += recent[index].content.length;
+                if (used > maxChars) {
+                    break;
+                }
+                firstKept = index;
+            }
+            return recent.slice(firstKept);
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] getConversationSeed failed, starting unseeded", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * Whether a conversation already holds messages under this user. A client
+     * may name the conversation a call appends to; the server accepts the name
+     * only when this is true for the user the session is verified as.
+     */
+    async conversationExists(options) {
+        NeuroLink.assertConversationIdentity(options.sessionId, options.userId);
+        const stored = await this.getSessionMessages(options.sessionId, options.userId);
+        if (stored.length === 0) {
+            return false;
+        }
+        return !(await this.isOwnedByAnotherUser(options.sessionId, options.userId));
+    }
+    /**
+     * Whether a stored conversation is owned by someone other than `userId`.
+     *
+     * The Redis manager includes the user in the key, so a different user simply
+     * never finds the conversation. The in-process manager keys sessions by id
+     * alone and only records the owner, so ownership is checked here: a session
+     * that exists with no recorded owner, or another one, is not `userId`'s.
+     */
+    async isOwnedByAnotherUser(sessionId, userId) {
+        const memory = this.conversationMemory;
+        if (!memory || memory.isRedisConfigured) {
+            return false;
+        }
+        const session = await memory.getSession(sessionId);
+        return session !== undefined && session.userId !== userId;
+    }
+    /** Shared identity check for the voice-memory methods. */
+    static assertConversationIdentity(sessionId, userId) {
+        const problem = typeof sessionId !== "string" || !sessionId.trim()
+            ? "sessionId must be a non-empty string"
+            : sessionId.includes(":")
+                ? 'sessionId must not contain ":"'
+                : typeof userId !== "string" || !userId.trim()
+                    ? "userId must be a non-empty string"
+                    : undefined;
+        if (problem) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.INVALID_PARAMETERS,
+                message: problem,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+    }
     /**
      * Replace the entire messages array for a session.
      * @param sessionId - The session ID to update

package/dist/providers/anthropic/client.js

@@ -2008,6 +2008,7 @@ export class AnthropicProvider extends BaseProvider {
                             steps: stepRecords,
                             maxSteps,
                             model: modelId,
+                            declaredTools: toolsRecord,
                             ...(abortSignal ? { abortSignal } : {}),
                         })))
                     : undefined;

package/dist/providers/openaiChatCompletionsBase.js

@@ -1741,6 +1741,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                             steps,
                             maxSteps,
                             model: modelId,
+                            declaredTools: toolsRecord,
                             ...(abortSignal ? { abortSignal } : {}),
                         }), wireNameMaps?.toWire)
                         : undefined,

package/dist/types/conversation.d.ts

@@ -295,6 +295,8 @@ export type ToolResultData = {
     /** Error message if execution failed */
     error?: string;
 };
+/** How a conversation turn was entered. */
+export type ConversationModality = "text" | "voice";
 /** Metadata associated with a ChatMessage. */
 export type ChatMessageMetadata = {
     /** Is this a summary message? */
@@ -328,6 +330,22 @@ export type ChatMessageMetadata = {
     thinkingExpanded?: boolean;
     /** Step index for reconstructing parallel vs sequential tool calls */
     stepIndex?: number;
+    /**
+     * How the message was entered: typed (`"text"`) or spoken (`"voice"`).
+     * Absent on every message stored before this field existed, and on typed
+     * turns that did not set it; readers treat absence as `"text"`.
+     */
+    modality?: ConversationModality;
+    /**
+     * Stable id of the voice turn this message belongs to. The stored message
+     * ids are `${turnId}:user` and `${turnId}:assistant`, which is what makes
+     * recording the same turn twice a no-op.
+     */
+    turnId?: string;
+    /** True when the message was cut off (barge-in, or the call ended) before it finished. */
+    interrupted?: boolean;
+    /** True when the call ended while this turn was still open. */
+    callEnded?: boolean;
     /**
      * Head/tail preview of a large tool output.
      * Only present on tool_result messages where the output exceeded truncation limits.
@@ -515,6 +533,97 @@ export type StoreConversationTurnOptions = {
      * for the canonical partition-and-reanchor pattern).
      */
     skillMessages?: ChatMessage[];
+    /**
+     * How the turn was entered. Stamped on both stored messages' metadata when
+     * set; a typed turn that leaves it unset is stored exactly as before.
+     */
+    modality?: ConversationModality;
+    /**
+     * Idempotency key for the turn. When set, the user and assistant messages
+     * are stored with the ids `${turnId}:user` and `${turnId}:assistant`, and a
+     * turn whose assistant id is already in the session's recent messages is
+     * skipped, so a retry after an ambiguous failure cannot duplicate it.
+     */
+    turnId?: string;
+    /** The assistant message was cut off before it finished. */
+    interrupted?: boolean;
+    /** The call ended while this turn was open. */
+    callEnded?: boolean;
+};
+/** Id and metadata a memory manager gives one stored message of a turn. */
+export type TurnMessageIdentity = {
+    /** Stable id for the message, or undefined to let the manager mint a random one. */
+    id: string | undefined;
+    /** Metadata to set on the message, or undefined when there is none to add. */
+    metadata: ChatMessageMetadata | undefined;
+};
+/**
+ * Input to `NeuroLink.recordConversationTurn`: one finished turn from a
+ * transport that does not go through generate()/stream() (a voice call),
+ * written to the same conversation memory typed chat uses.
+ */
+export type RecordConversationTurnOptions = {
+    /** Conversation to append to. Must not contain ":" (it is part of the stored key). */
+    sessionId: string;
+    /**
+     * Owner of the conversation. Required: typed chat falls back to a shared
+     * placeholder user when it is missing, and a spoken turn must never land
+     * there.
+     */
+    userId: string;
+    /** What the person said. Must be non-blank. */
+    userMessage: string;
+    /** What the assistant said (or the closing note for a cut-off turn). Must be non-blank unless `events` carries tool activity. */
+    aiResponse: string;
+    /** How the turn was entered. Stamped on both stored messages. */
+    modality?: ConversationModality;
+    /** Idempotency key. Recording the same `turnId` again is a no-op. */
+    turnId?: string;
+    /** The assistant message was cut off before it finished. */
+    interrupted?: boolean;
+    /** The call ended while this turn was open. */
+    callEnded?: boolean;
+    /** Tool and UI events of the turn, in the shape typed chat stores. */
+    events?: StreamEventSequence[];
+    /** When the turn started. */
+    startTime?: Date;
+    /** Provider and model that answered, for token-threshold selection. */
+    provider?: string;
+    model?: string;
+    /** Observability request identifier. */
+    requestId?: string;
+    /** Per-call override of summarization, as on generate()/stream(). */
+    enableSummarization?: boolean;
+    /** Per-call long-term memory switches, as on generate()/stream(). */
+    memory?: {
+        enabled?: boolean;
+        write?: boolean;
+    };
+};
+/** Outcome of `NeuroLink.recordConversationTurn`. */
+export type RecordConversationTurnResult = {
+    /** False when the turn was deliberately not stored; see `reason`. */
+    recorded: boolean;
+    /** Why nothing was stored. Only set when `recorded` is false. */
+    reason?: "empty-user-message" | "empty-response";
+    sessionId: string;
+    userId: string;
+    turnId?: string;
+};
+/** Options for `NeuroLink.getConversationSeed`. */
+export type ConversationSeedOptions = {
+    sessionId: string;
+    userId: string;
+    /** Most recent user/assistant exchanges to return (default 10). */
+    maxTurns?: number;
+    /** Cap on the total characters returned; the oldest messages are dropped first (default 6000). */
+    maxChars?: number;
+};
+/** One message of a conversation seed. */
+export type ConversationSeedMessage = {
+    role: "user" | "assistant";
+    content: string;
+    modality?: ConversationModality;
 };
 /**
  * Lightweight session metadata for efficient session listing