@juspay/neurolink 9.5.3 → 9.7.0

package/dist/utils/modelChoices.d.ts

@@ -6,11 +6,11 @@ import { AIProviderName } from "../constants/enums.js";
 /**
  * Model choice for CLI prompts (inquirer format)
  */
-export interface ModelChoice {
+export type ModelChoice = {
     name: string;
     value: string;
     description?: string;
-}
+};
 /**
  * Default models per provider (first choice/recommended)
  */

package/dist/utils/multimodalOptionsBuilder.d.ts

@@ -46,7 +46,7 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         text: string;
         images: (string | Buffer<ArrayBufferLike> | import("../index.js").ImageWithAltText)[] | undefined;
         content: import("../index.js").Content[] | undefined;
-        files: (string | Buffer<ArrayBufferLike>)[] | undefined;
+        files: (string | Buffer<ArrayBufferLike> | import("../index.js").FileWithMetadata)[] | undefined;
         csvFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
@@ -64,4 +64,5 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
     enableAnalytics: boolean | undefined;
     enableEvaluation: boolean | undefined;
     context: import("../index.js").UnknownRecord | undefined;
+    fileRegistry: unknown;
 };

package/dist/utils/multimodalOptionsBuilder.js

@@ -60,5 +60,6 @@ export function buildMultimodalOptions(options, providerName, modelName) {
         enableAnalytics: options.enableAnalytics,
         enableEvaluation: options.enableEvaluation,
         context: options.context,
+        fileRegistry: options.fileRegistry,
     };
 }

package/dist/utils/pricing.d.ts

@@ -0,0 +1,12 @@
+import type { TokenUsage } from "../types/analytics.js";
+/**
+ * Calculate the dollar cost of a generate/stream call based on token usage.
+ * Returns 0 if the provider/model combination is not in the pricing table.
+ */
+export declare function calculateCost(provider: string, model: string, usage: TokenUsage): number;
+/**
+ * Check if pricing is available for a provider/model combination.
+ * Checks the rate table directly instead of computing a cost,
+ * so even very cheap models (e.g. gemini-1.5-flash) are detected correctly.
+ */
+export declare function hasPricing(provider: string, model: string): boolean;

package/dist/utils/pricing.js

@@ -0,0 +1,133 @@
+/**
+ * Per-token pricing data (USD per token). Updated Feb 2026.
+ * Sources:
+ * - Anthropic: https://www.anthropic.com/pricing
+ * - OpenAI: https://openai.com/api/pricing
+ * - Google: https://ai.google.dev/pricing
+ *
+ * Note: Not all supported providers have pricing data. Missing providers
+ * (Bedrock, Azure, Mistral, etc.) will return 0 from calculateCost().
+ */
+const PRICING = {
+    // Anthropic (direct API)
+    anthropic: {
+        "claude-sonnet-4-5-20250929": {
+            input: 3.0 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.3 / 1_000_000,
+            cacheCreation: 3.75 / 1_000_000,
+        },
+        "claude-opus-4-6": {
+            input: 15.0 / 1_000_000,
+            output: 75.0 / 1_000_000,
+            cacheRead: 1.5 / 1_000_000,
+            cacheCreation: 18.75 / 1_000_000,
+        },
+        "claude-haiku-4-5-20251001": {
+            input: 0.8 / 1_000_000,
+            output: 4.0 / 1_000_000,
+            cacheRead: 0.08 / 1_000_000,
+            cacheCreation: 1.0 / 1_000_000,
+        },
+    },
+    // Google Vertex AI (same models, same pricing)
+    vertex: {
+        "claude-sonnet-4-5@20250929": {
+            input: 3.0 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.3 / 1_000_000,
+            cacheCreation: 3.75 / 1_000_000,
+        },
+        "claude-opus-4-6": {
+            input: 15.0 / 1_000_000,
+            output: 75.0 / 1_000_000,
+            cacheRead: 1.5 / 1_000_000,
+            cacheCreation: 18.75 / 1_000_000,
+        },
+        "claude-haiku-4-5@20251001": {
+            input: 0.8 / 1_000_000,
+            output: 4.0 / 1_000_000,
+            cacheRead: 0.08 / 1_000_000,
+            cacheCreation: 1.0 / 1_000_000,
+        },
+    },
+    // OpenAI
+    openai: {
+        "gpt-4o": { input: 2.5 / 1_000_000, output: 10.0 / 1_000_000 },
+        "gpt-4o-mini": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "gpt-4-turbo": { input: 10.0 / 1_000_000, output: 30.0 / 1_000_000 },
+        o1: { input: 15.0 / 1_000_000, output: 60.0 / 1_000_000 },
+        "o1-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
+    },
+    // Google (Gemini)
+    google: {
+        "gemini-2.0-flash": { input: 0.1 / 1_000_000, output: 0.4 / 1_000_000 },
+        "gemini-2.0-pro": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
+        "gemini-1.5-pro": { input: 1.25 / 1_000_000, output: 5.0 / 1_000_000 },
+        "gemini-1.5-flash": { input: 0.075 / 1_000_000, output: 0.3 / 1_000_000 },
+    },
+};
+/**
+ * Map of normalized provider aliases to canonical PRICING keys.
+ * After stripping non-alpha characters, e.g. "google-ai" becomes "googleai".
+ */
+const PROVIDER_ALIASES = {
+    googleai: "google",
+    googleaistudio: "google",
+    anthropic: "anthropic",
+    openai: "openai",
+    vertex: "vertex",
+    google: "google",
+};
+/**
+ * Look up per-token rates for a provider/model combination.
+ * Normalises the provider name via aliases, then tries an exact model match
+ * followed by a longest-prefix match so that e.g. "gpt-4o-2024-08-06"
+ * resolves to the "gpt-4o" entry without a false hit on "gpt-4".
+ *
+ * @returns The rate entry, or undefined when the combination is unknown.
+ */
+function findRates(provider, model) {
+    const stripped = provider.toLowerCase().replace(/[^a-z]/g, "");
+    const normalizedProvider = PROVIDER_ALIASES[stripped] ?? stripped;
+    const providerPricing = PRICING[normalizedProvider] || PRICING[provider];
+    if (!providerPricing) {
+        return undefined;
+    }
+    // Exact match
+    if (providerPricing[model]) {
+        return providerPricing[model];
+    }
+    // Longest-prefix match
+    const sortedKeys = Object.keys(providerPricing).sort((a, b) => b.length - a.length);
+    const key = sortedKeys.find((k) => model.startsWith(k));
+    return key ? providerPricing[key] : undefined;
+}
+/**
+ * Calculate the dollar cost of a generate/stream call based on token usage.
+ * Returns 0 if the provider/model combination is not in the pricing table.
+ */
+export function calculateCost(provider, model, usage) {
+    const rates = findRates(provider, model);
+    if (!rates) {
+        return 0;
+    }
+    let cost = 0;
+    cost += (usage.input || 0) * rates.input;
+    cost += (usage.output || 0) * rates.output;
+    if (usage.cacheReadTokens && rates.cacheRead) {
+        cost += usage.cacheReadTokens * rates.cacheRead;
+    }
+    if (usage.cacheCreationTokens && rates.cacheCreation) {
+        cost += usage.cacheCreationTokens * rates.cacheCreation;
+    }
+    return Math.round(cost * 1_000_000) / 1_000_000; // Round to 6 decimal places
+}
+/**
+ * Check if pricing is available for a provider/model combination.
+ * Checks the rate table directly instead of computing a cost,
+ * so even very cheap models (e.g. gemini-1.5-flash) are detected correctly.
+ */
+export function hasPricing(provider, model) {
+    return findRates(provider, model) !== undefined;
+}

package/dist/utils/rateLimiter.d.ts

@@ -9,7 +9,7 @@
 /**
  * Configuration options for the rate limiter
  */
-export interface RateLimiterConfig {
+export type RateLimiterConfig = {
     /** Maximum tokens (downloads) allowed per interval */
     maxTokens: number;
     /** Refill interval in milliseconds */
@@ -20,7 +20,7 @@ export interface RateLimiterConfig {
     maxQueueSize: number;
     /** Timeout for queued requests in milliseconds */
     queueTimeoutMs: number;
-}
+};
 /**
  * Token Bucket Rate Limiter
  *

package/dist/utils/redis.d.ts

@@ -5,6 +5,23 @@
 import { createClient } from "redis";
 import type { RedisStorageConfig, RedisConversationObject } from "../types/conversation.js";
 type RedisClient = ReturnType<typeof createClient>;
+/**
+ * Get a pooled Redis connection. Multiple callers with the same host:port:db
+ * share a single connection, reducing connection count.
+ */
+export declare function getPooledRedisClient(config: Required<RedisStorageConfig>): Promise<RedisClient>;
+/**
+ * Release a pooled Redis connection. Only closes when refCount reaches 0.
+ */
+export declare function releasePooledRedisClient(config: Required<RedisStorageConfig>): Promise<void>;
+/**
+ * Get stats about the connection pool
+ */
+export declare function getPoolStats(): Array<{
+    key: string;
+    refCount: number;
+    isOpen: boolean;
+}>;
 /**
  * Creates a Redis client with the provided configuration
  */

package/dist/utils/redis.js

@@ -4,6 +4,111 @@
  */
 import { createClient } from "redis";
 import { logger } from "./logger.js";
+// Connection pool - keyed by host:port:db
+const connectionPool = new Map();
+const pendingConnections = new Map();
+/**
+ * Get a pooled Redis connection. Multiple callers with the same host:port:db
+ * share a single connection, reducing connection count.
+ */
+export async function getPooledRedisClient(config) {
+    const key = `${config.host}:${config.port}:${config.db}:${config.password ? "auth" : "noauth"}`;
+    const existing = connectionPool.get(key);
+    if (existing && existing.client.isOpen) {
+        existing.refCount++;
+        logger.debug("[Redis] Reusing pooled connection", {
+            key,
+            refCount: existing.refCount,
+        });
+        return existing.client;
+    }
+    // Check pending BEFORE cleaning up stale entries to prevent TOCTOU race:
+    // Two callers seeing a stale entry could both skip this check and both
+    // attempt to create new connections if we cleaned up first.
+    const pending = pendingConnections.get(key);
+    if (pending) {
+        const client = await pending;
+        const entry = connectionPool.get(key);
+        if (entry) {
+            if (!entry.client.isOpen) {
+                // Client was closed while awaiting; clean up and create fresh
+                connectionPool.delete(key);
+                const freshClient = await createRedisClient(config);
+                connectionPool.set(key, { client: freshClient, refCount: 1 });
+                return freshClient;
+            }
+            entry.refCount++;
+        }
+        else if (client.isOpen) {
+            // Entry was released while we awaited; re-register
+            connectionPool.set(key, { client, refCount: 1 });
+        }
+        else {
+            // Client was closed while we awaited; create fresh connection
+            const freshClient = await createRedisClient(config);
+            connectionPool.set(key, { client: freshClient, refCount: 1 });
+            return freshClient;
+        }
+        return client;
+    }
+    // Clean up stale entry if exists (connection closed)
+    if (existing) {
+        connectionPool.delete(key);
+    }
+    // Create the promise and register it in pendingConnections atomically
+    // (synchronous) before any await, so concurrent callers will find it.
+    const connectPromise = createRedisClient(config);
+    pendingConnections.set(key, connectPromise);
+    try {
+        const client = await connectPromise;
+        connectionPool.set(key, { client, refCount: 1 });
+        logger.info("[Redis] Created pooled connection", { key, refCount: 1 });
+        return client;
+    }
+    finally {
+        pendingConnections.delete(key);
+    }
+}
+/**
+ * Release a pooled Redis connection. Only closes when refCount reaches 0.
+ */
+export async function releasePooledRedisClient(config) {
+    const key = `${config.host}:${config.port}:${config.db}:${config.password ? "auth" : "noauth"}`;
+    const entry = connectionPool.get(key);
+    if (!entry) {
+        return;
+    }
+    entry.refCount--;
+    logger.debug("[Redis] Released pooled connection", {
+        key,
+        refCount: entry.refCount,
+    });
+    if (entry.refCount <= 0) {
+        try {
+            if (entry.client.isOpen) {
+                await entry.client.quit();
+            }
+        }
+        catch (e) {
+            logger.warn("[Redis] Error closing pooled connection", {
+                key,
+                error: String(e),
+            });
+        }
+        connectionPool.delete(key);
+        logger.info("[Redis] Closed pooled connection", { key });
+    }
+}
+/**
+ * Get stats about the connection pool
+ */
+export function getPoolStats() {
+    return Array.from(connectionPool.entries()).map(([key, entry]) => ({
+        key,
+        refCount: entry.refCount,
+        isOpen: entry.client.isOpen,
+    }));
+}
 /**
  * Creates a Redis client with the provided configuration
  */

package/dist/utils/sanitizers/filename.d.ts

@@ -12,7 +12,7 @@
 /**
  * Options for filename sanitization.
  */
-export interface SanitizeFileNameOptions {
+export type SanitizeFileNameOptions = {
     /** Maximum length for the filename (default: 255) */
     maxLength?: number;
     /** Replacement character for invalid chars (default: '_') */
@@ -21,16 +21,16 @@ export interface SanitizeFileNameOptions {
     blockDangerousExtensions?: boolean;
     /** Whether to allow hidden files starting with dot (default: false) */
     allowHiddenFiles?: boolean;
-}
+};
 /**
  * Options for display name sanitization.
  */
-export interface SanitizeDisplayNameOptions {
+export type SanitizeDisplayNameOptions = {
     /** Maximum length for the name (default: 100) */
     maxLength?: number;
     /** Whether to allow unicode characters (default: true) */
     allowUnicode?: boolean;
-}
+};
 /**
  * Sanitize a filename for safe filesystem storage.
  * Removes characters that are invalid on various operating systems.

package/dist/utils/sanitizers/svg.d.ts

@@ -19,14 +19,14 @@
 /**
  * Result of SVG sanitization including metadata about removed content
  */
-export interface SvgSanitizationResult {
+export type SvgSanitizationResult = {
     /** Sanitized SVG content */
     content: string;
     /** Items that were removed during sanitization */
     removedItems: string[];
     /** Whether any content was modified */
     wasModified: boolean;
-}
+};
 /**
  * Sanitize SVG content by removing dangerous elements and attributes.
  * Uses OWASP-compliant allowlist approach with regex-based parsing.

package/dist/utils/thinkingConfig.d.ts

@@ -11,32 +11,32 @@ export type ThinkingLevel = "minimal" | "low" | "medium" | "high";
 /**
  * ThinkingConfig interface matching the SDK's expected structure
  */
-export interface ThinkingConfig {
+export type ThinkingConfig = {
     enabled?: boolean;
     type?: "enabled" | "disabled";
     /** Token budget for thinking (Anthropic models: 5000-100000) */
     budgetTokens?: number;
     /** Thinking level for Gemini 3 models */
     thinkingLevel?: ThinkingLevel;
-}
+};
 /**
  * Options for creating a thinkingConfig from CLI-style options
  */
-export interface CreateThinkingConfigOptions {
+export type CreateThinkingConfigOptions = {
     /** Enable thinking mode */
     thinking?: boolean;
     /** Token budget for thinking (defaults to 10000) */
     thinkingBudget?: number;
     /** Thinking level for Gemini 3 models */
     thinkingLevel?: ThinkingLevel;
-}
+};
 /**
  * Native SDK thinkingConfig structure for Gemini native SDK.
  */
-export interface NativeThinkingConfig {
+export type NativeThinkingConfig = {
     includeThoughts: boolean;
     thinkingLevel: ThinkingLevel;
-}
+};
 /**
  * Default token budget for thinking operations
  */

package/dist/utils/timeout.d.ts

@@ -117,6 +117,16 @@ export declare function createTimeoutController(timeout: number | string | undef
     cleanup: () => void;
     timeoutMs: number;
 } | null;
+/**
+ * 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 declare function composeAbortSignals(externalSignal?: AbortSignal, timeoutSignal?: AbortSignal): AbortSignal | undefined;
 /**
  * Merge abort signals (for combining user abort with timeout)
  * @param signals - Array of abort signals to merge

package/dist/utils/timeout.js

@@ -320,6 +320,21 @@ export function createTimeoutController(timeout, provider, operation) {
     };
     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

package/dist/utils/tokenEstimation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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)
+ */
+import type { ChatMessage } from "../types/conversation.js";
+/** Characters per token for English text */
+export declare const CHARS_PER_TOKEN = 4;
+/** Characters per token for code */
+export declare const CODE_CHARS_PER_TOKEN = 3;
+/** Safety margin to avoid underestimation */
+export declare const TOKEN_SAFETY_MARGIN = 1.15;
+/** Message framing overhead in tokens (role + delimiters) */
+export declare const TOKENS_PER_MESSAGE = 4;
+/** Conversation-level overhead in tokens */
+export declare const TOKENS_PER_CONVERSATION = 24;
+/** Image token estimate (flat) */
+export declare const IMAGE_TOKEN_ESTIMATE = 1024;
+/**
+ * Get the token multiplier for a given provider.
+ */
+export declare function getProviderMultiplier(provider?: string): number;
+/**
+ * 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 declare function estimateTokens(text: string, provider?: string, isCode?: boolean): number;
+/**
+ * Estimate token count for a single ChatMessage.
+ * Includes message framing overhead.
+ */
+export declare function estimateMessageTokens(message: ChatMessage | {
+    role: string;
+    content: string;
+}, provider?: string): number;
+/**
+ * Estimate total token count for an array of messages.
+ * Includes conversation-level overhead.
+ */
+export declare function estimateMessagesTokens(messages: Array<ChatMessage | {
+    role: string;
+    content: string;
+}>, provider?: string): number;
+/**
+ * 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 declare function truncateToTokenBudget(text: string, maxTokens: number, provider?: string): {
+    text: string;
+    truncated: boolean;
+};

package/dist/utils/tokenEstimation.js

@@ -0,0 +1,112 @@
+/**
+ * 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 to avoid underestimation */
+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);
+    return Math.ceil(baseTokens * multiplier * TOKEN_SAFETY_MARGIN);
+}
+/**
+ * Estimate token count for a single ChatMessage.
+ * Includes message framing overhead.
+ */
+export function estimateMessageTokens(message, provider) {
+    const contentTokens = estimateTokens(message.content || "", 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);
+    const safetyFactor = multiplier * TOKEN_SAFETY_MARGIN;
+    const maxChars = Math.floor((maxTokens / safetyFactor) * 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/utils/tokenUtils.d.ts

@@ -12,7 +12,7 @@ import type { TokenUsage } from "../types/analytics.js";
  * Raw usage object that may come from various AI providers
  * Supports multiple naming conventions and nested structures
  */
-export interface RawUsageObject {
+export type RawUsageObject = {
     input?: number;
     output?: number;
     total?: number;
@@ -30,11 +30,11 @@ export interface RawUsageObject {
     reasoning_tokens?: number;
     thinkingTokens?: number;
     usage?: RawUsageObject;
-}
+};
 /**
  * Options for token extraction behavior
  */
-export interface TokenExtractionOptions {
+export type TokenExtractionOptions = {
     /**
      * Whether to calculate cache savings percentage
      * @default true
@@ -46,7 +46,7 @@ export interface TokenExtractionOptions {
      * - "undefined": Return undefined for missing optional fields (default)
      */
     missingOptionalBehavior?: "zero" | "undefined";
-}
+};
 /**
  * Extract input token count from various provider formats
  * Priority: input > inputTokens > promptTokens