@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/utils/timeout.js

@@ -0,0 +1,359 @@
+/**
+ * Timeout utilities for NeuroLink
+ *
+ * Provides flexible timeout parsing and error handling for AI operations.
+ * Supports multiple time formats: milliseconds, seconds, minutes, hours.
+ */
+/**
+ * Custom error class for timeout operations
+ */
+export class TimeoutError extends Error {
+    timeout;
+    provider;
+    operation;
+    constructor(message, timeout, provider, operation) {
+        super(message);
+        this.timeout = timeout;
+        this.provider = provider;
+        this.operation = operation;
+        this.name = "TimeoutError";
+        // Maintains proper stack trace for where error was thrown
+        if (typeof Error.captureStackTrace === "function") {
+            Error.captureStackTrace(this, TimeoutError);
+        }
+    }
+}
+/**
+ * Parse timeout value from various formats
+ * @param timeout - Can be number (ms), string with unit, or undefined
+ * @returns Parsed timeout in milliseconds or undefined
+ * @throws Error if format is invalid
+ *
+ * Examples:
+ * - parseTimeout(5000) => 5000
+ * - parseTimeout('30s') => 30000
+ * - parseTimeout('2m') => 120000
+ * - parseTimeout('1.5h') => 5400000
+ * - parseTimeout(undefined) => undefined
+ */
+export function parseTimeout(timeout) {
+    if (timeout === undefined) {
+        return undefined;
+    }
+    if (typeof timeout === "number") {
+        if (timeout <= 0) {
+            throw new Error(`Timeout must be positive, got: ${timeout}`);
+        }
+        return timeout; // Assume milliseconds
+    }
+    if (typeof timeout === "string") {
+        // Match number (including decimals) followed by optional unit
+        const match = timeout.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+        if (!match) {
+            throw new Error(`Invalid timeout format: ${timeout}. Use formats like '30s', '2m', '500ms', or '1.5h'`);
+        }
+        const value = parseFloat(match[1]);
+        if (value <= 0) {
+            throw new Error(`Timeout must be positive, got: ${value}`);
+        }
+        const unit = match[2] || "ms";
+        switch (unit) {
+            case "ms":
+                return value;
+            case "s":
+                return value * 1000;
+            case "m":
+                return value * 60 * 1000;
+            case "h":
+                return value * 60 * 60 * 1000;
+            default:
+                return value; // Should never reach here due to regex
+        }
+    }
+    throw new Error(`Invalid timeout type: ${typeof timeout}`);
+}
+/**
+ * Default timeout configurations for different providers and operations
+ */
+export const DEFAULT_TIMEOUTS = {
+    global: "30s", // Default for all providers
+    streaming: "2m", // Longer timeout for streaming operations
+    providers: {
+        openai: "30s", // OpenAI typically responds quickly
+        bedrock: "45s", // AWS can be slower, especially for cold starts
+        vertex: "60s", // Google Cloud can be slower
+        anthropic: "60s", // Increased timeout for Anthropic API stability
+        azure: "30s", // Azure OpenAI similar to OpenAI
+        "google-ai": "30s", // Google AI Studio is fast
+        huggingface: "2m", // Open source models vary significantly
+        ollama: "5m", // Local models need more time, especially large ones
+        mistral: "45s", // Mistral AI moderate speed
+    },
+    tools: {
+        default: "10s", // Default timeout for MCP tool execution
+        filesystem: "5s", // File operations should be quick
+        network: "30s", // Network requests might take longer
+        computation: "2m", // Heavy computation tools need more time
+    },
+};
+/**
+ * Get default timeout for a specific provider
+ * @param provider - Provider name
+ * @param operation - Operation type (generate or stream)
+ * @returns Default timeout string
+ */
+export function getDefaultTimeout(provider, operation = "generate") {
+    if (operation === "stream") {
+        return DEFAULT_TIMEOUTS.streaming;
+    }
+    const providerKey = provider.toLowerCase().replace("_", "-");
+    return (DEFAULT_TIMEOUTS.providers[providerKey] || DEFAULT_TIMEOUTS.global);
+}
+/**
+ * Create a timeout promise that rejects after specified duration
+ * @param timeout - Timeout duration
+ * @param provider - Provider name for error message
+ * @param operation - Operation type for error message
+ * @returns Promise that rejects with TimeoutError
+ */
+export function createTimeoutPromise(timeout, provider, operation) {
+    const timeoutMs = parseTimeout(timeout);
+    if (!timeoutMs) {
+        return null; // No timeout
+    }
+    return new Promise((_, reject) => {
+        const timer = setTimeout(() => {
+            reject(new TimeoutError(`${provider} ${operation} operation timed out after ${timeout}`, timeoutMs, provider, operation));
+        }, timeoutMs);
+        // Unref the timer so it doesn't keep the process alive (Node.js only)
+        if (typeof timer === "object" &&
+            timer &&
+            "unref" in timer &&
+            typeof timer.unref === "function") {
+            timer.unref();
+        }
+    });
+}
+/**
+ * Enhanced timeout manager with proper cleanup and abort controller integration
+ * Consolidated from timeout-manager.ts
+ */
+export class TimeoutManager {
+    activeTimeouts = new Map();
+    /**
+     * Execute operation with timeout and proper cleanup
+     */
+    async executeWithTimeout(operation, config) {
+        const startTime = Date.now();
+        const operationId = this.generateOperationId(config.operation);
+        let retriesUsed = 0;
+        const maxRetries = config.retryOnTimeout ? (config.maxRetries ?? 1) : 0;
+        while (retriesUsed <= maxRetries) {
+            try {
+                const result = await this.performSingleOperation(operation, config, operationId);
+                return {
+                    success: true,
+                    data: result,
+                    timedOut: false,
+                    executionTime: Date.now() - startTime,
+                    retriesUsed,
+                };
+            }
+            catch (error) {
+                this.cleanup(operationId);
+                if (error instanceof TimeoutError && retriesUsed < maxRetries) {
+                    retriesUsed++;
+                    continue;
+                }
+                return {
+                    success: false,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    timedOut: error instanceof TimeoutError,
+                    executionTime: Date.now() - startTime,
+                    retriesUsed,
+                };
+            }
+        }
+        return {
+            success: false,
+            error: new Error("Maximum retries exceeded"),
+            timedOut: true,
+            executionTime: Date.now() - startTime,
+            retriesUsed,
+        };
+    }
+    async performSingleOperation(operation, config, operationId) {
+        const timeoutMs = this.getTimeoutMs(config);
+        if (!timeoutMs) {
+            return await operation();
+        }
+        const controller = new AbortController();
+        const existingSignal = config.abortSignal;
+        if (existingSignal) {
+            existingSignal.addEventListener("abort", () => {
+                controller.abort(existingSignal.reason);
+            });
+            if (existingSignal.aborted) {
+                throw new Error("Operation aborted before execution");
+            }
+        }
+        const timeoutPromise = this.createTimeoutPromise(timeoutMs, operationId);
+        this.registerTimeout(operationId, timeoutPromise.timer, controller, () => {
+            clearTimeout(timeoutPromise.timer);
+        });
+        try {
+            return await Promise.race([operation(), timeoutPromise.promise]);
+        }
+        finally {
+            this.cleanup(operationId);
+        }
+    }
+    getTimeoutMs(config) {
+        return parseTimeout(config.timeout);
+    }
+    generateOperationId(operation) {
+        return `${operation}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    createTimeoutPromise(timeoutMs, _operationId) {
+        let timer;
+        const promise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new TimeoutError(`Operation timeout after ${timeoutMs}ms`, timeoutMs));
+            }, timeoutMs);
+        });
+        if (!timer) {
+            throw new Error("Failed to create timeout timer");
+        }
+        return { promise, timer };
+    }
+    registerTimeout(operationId, timer, controller, cleanup) {
+        this.activeTimeouts.set(operationId, { timer, controller, cleanup });
+    }
+    cleanup(operationId) {
+        const timeoutInfo = this.activeTimeouts.get(operationId);
+        if (timeoutInfo) {
+            timeoutInfo.cleanup();
+            this.activeTimeouts.delete(operationId);
+        }
+    }
+    gracefulShutdown() {
+        for (const [operationId] of this.activeTimeouts) {
+            this.cleanup(operationId);
+        }
+    }
+}
+/**
+ * Wrapper functions consolidated from timeout-wrapper.ts
+ */
+/**
+ * Wrap a promise with timeout
+ * @param promise - The promise to wrap
+ * @param timeout - Timeout duration (number in ms or string with unit)
+ * @param provider - Provider name for error messages
+ * @param operation - Operation type (generate or stream)
+ * @returns The result of the promise or throws TimeoutError
+ */
+export async function withTimeout(promise, timeout, provider, operation) {
+    const timeoutMs = parseTimeout(timeout);
+    if (!timeoutMs) {
+        return promise;
+    }
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new TimeoutError(`${provider} ${operation} operation timed out after ${timeoutMs}ms`, timeoutMs, provider, operation));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]);
+}
+/**
+ * Wrap a streaming async generator with timeout
+ * @param generator - The async generator to wrap
+ * @param timeout - Timeout duration for the entire stream
+ * @param provider - Provider name for error messages
+ * @returns Wrapped async generator that respects timeout
+ */
+export async function* withStreamingTimeout(generator, timeout, provider) {
+    const timeoutMs = parseTimeout(timeout);
+    if (!timeoutMs) {
+        yield* generator;
+        return;
+    }
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new TimeoutError(`${provider} streaming operation timed out after ${timeoutMs}ms`, timeoutMs, provider, "stream"));
+        }, timeoutMs);
+    });
+    try {
+        for await (const item of generator) {
+            const raceResult = await Promise.race([
+                Promise.resolve(item),
+                timeoutPromise,
+            ]);
+            yield raceResult;
+        }
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/**
+ * Create an abort controller with timeout
+ * @param timeout - Timeout duration
+ * @param provider - Provider name for error messages
+ * @param operation - Operation type
+ * @returns AbortController and cleanup function
+ */
+export function createTimeoutController(timeout, provider, operation) {
+    const timeoutMs = parseTimeout(timeout);
+    if (!timeoutMs) {
+        return null;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort(new TimeoutError(`${provider} ${operation} operation timed out after ${timeout}`, timeoutMs, provider, operation));
+    }, timeoutMs);
+    const cleanup = () => {
+        clearTimeout(timer);
+    };
+    return { controller, cleanup, timeoutMs };
+}
+/**
+ * Compose an external abort signal with a timeout controller's signal.
+ * Returns a single AbortSignal that fires when either signal aborts.
+ * If only one signal is present, returns it directly without wrapping.
+ *
+ * @param externalSignal - User-provided AbortSignal (e.g., from options.abortSignal)
+ * @param timeoutSignal - Timeout controller's signal
+ * @returns Combined AbortSignal, or undefined if neither is present
+ */
+export function composeAbortSignals(externalSignal, timeoutSignal) {
+    if (externalSignal && timeoutSignal) {
+        return AbortSignal.any([externalSignal, timeoutSignal]);
+    }
+    return externalSignal ?? timeoutSignal;
+}
+/**
+ * Merge abort signals (for combining user abort with timeout)
+ * @param signals - Array of abort signals to merge
+ * @returns Combined abort controller
+ */
+export function mergeAbortSignals(signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal && !signal.aborted) {
+            signal.addEventListener("abort", () => {
+                if (!controller.signal.aborted) {
+                    controller.abort(signal.reason);
+                }
+            });
+        }
+        if (signal?.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+    }
+    return controller;
+}

package/dist/client/utils/tokenEstimation.js

@@ -0,0 +1,142 @@
+/**
+ * Token Estimation Utilities
+ *
+ * Provides character-based token estimation with per-provider adjustment
+ * multipliers. Uses the same approach as Continue (gpt-tokenizer baseline
+ * + provider multipliers) but without requiring a tokenizer dependency.
+ *
+ * Multiplier sources: Continue project's getAdjustedTokenCount.ts
+ * - Anthropic: 1.23x (Anthropic tokenizer produces ~23% more tokens)
+ * - Google (AI Studio / Vertex): 1.18x
+ * - Mistral/Codestral: 1.26x
+ * - OpenAI/GPT: 1.0x (baseline)
+ */
+/** Characters per token for English text */
+export const CHARS_PER_TOKEN = 4;
+/** Characters per token for code */
+export const CODE_CHARS_PER_TOKEN = 3;
+/**
+ * Safety margin: additive fraction of baseTokens added to the provider-adjusted estimate.
+ * Using additive margin prevents compounding with provider multipliers.
+ *
+ * Old behavior: baseTokens * providerMultiplier * 1.15  (compounding)
+ *   e.g. Anthropic: baseTokens * 1.23 * 1.15 = baseTokens * 1.4145
+ * New behavior: baseTokens * providerMultiplier + baseTokens * 0.05  (additive)
+ *   e.g. Anthropic: baseTokens * 1.23 + baseTokens * 0.05 = baseTokens * 1.28
+ */
+export const TOKEN_SAFETY_MARGIN_ADDITIVE = 0.05;
+/** @deprecated Use TOKEN_SAFETY_MARGIN_ADDITIVE instead. Kept for backward compatibility. */
+export const TOKEN_SAFETY_MARGIN = 1.15;
+/** Message framing overhead in tokens (role + delimiters) */
+export const TOKENS_PER_MESSAGE = 4;
+/** Conversation-level overhead in tokens */
+export const TOKENS_PER_CONVERSATION = 24;
+/** Image token estimate (flat) */
+export const IMAGE_TOKEN_ESTIMATE = 1_024;
+/**
+ * Per-provider token multipliers.
+ * Applied on top of the base GPT-style character estimate.
+ */
+const PROVIDER_MULTIPLIERS = {
+    anthropic: 1.23,
+    "google-ai": 1.18,
+    vertex: 1.18,
+    mistral: 1.26,
+    openai: 1.0,
+    azure: 1.0,
+    bedrock: 1.23, // Bedrock is mostly Anthropic models
+    ollama: 1.0,
+    litellm: 1.0,
+    huggingface: 1.0,
+    sagemaker: 1.0,
+};
+/**
+ * Get the token multiplier for a given provider.
+ */
+export function getProviderMultiplier(provider) {
+    if (!provider) {
+        return 1.0;
+    }
+    return PROVIDER_MULTIPLIERS[provider] ?? 1.0;
+}
+/**
+ * Estimate token count for a string.
+ *
+ * @param text - Input text
+ * @param provider - Optional provider for multiplier adjustment
+ * @param isCode - Whether the text is code (uses CODE_CHARS_PER_TOKEN)
+ * @returns Estimated token count
+ */
+export function estimateTokens(text, provider, isCode) {
+    if (!text || text.length === 0) {
+        return 0;
+    }
+    const charsPerToken = isCode ? CODE_CHARS_PER_TOKEN : CHARS_PER_TOKEN;
+    const baseTokens = Math.ceil(text.length / charsPerToken);
+    const multiplier = getProviderMultiplier(provider);
+    // Apply provider multiplier and additive safety margin separately
+    // This prevents compounding (e.g. Anthropic: 1.23 * 1.15 = 1.41x was too aggressive)
+    const providerAdjusted = baseTokens * multiplier;
+    const safetyBuffer = baseTokens * TOKEN_SAFETY_MARGIN_ADDITIVE;
+    return Math.ceil(providerAdjusted + safetyBuffer);
+}
+/**
+ * Estimate token count for a single ChatMessage.
+ * Includes message framing overhead.
+ */
+export function estimateMessageTokens(message, provider) {
+    let contentStr = "";
+    if (message.content) {
+        if (typeof message.content === "string") {
+            contentStr = message.content;
+        }
+        else {
+            try {
+                contentStr = JSON.stringify(message.content);
+            }
+            catch {
+                // Fallback for circular references or non-serializable content
+                contentStr = String(message.content);
+            }
+        }
+    }
+    const contentTokens = estimateTokens(contentStr, provider);
+    return contentTokens + TOKENS_PER_MESSAGE;
+}
+/**
+ * Estimate total token count for an array of messages.
+ * Includes conversation-level overhead.
+ */
+export function estimateMessagesTokens(messages, provider) {
+    if (!messages || messages.length === 0) {
+        return 0;
+    }
+    const messageTokens = messages.reduce((sum, msg) => sum + estimateMessageTokens(msg, provider), 0);
+    return messageTokens + TOKENS_PER_CONVERSATION;
+}
+/**
+ * Truncate text to fit within a token budget.
+ * Tries to cut at sentence or word boundaries.
+ *
+ * @param text - Input text
+ * @param maxTokens - Maximum tokens allowed
+ * @param provider - Optional provider for multiplier
+ * @returns Truncated text with "..." suffix if truncated
+ */
+export function truncateToTokenBudget(text, maxTokens, provider) {
+    if (estimateTokens(text, provider) <= maxTokens) {
+        return { text, truncated: false };
+    }
+    const multiplier = getProviderMultiplier(provider);
+    // Use additive safety margin: effective multiplier = multiplier + additive margin
+    const effectiveMultiplier = multiplier + TOKEN_SAFETY_MARGIN_ADDITIVE;
+    const maxChars = Math.floor((maxTokens / effectiveMultiplier) * CHARS_PER_TOKEN);
+    if (maxChars <= 0) {
+        return { text: "", truncated: true };
+    }
+    // Try to cut at sentence boundary
+    const candidate = text.slice(0, maxChars);
+    const lastSentence = Math.max(candidate.lastIndexOf(". "), candidate.lastIndexOf("! "), candidate.lastIndexOf("? "), candidate.lastIndexOf("\n"));
+    const cutPoint = lastSentence > maxChars * 0.5 ? lastSentence + 1 : maxChars;
+    return { text: text.slice(0, cutPoint) + "...", truncated: true };
+}

package/dist/client/utils/tokenLimits.js

@@ -0,0 +1,125 @@
+/**
+ * Provider-specific token limit utilities
+ * Provides safe maxTokens values based on provider and model capabilities
+ */
+import { PROVIDER_MAX_TOKENS } from "../core/constants.js";
+import { logger } from "./logger.js";
+/**
+ * Get the safe maximum tokens for a provider and model
+ */
+export function getSafeMaxTokens(provider, model, requestedMaxTokens) {
+    // Get provider-specific limits
+    const providerLimits = PROVIDER_MAX_TOKENS[provider];
+    if (!providerLimits) {
+        logger.warn(`Unknown provider ${provider}, no token limits enforced`);
+        return requestedMaxTokens || undefined; // No default limit for unknown providers
+    }
+    // Get model-specific limit or provider default
+    let maxLimit;
+    if (model &&
+        typeof providerLimits === "object" &&
+        providerLimits[model]) {
+        maxLimit = providerLimits[model];
+    }
+    else if (typeof providerLimits === "object" &&
+        providerLimits.default) {
+        maxLimit = providerLimits.default;
+    }
+    else if (typeof providerLimits === "number") {
+        maxLimit = providerLimits;
+    }
+    else {
+        maxLimit = PROVIDER_MAX_TOKENS.default;
+    }
+    // If no specific maxTokens requested, return the provider limit
+    if (!requestedMaxTokens) {
+        return maxLimit;
+    }
+    // If requested maxTokens exceeds the limit, use the limit and warn
+    if (requestedMaxTokens > maxLimit) {
+        logger.warn(`Requested maxTokens ${requestedMaxTokens} exceeds ${provider}/${model} limit of ${maxLimit}. Using ${maxLimit} instead.`);
+        return maxLimit;
+    }
+    // Use the requested value if it's within limits
+    return requestedMaxTokens;
+}
+/**
+ * Validate if maxTokens is safe for a provider/model combination
+ */
+export function validateMaxTokens(provider, model, maxTokens) {
+    const safeMaxTokens = getSafeMaxTokens(provider, model, maxTokens);
+    if (!maxTokens) {
+        return {
+            isValid: true,
+            recommendedMaxTokens: safeMaxTokens,
+        };
+    }
+    // If no limits are defined, validation always passes
+    if (safeMaxTokens === undefined) {
+        return {
+            isValid: true,
+            recommendedMaxTokens: maxTokens,
+        };
+    }
+    const isValid = maxTokens <= safeMaxTokens;
+    return {
+        isValid,
+        recommendedMaxTokens: safeMaxTokens,
+        warning: !isValid
+            ? `maxTokens ${maxTokens} exceeds ${provider}/${model} limit of ${safeMaxTokens}`
+            : undefined,
+    };
+}
+/**
+ * Get provider-specific token limit recommendations
+ */
+export function getTokenLimitRecommendations(provider) {
+    const providerLimits = PROVIDER_MAX_TOKENS[provider];
+    if (!providerLimits || typeof providerLimits === "number") {
+        const limit = typeof providerLimits === "number"
+            ? providerLimits
+            : PROVIDER_MAX_TOKENS.default;
+        return {
+            conservative: Math.floor(limit * 0.5),
+            balanced: Math.floor(limit * 0.75),
+            maximum: limit,
+            models: {},
+        };
+    }
+    const modelLimits = Object.entries(providerLimits)
+        .filter(([key]) => key !== "default")
+        .map(([_, limit]) => limit);
+    const maxLimit = Math.max(...modelLimits, providerLimits.default || 0);
+    const minLimit = Math.min(...modelLimits, providerLimits.default || maxLimit);
+    return {
+        conservative: Math.floor(minLimit * 0.5),
+        balanced: Math.floor(((minLimit + maxLimit) / 2) * 0.75),
+        maximum: maxLimit,
+        models: Object.fromEntries(Object.entries(providerLimits).filter(([key]) => key !== "default")),
+    };
+}
+/**
+ * Get all provider limits summary
+ */
+export function getAllProviderLimits() {
+    const result = {};
+    for (const [provider, limits] of Object.entries(PROVIDER_MAX_TOKENS)) {
+        if (provider === "default") {
+            continue;
+        }
+        if (typeof limits === "number") {
+            result[provider] = {
+                default: limits,
+                models: {},
+            };
+        }
+        else {
+            const { default: defaultLimit, ...models } = limits;
+            result[provider] = {
+                default: defaultLimit || PROVIDER_MAX_TOKENS.default,
+                models: models,
+            };
+        }
+    }
+    return result;
+}