@juspay/neurolink 9.63.1 → 9.65.0

package/dist/lib/neurolink.js

@@ -62,6 +62,9 @@ import { tracers } from "./telemetry/tracers.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
+import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "./utils/lifecycleCallbacks.js";
+import { resolveLifecycleTimeoutMs } from "./utils/lifecycleTimeout.js";
+import { cloneOptionsForCallIsolation } from "./utils/cloneOptions.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
@@ -333,7 +336,30 @@ export function markStreamProviderEmittedGenerationEnd(options) {
         ctx.providerEmitted = true;
     }
 }
+/**
+ * Symbol-based brand for cross-module identification without circular imports.
+ *
+ * Provider constructors receive `sdk?: unknown` (the factory layer's
+ * contract). Rather than duck-typing via `"getInMemoryServers" in sdk`,
+ * use `isNeuroLink(value)` from this module to do a brand check —
+ * survives minification AND doesn't rely on method-name stability.
+ */
+export const NEUROLINK_BRAND = Symbol.for("@juspay/neurolink/sdk-brand");
+/**
+ * Type-guard for opaque values that should be a {@link NeuroLink} instance.
+ *
+ * Designed for the provider-factory boundary where TS can't carry the type
+ * through `UnknownRecord` without forcing every caller into a circular
+ * dependency. Cheap to call and unaffected by minification.
+ */
+export function isNeuroLink(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[NEUROLINK_BRAND] === true);
+}
 export class NeuroLink {
+    /** @internal Brand for cross-module identification — see {@link isNeuroLink}. */
+    [NEUROLINK_BRAND] = true;
     mcpInitialized = false;
     mcpSkipped = false;
     mcpInitPromise = null;
@@ -2753,7 +2779,66 @@ Current user's request: ${currentInput}`;
      * @since 1.0.0
      */
     async generate(optionsOrPrompt) {
-        return this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan)));
+        // Defensive call-isolation clone — mirrors stream(): downstream
+        // generate-prep (memory retrieval, orchestration, RAG/MCP tool
+        // injection) mutates nested branches on the caller-supplied options
+        // object. Without cloning here, callers reusing a single options
+        // bag across generate() calls accumulate state across them.
+        // String prompts are immutable, so they pass through.
+        if (typeof optionsOrPrompt !== "string") {
+            optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
+        }
+        const startedAt = Date.now();
+        try {
+            return await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan)));
+        }
+        catch (error) {
+            // Lifecycle middleware (wrapGenerate.catch in builtin/lifecycle.ts)
+            // stamps errors it already surfaced with the shared Symbol marker
+            // (see utils/lifecycleCallbacks.ts). For errors thrown BEFORE the
+            // language model was wrapped (e.g. unknown provider name,
+            // validation failures, factory exceptions), the mark is absent —
+            // fire the consumer's onError here so it sees every failure path.
+            // Awaited so async handlers fully settle before generate()
+            // rethrows, matching the middleware-managed path.
+            await this.fireConsumerOnErrorIfNotFired(optionsOrPrompt, error, startedAt);
+            throw error;
+        }
+    }
+    async fireConsumerOnErrorIfNotFired(optionsOrPrompt, error, startedAt) {
+        if (hasLifecycleErrorFired(error)) {
+            return;
+        }
+        if (typeof optionsOrPrompt !== "object" || optionsOrPrompt === null) {
+            return;
+        }
+        const opts = optionsOrPrompt;
+        const userOnError = opts.onError;
+        if (!userOnError) {
+            return;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        // Bound the consumer callback so a never-settling handler can't hang
+        // generate()/stream(). The deadline honors per-call
+        // `lifecycle.timeoutMs` and the `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env
+        // var (CLI surface), falling back to 5_000. Errors raised here are
+        // logged and swallowed; the original failure still propagates to the
+        // caller because the outer catch re-throws.
+        const lifecycle = opts.middleware?.middlewareConfig?.lifecycle?.config;
+        const timeoutMs = resolveLifecycleTimeoutMs(lifecycle);
+        // Mark the error first so the AI-SDK lifecycle middleware can't
+        // re-fire the same callback if the throw races a parallel catch.
+        markLifecycleErrorFired(err);
+        try {
+            await withTimeout(Promise.resolve(userOnError({
+                error: err,
+                duration: Date.now() - startedAt,
+                recoverable: false,
+            })), timeoutMs, new Error(`consumer onError callback timed out after ${timeoutMs}ms`));
+        }
+        catch (e) {
+            logger.warn("[NeuroLink] consumer onError callback error:", e);
+        }
     }
     /**
      * Curator P2-3: wraps a generate/stream call with the fallback
@@ -2838,15 +2923,23 @@ Current user's request: ${currentInput}`;
             catch {
                 /* listener errors are non-fatal */
             }
+            // Defensive call-isolation clone for the retry attempt. The shallow
+            // spread below would keep nested branches (`input`, `tools`, `memory`,
+            // `rag`, …) pointing at the same objects the previous attempt's
+            // prepare stages mutated — so the retry inherits e.g. memory-retrieved
+            // history appended to `input.messages`, RAG-injected tools, etc.
+            // Re-cloning at the retry boundary mirrors the entry-level isolation
+            // applied in generate()/stream() so each fallback attempt sees a
+            // fresh options bag.
             const retriedOptions = typeof optionsOrPrompt === "object"
-                ? {
+                ? cloneOptionsForCallIsolation({
                     ...optionsOrPrompt,
                     ...(next.provider && { provider: next.provider }),
                     ...(next.model && { model: next.model }),
                     // Strip the fallback hooks so the retry doesn't re-orchestrate.
                     providerFallback: undefined,
                     modelChain: undefined,
-                }
+                })
                 : optionsOrPrompt;
             const retryAttempt = await this.attemptInner(inner, retriedOptions);
             if ("ok" in retryAttempt) {
@@ -2922,6 +3015,12 @@ Current user's request: ${currentInput}`;
         const options = typeof optionsOrPrompt === "string"
             ? { input: { text: optionsOrPrompt } }
             : { ...optionsOrPrompt };
+        // Normalise: all downstream code assumes options.input is defined.
+        // Media-only callers may omit `input` entirely (or pass `input: {}`);
+        // synthesise an empty shell so the rest of the pipeline can rely on it.
+        if (!options.input) {
+            options.input = {};
+        }
         // Dynamic argument resolution — resolve any function-valued options before downstream use
         await this.resolveDynamicOptions(options);
         options.model = resolveModel(options.model, this.modelAliasConfig);
@@ -2932,13 +3031,28 @@ Current user's request: ${currentInput}`;
             ? optionsOrPrompt.length
             : options.input?.text?.length || 0);
         generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
-        // When STT audio is provided, ensure options.input exists (the transcription
-        // will supply the text inside runStandardGenerateRequest) and skip text validation.
+        // Ensure options.input is always an object — callers may omit it for
+        // media-only modes (avatar / music / video) or STT flows. Downstream code
+        // accesses it unconditionally, so we guarantee a non-null object here and
+        // rely on the per-mode checks below to populate / validate the text field.
+        options.input ??= {};
+        // When STT audio is provided, ensure options.input.text is initialised
+        // (the transcription will supply the text inside runStandardGenerateRequest).
         const hasSttAudio = !!(options.stt?.enabled && options.stt?.audio);
-        if (hasSttAudio && !options.input) {
-            options.input = { text: "" };
-        }
-        if (!hasSttAudio) {
+        if (hasSttAudio && !options.input.text) {
+            options.input.text = "";
+        }
+        // Modality dispatch (video / avatar / music) carries the prompt inside
+        // `output.{video|avatar|music}` — input.text is not meaningful for these
+        // modes. Synthesize an empty input.text and skip validation, mirroring
+        // the STT-audio exception above.
+        const isMediaModalityMode = options.output?.mode === "video" ||
+            options.output?.mode === "avatar" ||
+            options.output?.mode === "music";
+        if (isMediaModalityMode && !options.input.text) {
+            options.input.text = "";
+        }
+        if (!hasSttAudio && !isMediaModalityMode) {
             this.assertInputText(options.input?.text, "Input text is required and must be a non-empty string");
         }
         this.enforceSessionBudget(options.maxBudgetUsd);
@@ -2948,6 +3062,16 @@ Current user's request: ${currentInput}`;
     }
     async maybeHandleEarlyGenerateResult(options, generateSpan) {
         if (options.workflow || options.workflowConfig) {
+            // Workflow engine operates on text; media generation modes (avatar, music,
+            // video, ppt) use dedicated code paths and are incompatible with workflows.
+            const workflowMediaMode = options.output?.mode;
+            if (workflowMediaMode === "avatar" ||
+                workflowMediaMode === "music" ||
+                workflowMediaMode === "video" ||
+                workflowMediaMode === "ppt") {
+                throw new Error(`Workflow mode is not compatible with output.mode="${workflowMediaMode}". ` +
+                    'Remove the workflow config or use output.mode="text".');
+            }
             if (options.stt?.enabled && options.stt?.audio) {
                 // prepareGenerateRequest synthesizes input.text = "" for audio-only
                 // calls, so without this guard generateWithWorkflow runs with an
@@ -2959,6 +3083,12 @@ Current user's request: ${currentInput}`;
             }
             return this.generateWithWorkflow(options);
         }
+        if (options.output?.mode === "music") {
+            return this.generateWithMusic(options, generateSpan);
+        }
+        if (options.output?.mode === "avatar") {
+            return this.generateWithAvatar(options, generateSpan);
+        }
         if (options.output?.mode !== "ppt") {
             return null;
         }
@@ -3076,7 +3206,7 @@ Current user's request: ${currentInput}`;
                 originalProvider: options.provider || "auto",
                 orchestratedProvider: orchestratedOptions.provider,
                 orchestratedModel: orchestratedOptions.model,
-                prompt: options.input.text.substring(0, 100),
+                prompt: (options.input?.text ?? "").substring(0, 100),
             });
             Object.assign(options, orchestratedOptions);
             if (orchestratedOptions.model) {
@@ -3121,12 +3251,22 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
-        if (!this.shouldReadMemory(options.memory, options.context?.userId) ||
+        // Media-only modes (avatar, music, video, ppt) do not have a meaningful
+        // text prompt to augment with memory — skip injection to avoid corrupting
+        // the empty/synthesized input.text that was set for these modes.
+        const mediaOnlyMode = options.output?.mode === "avatar" ||
+            options.output?.mode === "music" ||
+            options.output?.mode === "video" ||
+            options.output?.mode === "ppt";
+        if (mediaOnlyMode ||
+            !this.shouldReadMemory(options.memory, options.context?.userId) ||
             !options.context?.userId) {
             return;
         }
         try {
-            options.input.text = await this.retrieveMemory(options.input.text, options.context.userId, options.memory?.additionalUsers);
+            if (options.input) {
+                options.input.text = await this.retrieveMemory(options.input.text ?? "", options.context.userId, options.memory?.additionalUsers);
+            }
             logger.debug("Memory retrieval successful (generate)");
         }
         catch (error) {
@@ -3135,7 +3275,7 @@ Current user's request: ${currentInput}`;
     }
     async buildGenerateTextOptions(options, originalPrompt, factoryResult) {
         const baseOptions = {
-            prompt: options.input.text,
+            prompt: options.input?.text,
             provider: options.provider,
             model: options.model,
             temperature: options.temperature,
@@ -3167,6 +3307,12 @@ Current user's request: ${currentInput}`;
             middleware: options.middleware,
             conversationMessages: options.conversationMessages,
             credentials: options.credentials,
+            // Lifecycle callbacks must reach the provider so non-AI-SDK paths
+            // (Vertex's native @google/genai, native Bedrock, Ollama, etc.) can
+            // invoke them directly. Pipeline A also still receives them via the
+            // wrapped middleware config set by applyGenerateLifecycleMiddleware.
+            onFinish: options.onFinish,
+            onError: options.onError,
         };
         const extraContext = options;
         if (extraContext.sessionId || extraContext.userId) {
@@ -3185,11 +3331,11 @@ Current user's request: ${currentInput}`;
             textOptions.conversationMemoryConfig = this.conversationMemory.config;
             textOptions.originalPrompt = originalPrompt;
         }
-        const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input.text, factoryResult.domainType);
+        const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input?.text || "", factoryResult.domainType);
         if (enhancedPrompt !== textOptions.prompt) {
             textOptions.prompt = enhancedPrompt;
             logger.debug("Enhanced prompt with tool results", {
-                originalLength: options.input.text.length,
+                originalLength: (options.input?.text ?? "").length,
                 enhancedLength: enhancedPrompt.length,
                 toolResults: toolResults.length,
             });
@@ -3198,26 +3344,35 @@ Current user's request: ${currentInput}`;
     }
     finalizeGenerateRequestResult(params) {
         const { generateSpan, options, textOptions, textResult, factoryResult, originalPrompt, startTime, } = params;
-        this.emitter.emit("generation:end", {
-            provider: textResult.provider,
-            responseTime: Date.now() - startTime,
-            toolsUsed: textResult.toolsUsed,
-            timestamp: Date.now(),
-            result: textResult,
-            // Use the effective prompt (which already incorporates STT-transcribed
-            // text for audio-only calls) so observers see the real prompt instead
-            // of an empty string. Falls back through the same chain as before for
-            // text-only calls.
-            prompt: originalPrompt ||
-                options.input?.text ||
-                options.prompt,
-            temperature: textOptions.temperature,
-            maxTokens: textOptions.maxTokens,
-            // A2 fix: Signal that Pipeline A (AI SDK → @langfuse/otel) already
-            // creates a GENERATION observation for this call. The generation:end
-            // listener should skip creating a duplicate Pipeline B span.
-            pipelineAHandled: true,
-        });
+        // Skip the top-level `generation:end` emission when the provider already
+        // emitted it from its native generate path (Vertex / Google AI Studio).
+        // Without this guard, native-path providers would surface TWO events
+        // per generate call (Pipeline A path: 1 from provider native + 1 here;
+        // standard AI-SDK path: 1 here). The observability suite asserts on
+        // emission count and would (and did) fail.
+        const nativeAlreadyEmitted = !!textResult._generationEndEmitted;
+        if (!nativeAlreadyEmitted) {
+            this.emitter.emit("generation:end", {
+                provider: textResult.provider,
+                responseTime: Date.now() - startTime,
+                toolsUsed: textResult.toolsUsed,
+                timestamp: Date.now(),
+                result: textResult,
+                // Use the effective prompt (which already incorporates STT-transcribed
+                // text for audio-only calls) so observers see the real prompt instead
+                // of an empty string. Falls back through the same chain as before for
+                // text-only calls.
+                prompt: originalPrompt ||
+                    options.input?.text ||
+                    options.prompt,
+                temperature: textOptions.temperature,
+                maxTokens: textOptions.maxTokens,
+                // A2 fix: Signal that Pipeline A (AI SDK → @langfuse/otel) already
+                // creates a GENERATION observation for this call. The generation:end
+                // listener should skip creating a duplicate Pipeline B span.
+                pipelineAHandled: true,
+            });
+        }
         this.emitter.emit("response:end", textResult.content || "");
         this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
         const generateResult = {
@@ -3255,7 +3410,18 @@ Current user's request: ${currentInput}`;
             audio: textResult.audio,
             transcription: textResult.transcription,
             video: textResult.video,
+            avatar: textResult.avatar,
+            music: textResult.music,
             ppt: textResult.ppt,
+            // Forward reasoning/reasoningTokens from the provider layer.
+            // BaseProvider's GenerationHandler extracts these from AI-SDK reasoning
+            // parts (DeepSeek's `reasoning_content`, Anthropic thinking blocks,
+            // Gemini thought parts, OpenAI o1) and they're declared on
+            // `GenerateResult`, but the builder previously dropped them on the
+            // floor — so callers asking for `result.reasoning` got `undefined`
+            // even when the model emitted a chain-of-thought.
+            reasoning: textResult.reasoning,
+            reasoningTokens: textResult.reasoningTokens,
             ...(textResult.retries && { retries: textResult.retries }),
         };
         if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
@@ -3348,6 +3514,67 @@ Current user's request: ${currentInput}`;
             ppt: pptResult,
         };
     }
+    /**
+     * Dispatch a music-generation request to the registered music handler
+     * for the provider named in `options.output.music.provider`.
+     */
+    async generateWithMusic(options, generateSpan) {
+        const startTime = Date.now();
+        const musicOptions = options.output?.music;
+        if (!musicOptions) {
+            throw new Error('output.mode="music" requires output.music with at least { provider, prompt }.');
+        }
+        const providerName = musicOptions.provider;
+        if (!providerName) {
+            throw new Error('output.music.provider is required (e.g. "beatoven", "elevenlabs-music", "lyria", "replicate").');
+        }
+        const { MusicProcessor } = await import("./utils/musicProcessor.js");
+        const musicResult = await MusicProcessor.generate(providerName, {
+            ...musicOptions,
+            prompt: musicOptions.prompt ?? options.input?.text ?? "",
+        });
+        generateSpan.setAttribute("neurolink.music.provider", providerName);
+        generateSpan.setAttribute("neurolink.music.bytes", musicResult.size);
+        generateSpan.setStatus({ code: SpanStatusCode.OK });
+        return {
+            content: `Music generated (${providerName}, ${musicResult.size} bytes, ${musicResult.format}).`,
+            finishReason: "stop",
+            provider: providerName,
+            model: musicResult.metadata?.model ?? providerName,
+            usage: undefined,
+            responseTime: Date.now() - startTime,
+            music: musicResult,
+        };
+    }
+    /**
+     * Dispatch an avatar (lip-sync) request to the registered avatar handler
+     * for the provider named in `options.output.avatar.provider`.
+     */
+    async generateWithAvatar(options, generateSpan) {
+        const startTime = Date.now();
+        const avatarOptions = options.output?.avatar;
+        if (!avatarOptions) {
+            throw new Error('output.mode="avatar" requires output.avatar with at least { provider, image, audio|text }.');
+        }
+        const providerName = avatarOptions.provider;
+        if (!providerName) {
+            throw new Error('output.avatar.provider is required (e.g. "d-id", "heygen", "replicate").');
+        }
+        const { AvatarProcessor } = await import("./utils/avatarProcessor.js");
+        const avatarResult = await AvatarProcessor.generate(providerName, avatarOptions);
+        generateSpan.setAttribute("neurolink.avatar.provider", providerName);
+        generateSpan.setAttribute("neurolink.avatar.bytes", avatarResult.size);
+        generateSpan.setStatus({ code: SpanStatusCode.OK });
+        return {
+            content: `Avatar generated (${providerName}, ${avatarResult.size} bytes, ${avatarResult.format}).`,
+            finishReason: "stop",
+            provider: providerName,
+            model: avatarResult.metadata?.model ?? providerName,
+            usage: undefined,
+            responseTime: Date.now() - startTime,
+            avatar: avatarResult,
+        };
+    }
     /**
      * Generate with workflow engine integration
      * Returns both original and processed responses for AB testing
@@ -3357,7 +3584,7 @@ Current user's request: ${currentInput}`;
         logger.debug("[NeuroLink] Executing workflow generation", {
             workflowId: options.workflow,
             hasInlineConfig: !!options.workflowConfig,
-            prompt: options.input.text.substring(0, 100),
+            prompt: (options.input?.text ?? "").substring(0, 100),
             startTime: workflowStartTime,
         });
         // Determine workflow configuration
@@ -3378,7 +3605,7 @@ Current user's request: ${currentInput}`;
         }
         // Execute workflow
         const workflowResult = await runWorkflow(workflowConfig, {
-            prompt: options.input.text,
+            prompt: options.input?.text ?? "",
             conversationHistory: options.conversationMessages
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
@@ -3457,7 +3684,7 @@ Current user's request: ${currentInput}`;
         logger.debug("[NeuroLink] Executing workflow streaming (progressive)", {
             workflowId: options.workflow,
             hasInlineConfig: !!options.workflowConfig,
-            prompt: options.input.text.substring(0, 100),
+            prompt: (options.input?.text ?? "").substring(0, 100),
         });
         // Determine workflow configuration
         let workflowConfig;
@@ -3477,7 +3704,7 @@ Current user's request: ${currentInput}`;
         const { runWorkflowWithStreaming } = await import("./workflow/core/workflowRunner.js");
         // Execute workflow with progressive streaming
         const workflowStream = runWorkflowWithStreaming(workflowConfig, {
-            prompt: options.input.text,
+            prompt: options.input?.text ?? "",
             conversationHistory: options.conversationMessages
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
@@ -4532,10 +4759,22 @@ Current user's request: ${currentInput}`;
             availableTools: transformToolsForMCP(transformToolsToExpectedFormat(availableTools)),
             audio: result.audio,
             video: result.video,
+            avatar: result.avatar,
+            music: result.music,
             ppt: result.ppt,
             imageOutput: result.imageOutput,
             analytics: result.analytics,
             evaluation: result.evaluation,
+            // Forward reasoning from provider so callers asking for `result.reasoning`
+            // (DeepSeek `reasoning_content`, Anthropic thinking, Gemini thought parts,
+            // OpenAI o1) actually receive it.
+            reasoning: result.reasoning,
+            reasoningTokens: result.reasoningTokens,
+            // Propagate the native-emission flag so finalizeGenerateRequestResult
+            // skips the public top-level `generation:end` emission when the
+            // provider already emitted it itself (Vertex / Google AI Studio).
+            _generationEndEmitted: result
+                ._generationEndEmitted,
         };
     }
     /**
@@ -4807,9 +5046,19 @@ Current user's request: ${currentInput}`;
                     evaluation: result.evaluation,
                     audio: result.audio,
                     video: result.video,
+                    avatar: result.avatar,
+                    music: result.music,
                     ppt: result.ppt,
                     // CRITICAL FIX: Include imageOutput for image generation models
                     imageOutput: result.imageOutput,
+                    // Forward reasoning so callers asking for `result.reasoning`
+                    // (DeepSeek `reasoning_content`, Anthropic thinking, Gemini
+                    // thought parts, OpenAI o1) actually receive it.
+                    reasoning: result.reasoning,
+                    reasoningTokens: result.reasoningTokens,
+                    // Propagate native-emission flag — see attemptMCPGeneration comment.
+                    _generationEndEmitted: result
+                        ._generationEndEmitted,
                 };
             }
             catch (error) {
@@ -5032,7 +5281,30 @@ Current user's request: ${currentInput}`;
                 : [],
             optionKeys: Object.keys(options),
         });
-        return this.streamWithIterationFallback(options);
+        // Defensive shallow clone of top-level options + the nested mutable
+        // branches that downstream stages (prepareStreamOptions's memory
+        // retrieval at `options.input.text`, applyStreamOrchestration's merge,
+        // RAG/MCP tool injection, etc.) mutate. Cloning at the entry point
+        // means callers can reuse a single options object across stream()
+        // calls without accumulating mutations across them — the earlier
+        // shallow rebind at the orchestration site only covered the
+        // top-level keys and left `options.input` shared with the caller.
+        options = cloneOptionsForCallIsolation(options);
+        const startedAt = Date.now();
+        try {
+            return await this.streamWithIterationFallback(options);
+        }
+        catch (error) {
+            // Mirror generate(): fire consumer onError for failures that
+            // happened before the wrapped language-model middleware could
+            // observe them (e.g. unknown provider, validation, factory
+            // exceptions). The shared Symbol marker (lifecycleCallbacks.ts)
+            // prevents double-fire when the AI-SDK lifecycle middleware
+            // already handled the error. Awaited so async handlers fully
+            // settle before stream() rethrows.
+            await this.fireConsumerOnErrorIfNotFired(options, error, startedAt);
+            throw error;
+        }
     }
     /**
      * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
@@ -5626,14 +5898,36 @@ Current user's request: ${currentInput}`;
                 streamResult.usage = streamUsage;
             }
             if (!streamResult.analytics) {
+                // CRITICAL: do NOT `await` a Promise-typed analytics here. Bedrock
+                // resolves its analytics from the stream's `finally` block — it
+                // only completes once the consumer has fully iterated the stream.
+                // Awaiting it before returning the StreamResult deadlocks: caller
+                // can't iterate (no stream yet), analytics can't resolve (no
+                // iteration). Pass the Promise through to the consumer instead;
+                // they (or the cost listener below) can await it after consumption.
+                //
+                // The outer StreamResult type (StreamResult.analytics in
+                // src/lib/types/stream.ts) explicitly allows `AnalyticsData |
+                // Promise<AnalyticsData>` — the cast widens the local
+                // `processStreamResult` return type which only declares the
+                // resolved shape.
                 streamResult.analytics =
-                    streamAnalytics instanceof Promise
-                        ? await streamAnalytics
-                        : streamAnalytics;
-            }
-            if (streamResult.analytics?.cost && streamResult.analytics.cost > 0) {
-                this._sessionCostUsd += streamResult.analytics.cost;
-            }
+                    streamAnalytics;
+            }
+            // The cost listener wants a resolved cost, but if the provider gave
+            // us a Promise (Bedrock) we can't tax the stream's return path on it.
+            // Defer cost accumulation: resolve in the background once the analytics
+            // Promise settles. Synchronous analytics (most providers) still fire
+            // immediately because Promise.resolve(non-promise) is sync-ish.
+            Promise.resolve(streamResult.analytics)
+                .then((analytics) => {
+                if (analytics?.cost && analytics.cost > 0) {
+                    this._sessionCostUsd += analytics.cost;
+                }
+            })
+                .catch(() => {
+                /* analytics rejection is non-fatal — cost stays unupdated */
+            });
             this.emitStreamEndEvents(streamResult);
             return this.createStreamResponse(streamResult, processedStream, {
                 providerName,
@@ -5728,7 +6022,7 @@ Current user's request: ${currentInput}`;
         if (this.shouldReadMemory(options.memory, options.context?.userId) &&
             options.context?.userId) {
             try {
-                options.input.text = await this.retrieveMemory(options.input.text, options.context.userId, options.memory?.additionalUsers);
+                options.input.text = await this.retrieveMemory(options.input.text ?? "", options.context.userId, options.memory?.additionalUsers);
                 logger.debug("Memory retrieval successful");
             }
             catch (error) {
@@ -5752,7 +6046,6 @@ Current user's request: ${currentInput}`;
                 // obvious to future readers, and the lint suppression is scoped
                 // narrowly to the one statement that actually rebinds the param.
                 const mergedOptions = { ...options, ...orchestratedOptions };
-                // eslint-disable-next-line no-param-reassign -- see NEW2/Issue 6 above
                 options = mergedOptions;
                 // Re-resolve model alias in case orchestration returned an alias
                 if (orchestratedOptions.model) {

package/dist/lib/providers/amazonBedrock.d.ts

@@ -7,6 +7,16 @@ export declare class AmazonBedrockProvider extends BaseProvider {
     private bedrockClient;
     private conversationHistory;
     private region;
+    /**
+     * Parse the region segment from a Bedrock ARN.
+     * Returns null when the input is not an ARN.
+     *
+     * Supports all AWS partitions:
+     * - `arn:aws:bedrock:…`        (commercial)
+     * - `arn:aws-cn:bedrock:…`     (China)
+     * - `arn:aws-us-gov:bedrock:…` (GovCloud)
+     */
+    private static extractRegionFromArn;
     constructor(modelName?: string, neurolink?: NeuroLink, region?: string, credentials?: {
         accessKeyId?: string;
         secretAccessKey?: string;