@juspay/neurolink 9.64.0 → 9.65.0

package/dist/types/safeFetch.js

@@ -0,0 +1,6 @@
+/**
+ * Types for the safe-fetch utility (SSRF-hardened binary downloads).
+ *
+ * Runtime helper lives in `src/lib/utils/safeFetch.ts`.
+ */
+export {};

package/dist/types/stream.d.ts

@@ -167,7 +167,8 @@ export type StreamChunk = {
 };
 export type StreamOptions = {
     input: {
-        text: string;
+        /** Prompt text. Optional for media-only modes (avatar, music) that are driven by uploaded files rather than a prompt. */
+        text?: string;
         audio?: AudioInputSpec;
         /**
          * Images to include in the request.

package/dist/types/tools.d.ts

@@ -515,3 +515,16 @@ export declare function isToolResult(value: unknown): value is ToolResult;
  * Type guard for tool definition
  */
 export declare function isToolDefinition(value: unknown): value is ToolDefinition;
+/**
+ * Result shape returned by the built-in `bashTool` execute function in
+ * `src/lib/agent/directTools.ts`. Centralised here per CLAUDE.md rule 2
+ * so callers (incl. the mcp-bash test suite) don't need to declare a
+ * local re-shaping of the runtime contract.
+ */
+export type BashToolResult = {
+    success: boolean;
+    code: number;
+    stdout: string;
+    stderr: string;
+    error?: string;
+};

package/dist/types/video.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Video Generation Type Definitions
+ *
+ * Shared types for video generation across providers (Vertex Veo, Kling,
+ * Runway, Replicate-hosted models, etc.).
+ *
+ * The shared base shapes (`VideoOutputOptions`, `VideoGenerationResult`)
+ * are defined in `multimodal.ts` for backwards compatibility — they are
+ * re-exported here so callers can import every video-related type from a
+ * single module.
+ *
+ * @module types/video
+ */
+import type { VideoGenerationResult, VideoOutputOptions } from "./multimodal.js";
+export type { VideoGenerationResult, VideoOutputOptions, } from "./multimodal.js";
+/**
+ * Director-mode transition options.
+ *
+ * Used by handlers that support first-and-last-frame interpolation
+ * (e.g., Veo 3.1 Fast). Providers without transition support omit the
+ * `generateTransition` method on `VideoHandler`.
+ */
+export type VideoTransitionOptions = {
+    aspectRatio?: "9:16" | "16:9" | "1:1" | string;
+    resolution?: "720p" | "1080p";
+    audio?: boolean;
+    /** Duration of the transition clip (Veo accepts 4, 6, or 8). Default 4. */
+    durationSeconds?: 4 | 6 | 8;
+};
+/**
+ * Handler contract for video generation providers.
+ *
+ * Every concrete handler (`VertexVideoHandler`, `KlingVideoHandler`,
+ * `RunwayVideoHandler`, `ReplicateVideoHandler`, …) implements this
+ * interface and registers itself with `VideoProcessor.registerHandler`.
+ *
+ * Implementations MUST enforce their own timeouts. The recommended
+ * total-deadline for image-to-video predictLongRunning APIs is
+ * 3-5 minutes; the per-request fetch timeout is 30 seconds.
+ */
+export type VideoHandler = {
+    /**
+     * Generate a single video clip from an input image and prompt.
+     *
+     * @param image - Input image buffer (JPEG, PNG, or WebP)
+     * @param prompt - Text prompt describing desired video motion / content
+     * @param options - Resolution, length, aspect ratio, audio settings
+     * @param region - Provider-specific region override (e.g. Vertex location)
+     * @returns Buffer + metadata
+     */
+    generate(image: Buffer, prompt: string, options: VideoOutputOptions, region?: string): Promise<VideoGenerationResult>;
+    /**
+     * Optional — generate a transition clip between two frames (Director Mode).
+     *
+     * Providers without first-and-last-frame interpolation omit this method;
+     * `VideoProcessor.generateTransition` will surface a typed error.
+     *
+     * `durationSeconds` is on `VideoTransitionOptions` (default 4).
+     */
+    generateTransition?(firstFrame: Buffer, lastFrame: Buffer, prompt: string, options?: VideoTransitionOptions, region?: string): Promise<Buffer>;
+    /** Validate the provider is configured (auth, base URL, etc.). */
+    isConfigured(): boolean;
+    /** Maximum video duration in seconds supported by this provider. */
+    readonly maxDurationSeconds?: number;
+    /** Supported aspect ratios. */
+    readonly supportedAspectRatios?: readonly ("9:16" | "16:9" | "1:1" | "4:3" | "3:4")[];
+    /** Supported output resolutions. */
+    readonly supportedResolutions?: readonly ("480p" | "720p" | "1080p" | "4k")[];
+};
+/**
+ * Kling (PiAPI) task status response.
+ */
+export type KlingTaskResponse = {
+    status?: string;
+    video_url?: string;
+    output?: {
+        video_url?: string;
+    };
+    error?: string;
+};
+/**
+ * Runway task status response.
+ */
+export type RunwayTaskResponse = {
+    status?: string;
+    output?: string[] | string;
+    error?: string;
+    failure?: string;
+};

package/dist/types/video.js

@@ -0,0 +1,14 @@
+/**
+ * Video Generation Type Definitions
+ *
+ * Shared types for video generation across providers (Vertex Veo, Kling,
+ * Runway, Replicate-hosted models, etc.).
+ *
+ * The shared base shapes (`VideoOutputOptions`, `VideoGenerationResult`)
+ * are defined in `multimodal.ts` for backwards compatibility — they are
+ * re-exported here so callers can import every video-related type from a
+ * single module.
+ *
+ * @module types/video
+ */
+export {};

package/dist/utils/avatarProcessor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Avatar / Lip-sync Generation Processing Utility
+ *
+ * Central registry + dispatch for avatar handlers across providers
+ * (D-ID, HeyGen, Replicate-hosted MuseTalk / SadTalker / Wav2Lip).
+ *
+ * Mirrors the static-handler-registry pattern established by
+ * `TTSProcessor` / `STTProcessor` / `VideoProcessor` / `MusicProcessor`.
+ *
+ * @module utils/avatarProcessor
+ */
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import type { AvatarHandler, AvatarOptions, AvatarResult } from "../types/index.js";
+import { NeuroLinkError } from "./errorHandling.js";
+/**
+ * Avatar-specific error codes.
+ */
+export declare const AVATAR_ERROR_CODES: {
+    readonly PROVIDER_NOT_SUPPORTED: "AVATAR_PROVIDER_NOT_SUPPORTED";
+    readonly PROVIDER_NOT_CONFIGURED: "AVATAR_PROVIDER_NOT_CONFIGURED";
+    readonly GENERATION_FAILED: "AVATAR_GENERATION_FAILED";
+    readonly POLL_TIMEOUT: "AVATAR_POLL_TIMEOUT";
+    readonly INVALID_INPUT: "AVATAR_INVALID_INPUT";
+    readonly AUDIO_REQUIRED: "AVATAR_AUDIO_REQUIRED";
+    readonly IMAGE_REQUIRED: "AVATAR_IMAGE_REQUIRED";
+    readonly AUDIO_TOO_LONG: "AVATAR_AUDIO_TOO_LONG";
+};
+/**
+ * Typed error class for avatar-generation failures.
+ */
+export declare class AvatarError extends NeuroLinkError {
+    constructor(options: {
+        code: string;
+        message: string;
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+/**
+ * Static processor managing the avatar handler registry.
+ */
+export declare class AvatarProcessor {
+    private static readonly handlers;
+    /**
+     * Register an avatar handler for a specific provider.
+     */
+    static registerHandler(providerName: string, handler: AvatarHandler): void;
+    /**
+     * Check if a provider has a registered avatar handler.
+     */
+    static supports(providerName: string): boolean;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    private static getHandler;
+    private static buildSpanAttributes;
+    /**
+     * Generate an avatar video via the registered handler.
+     *
+     * @throws AvatarError on registry miss, handler-not-configured, or
+     *         generation failure.
+     */
+    static generate(provider: string, options: AvatarOptions): Promise<AvatarResult>;
+}

package/dist/utils/avatarProcessor.js

@@ -0,0 +1,171 @@
+/**
+ * Avatar / Lip-sync Generation Processing Utility
+ *
+ * Central registry + dispatch for avatar handlers across providers
+ * (D-ID, HeyGen, Replicate-hosted MuseTalk / SadTalker / Wav2Lip).
+ *
+ * Mirrors the static-handler-registry pattern established by
+ * `TTSProcessor` / `STTProcessor` / `VideoProcessor` / `MusicProcessor`.
+ *
+ * @module utils/avatarProcessor
+ */
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
+import { NeuroLinkError } from "./errorHandling.js";
+import { logger } from "./logger.js";
+/**
+ * Avatar-specific error codes.
+ */
+export const AVATAR_ERROR_CODES = {
+    PROVIDER_NOT_SUPPORTED: "AVATAR_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "AVATAR_PROVIDER_NOT_CONFIGURED",
+    GENERATION_FAILED: "AVATAR_GENERATION_FAILED",
+    POLL_TIMEOUT: "AVATAR_POLL_TIMEOUT",
+    INVALID_INPUT: "AVATAR_INVALID_INPUT",
+    AUDIO_REQUIRED: "AVATAR_AUDIO_REQUIRED",
+    IMAGE_REQUIRED: "AVATAR_IMAGE_REQUIRED",
+    AUDIO_TOO_LONG: "AVATAR_AUDIO_TOO_LONG",
+};
+/**
+ * Typed error class for avatar-generation failures.
+ */
+export class AvatarError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.EXECUTION,
+            severity: options.severity ?? ErrorSeverity.HIGH,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "AvatarError";
+    }
+}
+/**
+ * Static processor managing the avatar handler registry.
+ */
+export class AvatarProcessor {
+    static handlers = new Map();
+    /**
+     * Register an avatar handler for a specific provider.
+     */
+    static registerHandler(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            logger.warn(`[AvatarProcessor] Overwriting existing handler for provider: ${key}`);
+        }
+        this.handlers.set(key, handler);
+        logger.debug(`[AvatarProcessor] Registered avatar handler: ${key}`);
+    }
+    /**
+     * Check if a provider has a registered avatar handler.
+     */
+    static supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders() {
+        return Array.from(this.handlers.keys());
+    }
+    static getHandler(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    static buildSpanAttributes(provider, options) {
+        return {
+            "avatar.operation": "generate",
+            "avatar.provider": provider,
+            "avatar.quality": options.quality,
+            "avatar.format": options.format,
+            "avatar.has_text": options.text !== undefined,
+            "avatar.has_audio": options.audio !== undefined,
+        };
+    }
+    /**
+     * Generate an avatar video via the registered handler.
+     *
+     * @throws AvatarError on registry miss, handler-not-configured, or
+     *         generation failure.
+     */
+    static async generate(provider, options) {
+        const span = SpanSerializer.createSpan(SpanType.MEDIA_GENERATION, "avatar.generate", this.buildSpanAttributes(provider, options));
+        try {
+            if (!options.image) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.IMAGE_REQUIRED,
+                    message: "Avatar generation requires an `image` (Buffer, path, or URL)",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            if (!options.audio && !options.text) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: "Avatar generation requires either `audio` (a Buffer/URL) or `text` (to be TTS'd by the provider).",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            const handler = this.getHandler(provider);
+            if (!handler) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                    message: `Avatar provider "${provider}" is not registered. Available: ${this.listProviders().join(", ")}`,
+                    category: ErrorCategory.CONFIGURATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider, available: this.listProviders() },
+                });
+            }
+            if (!handler.isConfigured()) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                    message: `Avatar provider "${provider}" is not configured. Set the required credentials.`,
+                    category: ErrorCategory.CONFIGURATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            logger.debug(`[AvatarProcessor] Starting avatar generation with provider: ${provider}`);
+            const result = await handler.generate(options);
+            const ended = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(ended);
+            logger.info(`[AvatarProcessor] Generated ${result.size} bytes (${provider})`);
+            return result;
+        }
+        catch (err) {
+            const ended = SpanSerializer.endSpan(span, SpanStatus.ERROR, err instanceof Error ? err.message : String(err));
+            getMetricsAggregator().recordSpan(ended);
+            if (err instanceof AvatarError) {
+                throw err;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `Avatar generation failed for provider "${provider}": ${message}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: { provider },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+}

package/dist/utils/cloneOptions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The set of top-level branches on a `StreamOptions` / `GenerateOptions`
+ * / `DynamicOptions` bag that downstream prep stages mutate. Listed here
+ * once so the runtime clone (`cloneOptionsForCallIsolation`) and any
+ * future test that wants to assert call isolation reference the same
+ * source of truth.
+ *
+ * If you add a new top-level field to `StreamOptions` that gets mutated
+ * by prepareStreamOptions / applyStreamOrchestration / RAG/MCP injection
+ * / memory retrieval / etc., add it here AND add an entry to
+ * `test/helpers/cloneOptions.test.ts` so the isolation guarantee gets
+ * exercised.
+ *
+ * Branches that are deliberately NOT cloned (and why):
+ *   - `signal` / `abortSignal` — `AbortSignal` can't be `structuredClone`d
+ *     and a shallow copy would strip the listener wiring.
+ *   - `tools[name].execute` — function identity is used as a cache key
+ *     downstream; cloning would break that.
+ *   - schema objects (zod / JSON Schema) — large, frequently frozen,
+ *     and not mutated by NeuroLink internals.
+ */
+export declare const CLONE_MUTABLE_OPTION_BRANCHES: readonly ["input", "context", "memory", "tools", "middleware", "rag", "csvOptions", "stt", "tts"];
+/**
+ * Defensive call-isolation clone for stream() / generate()-shaped inputs.
+ *
+ * Shallow-clones the top-level options bag plus every branch listed in
+ * `CLONE_MUTABLE_OPTION_BRANCHES`. Caller-supplied objects can be reused
+ * across calls without accumulating cross-call mutations from
+ * prepareStreamOptions, applyStreamOrchestration, memory retrieval, or
+ * RAG/MCP tool injection.
+ *
+ * Unclonable / by-reference values are deliberately kept by-reference —
+ * cloning them would either fail outright (`structuredClone(AbortSignal)`)
+ * or strip behavior (function identity used as a cache key).
+ */
+export declare function cloneOptionsForCallIsolation<T>(options: T): T;

package/dist/utils/cloneOptions.js

@@ -0,0 +1,61 @@
+/**
+ * The set of top-level branches on a `StreamOptions` / `GenerateOptions`
+ * / `DynamicOptions` bag that downstream prep stages mutate. Listed here
+ * once so the runtime clone (`cloneOptionsForCallIsolation`) and any
+ * future test that wants to assert call isolation reference the same
+ * source of truth.
+ *
+ * If you add a new top-level field to `StreamOptions` that gets mutated
+ * by prepareStreamOptions / applyStreamOrchestration / RAG/MCP injection
+ * / memory retrieval / etc., add it here AND add an entry to
+ * `test/helpers/cloneOptions.test.ts` so the isolation guarantee gets
+ * exercised.
+ *
+ * Branches that are deliberately NOT cloned (and why):
+ *   - `signal` / `abortSignal` — `AbortSignal` can't be `structuredClone`d
+ *     and a shallow copy would strip the listener wiring.
+ *   - `tools[name].execute` — function identity is used as a cache key
+ *     downstream; cloning would break that.
+ *   - schema objects (zod / JSON Schema) — large, frequently frozen,
+ *     and not mutated by NeuroLink internals.
+ */
+export const CLONE_MUTABLE_OPTION_BRANCHES = [
+    "input",
+    "context",
+    "memory",
+    "tools",
+    "middleware",
+    "rag",
+    "csvOptions",
+    "stt",
+    "tts",
+];
+/**
+ * Defensive call-isolation clone for stream() / generate()-shaped inputs.
+ *
+ * Shallow-clones the top-level options bag plus every branch listed in
+ * `CLONE_MUTABLE_OPTION_BRANCHES`. Caller-supplied objects can be reused
+ * across calls without accumulating cross-call mutations from
+ * prepareStreamOptions, applyStreamOrchestration, memory retrieval, or
+ * RAG/MCP tool injection.
+ *
+ * Unclonable / by-reference values are deliberately kept by-reference —
+ * cloning them would either fail outright (`structuredClone(AbortSignal)`)
+ * or strip behavior (function identity used as a cache key).
+ */
+export function cloneOptionsForCallIsolation(options) {
+    if (!options || typeof options !== "object") {
+        return options;
+    }
+    const cloned = { ...options };
+    const o = cloned;
+    for (const branch of CLONE_MUTABLE_OPTION_BRANCHES) {
+        const value = o[branch];
+        if (value && typeof value === "object") {
+            o[branch] = Array.isArray(value)
+                ? [...value]
+                : { ...value };
+        }
+    }
+    return cloned;
+}

package/dist/utils/lifecycleCallbacks.d.ts

@@ -1,13 +1,56 @@
 /**
- * Dedupes per-error invocations of the user-supplied `onError` lifecycle
- * callback. The same thrown error can travel through both the middleware
- * pipeline (which fires `onError` then re-throws) and the top-level
- * generate/stream catch in `neurolink.ts` — without a guard, the consumer
- * callback would fire twice for one logical failure.
+ * Lifecycle callback firing + dedupe.
  *
- * Strategy: stamp a non-enumerable Symbol on the error object the first
- * time a firing site is reached, skip subsequent firings. Symbol.for
- * lets us share the same key across modules without import gymnastics.
+ * The same thrown error can travel through multiple layers that each
+ * want to surface it to the consumer's `onError`:
+ *   - LifecycleMiddleware's `wrapGenerate` / `wrapStream` catch
+ *   - `BaseProvider.wrapStreamWithLifecycleCallbacks` (raw-fetch
+ *     streaming providers that bypass AI SDK middleware)
+ *   - `BaseProvider.fireLifecycleErrorCallback` (top-level provider catch)
+ *   - `NeuroLink.generate()` / `NeuroLink.stream()` (early-resolution
+ *     failures, before the language model is wrapped)
+ *
+ * Without a shared dedupe these layers would fire `onError` multiple
+ * times for one logical failure. This module stamps a non-enumerable
+ * `Symbol.for("neurolink.onErrorFired")` on the error the first time
+ * a firing site is reached; subsequent sites observe the stamp and
+ * skip their own fire.
+ *
+ * `Symbol.for` (rather than a local Symbol) so the same key works
+ * across modules — anyone who can read the symbol can read the stamp.
+ *
+ * Frozen / sealed / non-extensible errors: `Object.defineProperty`
+ * throws, we catch and proceed. Worst case is a single duplicate fire
+ * (the pre-shared-marker behaviour). `WeakSet`-based bookkeeping
+ * would handle this case cleanly but the symbol stamp is preferred
+ * for cross-realm consistency: a Symbol.for-keyed property survives
+ * structuredClone / cross-realm postMessage where a closed-over
+ * WeakSet does not.
  */
 import type { LifecycleErrorPayload, OnErrorCallback } from "../types/index.js";
+/**
+ * Returns true when `markLifecycleErrorFired` or a previous
+ * `fireOnErrorOnce` call has already stamped this error.
+ */
+export declare function hasLifecycleErrorFired(error: unknown): boolean;
+/**
+ * Stamps the error as already-fired without invoking any callback.
+ * Use this from sites that already invoked `onError` via their own
+ * path (e.g. a provider-specific raw-fetch stream wrapper) so the
+ * shared dedupe still works.
+ */
+export declare function markLifecycleErrorFired(error: unknown): void;
+/**
+ * Fire the consumer's `onError` once per logical failure.
+ *
+ * - No-op when `onError` is missing.
+ * - No-op when the error is already stamped (any prior layer fired).
+ * - Otherwise: stamps the error, then invokes the callback.
+ *
+ * The callback is fire-and-forget; rejections are swallowed so a
+ * faulty handler can't mask the original throw. Callers that need
+ * to AWAIT the callback (e.g. to enforce a timeout) should use
+ * `hasLifecycleErrorFired` + `markLifecycleErrorFired` directly and
+ * run the callback themselves.
+ */
 export declare function fireOnErrorOnce(onError: OnErrorCallback | undefined, error: unknown, payload: LifecycleErrorPayload): void;

package/dist/utils/lifecycleCallbacks.js

@@ -1,37 +1,93 @@
 /**
- * Dedupes per-error invocations of the user-supplied `onError` lifecycle
- * callback. The same thrown error can travel through both the middleware
- * pipeline (which fires `onError` then re-throws) and the top-level
- * generate/stream catch in `neurolink.ts` — without a guard, the consumer
- * callback would fire twice for one logical failure.
+ * Lifecycle callback firing + dedupe.
  *
- * Strategy: stamp a non-enumerable Symbol on the error object the first
- * time a firing site is reached, skip subsequent firings. Symbol.for
- * lets us share the same key across modules without import gymnastics.
+ * The same thrown error can travel through multiple layers that each
+ * want to surface it to the consumer's `onError`:
+ *   - LifecycleMiddleware's `wrapGenerate` / `wrapStream` catch
+ *   - `BaseProvider.wrapStreamWithLifecycleCallbacks` (raw-fetch
+ *     streaming providers that bypass AI SDK middleware)
+ *   - `BaseProvider.fireLifecycleErrorCallback` (top-level provider catch)
+ *   - `NeuroLink.generate()` / `NeuroLink.stream()` (early-resolution
+ *     failures, before the language model is wrapped)
+ *
+ * Without a shared dedupe these layers would fire `onError` multiple
+ * times for one logical failure. This module stamps a non-enumerable
+ * `Symbol.for("neurolink.onErrorFired")` on the error the first time
+ * a firing site is reached; subsequent sites observe the stamp and
+ * skip their own fire.
+ *
+ * `Symbol.for` (rather than a local Symbol) so the same key works
+ * across modules — anyone who can read the symbol can read the stamp.
+ *
+ * Frozen / sealed / non-extensible errors: `Object.defineProperty`
+ * throws, we catch and proceed. Worst case is a single duplicate fire
+ * (the pre-shared-marker behaviour). `WeakSet`-based bookkeeping
+ * would handle this case cleanly but the symbol stamp is preferred
+ * for cross-realm consistency: a Symbol.for-keyed property survives
+ * structuredClone / cross-realm postMessage where a closed-over
+ * WeakSet does not.
  */
 const ON_ERROR_FIRED = Symbol.for("neurolink.onErrorFired");
+function stampFired(error) {
+    try {
+        Object.defineProperty(error, ON_ERROR_FIRED, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    catch {
+        // Non-extensible — fall through; worst case is a duplicate fire.
+    }
+}
+/**
+ * Returns true when `markLifecycleErrorFired` or a previous
+ * `fireOnErrorOnce` call has already stamped this error.
+ */
+export function hasLifecycleErrorFired(error) {
+    if (error === null || typeof error !== "object") {
+        return false;
+    }
+    return error[ON_ERROR_FIRED] === true;
+}
+/**
+ * Stamps the error as already-fired without invoking any callback.
+ * Use this from sites that already invoked `onError` via their own
+ * path (e.g. a provider-specific raw-fetch stream wrapper) so the
+ * shared dedupe still works.
+ */
+export function markLifecycleErrorFired(error) {
+    if (error === null || typeof error !== "object") {
+        return;
+    }
+    if (error[ON_ERROR_FIRED] === true) {
+        return;
+    }
+    stampFired(error);
+}
+/**
+ * Fire the consumer's `onError` once per logical failure.
+ *
+ * - No-op when `onError` is missing.
+ * - No-op when the error is already stamped (any prior layer fired).
+ * - Otherwise: stamps the error, then invokes the callback.
+ *
+ * The callback is fire-and-forget; rejections are swallowed so a
+ * faulty handler can't mask the original throw. Callers that need
+ * to AWAIT the callback (e.g. to enforce a timeout) should use
+ * `hasLifecycleErrorFired` + `markLifecycleErrorFired` directly and
+ * run the callback themselves.
+ */
 export function fireOnErrorOnce(onError, error, payload) {
     if (typeof onError !== "function") {
         return;
     }
-    if (error && typeof error === "object") {
-        const errAsRecord = error;
-        if (errAsRecord[ON_ERROR_FIRED]) {
-            return;
-        }
-        try {
-            Object.defineProperty(error, ON_ERROR_FIRED, {
-                value: true,
-                enumerable: false,
-                writable: false,
-                configurable: false,
-            });
-        }
-        catch {
-            // Frozen/sealed error object — proceed without the stamp; the
-            // worst case is a single duplicate fire if multiple sites observe
-            // the same frozen value, which is the pre-existing behaviour.
-        }
+    if (hasLifecycleErrorFired(error)) {
+        return;
+    }
+    if (error !== null && typeof error === "object") {
+        stampFired(error);
     }
     try {
         const result = onError(payload);