@juspay/neurolink 11.2.3 → 11.3.0

package/dist/lib/types/loopEngine.d.ts

@@ -0,0 +1,78 @@
+export type AgenticLoopToolCall = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+export type AgenticLoopUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+};
+export type AgenticLoopStepResult<TRaw = unknown> = {
+    text: string;
+    reasoning?: string;
+    toolCalls: AgenticLoopToolCall[];
+    usage: AgenticLoopUsage;
+    /** Provider's own raw stop/finish-reason string, e.g. "tool_use", "MAX_TOKENS" */
+    rawStopReason: string | undefined;
+    /** Adapter-private accumulated response data needed by buildToolResultMessages
+     *  (e.g. Anthropic's ordered content blocks, Gemini's rawResponseParts). */
+    raw: TRaw;
+};
+export type AgenticLoopToolCallResult = AgenticLoopToolCall & {
+    output: unknown;
+    error?: string;
+    permanentlyFailed?: boolean;
+};
+export type AgenticLoopStepRequest = {
+    raw: unknown;
+};
+export type AgenticLoopReclaimResult<TConversation> = {
+    conversation: TConversation;
+};
+export type AgenticLoopToolFailureBreaker = {
+    maxRetries: number;
+};
+export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
+    readonly providerLabel: string;
+    readonly maxSteps: number;
+    /** Pre-existing per-family flat timeout, used as createTurnClock's deadline default. */
+    readonly defaultTurnTimeoutMs?: number;
+    readonly stallTimeoutMs?: number;
+    /** Set only for adapter instances whose client has the TOOL_NOT_FOUND strike breaker today: both Gemini adapters (AI Studio, Vertex+Gemini) AND the Vertex+Claude call to createAnthropicLoopAdapter — NOT the native-Anthropic call to that same factory, and not Bedrock. See Verified Fact 4. */
+    readonly toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest;
+    executeStep(request: AgenticLoopStepRequest, channel: {
+        push(chunk: {
+            content: string;
+        }): void;
+    }, signal: AbortSignal): Promise<AgenticLoopStepResult<TRaw>>;
+    buildToolResultMessages(conversation: TConversation, stepResult: AgenticLoopStepResult<TRaw>, toolResults: AgenticLoopToolCallResult[]): TConversation;
+    mapFinishReason(rawStopReason: string | undefined, hadToolCalls: boolean): string;
+    /** Optional: in-turn context-budget reclaim, called once per step before buildStepRequest. */
+    planReclaim?(conversation: TConversation, step: number): AgenticLoopReclaimResult<TConversation> | undefined;
+    /** Optional: Vertex+Gemini-only single-retry-on-malformed-call. */
+    isMalformedStep?(stepResult: AgenticLoopStepResult<TRaw>): boolean;
+    buildMalformedRetryNote?(conversation: TConversation): TConversation;
+};
+export type AgenticLoopOptions = {
+    tools?: Record<string, {
+        execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;
+    }>;
+    abortSignal?: AbortSignal;
+};
+export type AgenticLoopResult<TConversation> = {
+    text: string;
+    toolCalls: AgenticLoopToolCall[];
+    toolExecutions: Array<{
+        name: string;
+        input: Record<string, unknown>;
+        output: unknown;
+    }>;
+    usage: AgenticLoopUsage;
+    finishReason: string;
+    rawStopReason: string | undefined;
+    conversation: TConversation;
+};

package/dist/lib/types/loopEngine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loopEngine.js.map

package/dist/lib/types/nativeTools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wire formats accepted by `toNativeToolDeclarations` (src/lib/core/nativeToolFormat.ts).
+ * `"input_schema"` is Anthropic's native Messages-API tool shape;
+ * `"functionDeclarations"` is the @google/genai SDK shape shared by the
+ * Gemini-family native providers (Google AI Studio, Vertex+Gemini).
+ */
+export type NativeToolFormat = "input_schema" | "functionDeclarations";
+/** A single tool declaration in Anthropic's native `input_schema` wire format. */
+export type NativeAnthropicToolDeclaration = {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+    cache_control?: {
+        type: "ephemeral";
+    };
+};

package/dist/lib/types/nativeTools.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=nativeTools.js.map

package/dist/lib/types/openaiCompatible.d.ts

@@ -203,8 +203,6 @@ export type OpenAICompatSSEResult = {
 export type OpenAICompatStreamChunk = {
     content: string;
     reasoning?: string;
-} | {
-    done: true;
 };
 export type ToolExecutionSummaryInternal = {
     toolCallId: string;
@@ -232,6 +230,8 @@ export type StreamLoopArgs = {
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];
     pushChunk: (chunk: OpenAICompatStreamChunk) => void;
+    /** Signals the channel that no further chunks will arrive (success or error path alike). */
+    closeChannel: () => void;
     resolveUsage: (u: {
         promptTokens: number;
         completionTokens: number;

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

@@ -1740,19 +1740,6 @@ export type CollectedChunkResult = {
      */
     reasoningTokens?: number;
 };
-/** Push-based text channel for incremental streaming. */
-export type TextChannel = {
-    /** Push a text chunk to the consumer. */
-    push: (text: string) => void;
-    /** Signal that no more chunks will arrive. */
-    close: () => void;
-    /** Signal that the producer encountered a fatal error. */
-    error: (err: unknown) => void;
-    /** Async iterable consumed by the StreamResult. */
-    iterable: AsyncIterable<{
-        content: string;
-    }>;
-};
 /** Language model object shape (LanguageModelV2/V3). */
 export type LanguageModelObject = {
     readonly modelId: string;

package/dist/lib/types/streaming.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer. Replaces the two
+ * independently-invented primitives this type unifies: the OpenAI-family
+ * `createChunkQueue` (pull-based, in-band `{done:true}` sentinel) and the
+ * Gemini-family `createTextChannel` (push-based, out-of-band close/error).
+ */
+export type StreamChannel<T = {
+    content: string;
+}> = {
+    push(value: T): void;
+    close(): void;
+    error(err: unknown): void;
+    readonly iterable: AsyncIterable<T>;
+};

package/dist/lib/types/streaming.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=streaming.js.map

package/dist/lib/utils/avatarProcessor.d.ts

@@ -43,7 +43,7 @@ export declare class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export declare class AvatarProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register an avatar handler for a specific provider.
      */
@@ -63,6 +63,10 @@ export declare class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): AvatarHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate an avatar video via the registered handler.

package/dist/lib/utils/avatarProcessor.js

@@ -13,6 +13,7 @@ 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";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Avatar-specific error codes.
  */
@@ -47,38 +48,26 @@ export class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export class AvatarProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("AvatarProcessor");
     /**
      * 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);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, 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());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered avatar handler by provider name.
@@ -87,7 +76,13 @@ export class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/lib/utils/musicProcessor.d.ts

@@ -42,7 +42,7 @@ export declare class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export declare class MusicProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register a music handler for a specific provider.
      */
@@ -62,6 +62,10 @@ export declare class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): MusicHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate a music track via the registered handler.

package/dist/lib/utils/musicProcessor.js

@@ -13,6 +13,7 @@ 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";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Music-specific error codes.
  */
@@ -46,38 +47,26 @@ export class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export class MusicProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("MusicProcessor");
     /**
      * Register a music 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(`[MusicProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[MusicProcessor] Registered music handler: ${key}`);
     }
     /**
      * Check if a provider has a registered music handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered music handler by provider name.
@@ -86,7 +75,13 @@ export class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/lib/utils/sttProcessor.d.ts

@@ -27,11 +27,10 @@ import type { STTOptions, STTResult, STTHandler } from "../types/index.js";
 export declare class STTProcessor {
     /**
      * Handler registry mapping provider names to STT handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Default maximum audio duration for STT transcription (in seconds)
      *
@@ -72,6 +71,15 @@ export declare class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): STTHandler | undefined;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    /**
+     * Removes every registered STT handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers(): void;
     /**
      * Check if a provider is supported (has a registered STT handler)
      *

package/dist/lib/utils/sttProcessor.js

@@ -10,6 +10,7 @@ import { logger } from "./logger.js";
 import { STT_ERROR_CODES } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { STTError } from "../voice/errors.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 /**
  * STT processor class for orchestrating speech-to-text operations
@@ -31,11 +32,10 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 export class STTProcessor {
     /**
      * Handler registry mapping provider names to STT handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    static handlers = new Map();
+    static registry = new HandlerRegistry("STTProcessor");
     /**
      * Default maximum audio duration for STT transcription (in seconds)
      *
@@ -66,17 +66,10 @@ export class STTProcessor {
      * ```
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const normalizedName = providerName.toLowerCase();
-        if (this.handlers.has(normalizedName)) {
-            logger.warn(`[STTProcessor] Overwriting existing handler for provider: ${normalizedName}`);
-        }
-        this.handlers.set(normalizedName, handler);
+        const normalizedName = providerName
+            ? providerName.toLowerCase()
+            : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[STTProcessor] Registered STT handler for provider: ${normalizedName}`);
     }
     /**
@@ -89,8 +82,20 @@ export class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName) {
-        const normalizedName = providerName.toLowerCase();
-        return this.handlers.get(normalizedName);
+        return this.registry.get(providerName);
+    }
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders() {
+        return this.registry.list();
+    }
+    /**
+     * Removes every registered STT handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     /**
      * Check if a provider is supported (has a registered STT handler)
@@ -110,8 +115,7 @@ export class STTProcessor {
             logger.error("[STTProcessor] Provider name is required for supports check");
             return false;
         }
-        const normalizedName = providerName.toLowerCase();
-        const isSupported = this.handlers.has(normalizedName);
+        const isSupported = this.registry.supports(providerName);
         if (!isSupported) {
             logger.debug(`[STTProcessor] Provider ${providerName} is not supported`);
         }
@@ -192,7 +196,7 @@ export class STTProcessor {
                     retriable: false,
                     context: {
                         provider,
-                        availableProviders: Array.from(this.handlers.keys()),
+                        availableProviders: this.registry.list(),
                     },
                 });
             }

package/dist/lib/utils/ttsProcessor.d.ts

@@ -54,11 +54,10 @@ export declare class TTSError extends NeuroLinkError {
 export declare class TTSProcessor {
     /**
      * Handler registry mapping provider names to TTS handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Default maximum text length for TTS synthesis (in bytes)
      *
@@ -100,6 +99,15 @@ export declare class TTSProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): TTSHandler | undefined;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    /**
+     * Removes every registered TTS handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers(): void;
     /**
      * Check if a provider is supported (has a registered TTS handler)
      *

package/dist/lib/utils/ttsProcessor.js

@@ -9,6 +9,7 @@
 import { logger } from "./logger.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { NeuroLinkError } from "./errorHandling.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 /**
  * TTS-specific error codes
@@ -58,11 +59,10 @@ export class TTSError extends NeuroLinkError {
 export class TTSProcessor {
     /**
      * Handler registry mapping provider names to TTS handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    static handlers = new Map();
+    static registry = new HandlerRegistry("TTSProcessor");
     /**
      * Default maximum text length for TTS synthesis (in bytes)
      *
@@ -93,17 +93,10 @@ export class TTSProcessor {
      * ```
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const normalizedName = providerName.toLowerCase();
-        if (this.handlers.has(normalizedName)) {
-            logger.warn(`[TTSProcessor] Overwriting existing handler for provider: ${normalizedName}`);
-        }
-        this.handlers.set(normalizedName, handler);
+        const normalizedName = providerName
+            ? providerName.toLowerCase()
+            : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[TTSProcessor] Registered TTS handler for provider: ${normalizedName}`);
     }
     /**
@@ -117,8 +110,20 @@ export class TTSProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName) {
-        const normalizedName = providerName.toLowerCase();
-        return this.handlers.get(normalizedName);
+        return this.registry.get(providerName);
+    }
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders() {
+        return this.registry.list();
+    }
+    /**
+     * Removes every registered TTS handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     /**
      * Check if a provider is supported (has a registered TTS handler)
@@ -138,8 +143,7 @@ export class TTSProcessor {
             logger.error("[TTSProcessor] Provider name is required for supports check");
             return false;
         }
-        const normalizedName = providerName.toLowerCase();
-        const isSupported = this.handlers.has(normalizedName);
+        const isSupported = this.registry.supports(providerName);
         if (!isSupported) {
             logger.debug(`[TTSProcessor] Provider ${providerName} is not supported`);
         }
@@ -211,7 +215,7 @@ export class TTSProcessor {
                     retriable: false,
                     context: {
                         provider,
-                        availableProviders: Array.from(this.handlers.keys()),
+                        availableProviders: this.registry.list(),
                     },
                 });
             }

package/dist/lib/utils/videoProcessor.d.ts

@@ -22,7 +22,7 @@ export { VideoError, VIDEO_ERROR_CODES };
  * O(1) on a normalised lower-case provider key.
  */
 export declare class VideoProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register a video handler for a specific provider.
      */
@@ -36,6 +36,10 @@ export declare class VideoProcessor {
      */
     static listProviders(): string[];
     private static getHandler;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate a single video clip via the registered handler.

package/dist/lib/utils/videoProcessor.js

@@ -19,6 +19,7 @@ import { logger } from "./logger.js";
 // the same module. Both throws and instanceof checks resolve to the same
 // class.
 import { VideoError } from "../adapters/video/vertexVideoHandler.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 export { VideoError, VIDEO_ERROR_CODES };
 /**
  * Static processor managing the video handler registry.
@@ -28,41 +29,35 @@ export { VideoError, VIDEO_ERROR_CODES };
  * O(1) on a normalised lower-case provider key.
  */
 export class VideoProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("VideoProcessor");
     /**
      * Register a video 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(`[VideoProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[VideoProcessor] Registered video handler: ${key}`);
     }
     /**
      * Check if a provider has a registered video handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/lib/voice/RealtimeVoiceAPI.d.ts

@@ -36,7 +36,7 @@ export declare class RealtimeProcessor {
     /**
      * Handler registry mapping provider names to Realtime handlers
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Active sessions by provider
      */