@juspay/neurolink 12.9.6 → 12.11.0

package/dist/types/artifact.d.ts

@@ -7,6 +7,7 @@
  *
  * @module types/artifactTypes
  */
+import type { RedisStorageConfig } from "./conversation.js";
 /** Metadata recorded alongside a stored artifact. */
 export type ArtifactMeta = {
     /** Tool name that produced the output. */
@@ -83,10 +84,63 @@ export type ArtifactPageRequest = {
     limit?: number;
 };
 /**
- * Pluggable storage contract for externalized MCP tool outputs.
+ * One window of an artifact, as returned by `ArtifactStore.retrieveRange` or
+ * by the shared reader when the store only supports whole-payload reads.
  *
- * Default backend: LocalTempArtifactStore (filesystem, single-process).
- * Future backends can implement this interface for S3, Redis blobs, etc.
+ * Offsets and lengths are CHARACTERS (UTF-16 code units, the unit
+ * `String.prototype.slice` and `retrieve_context`'s `offset` / `limit` use),
+ * never bytes — so a model advancing `offset` by the characters it received
+ * lands exactly where the previous window ended.
+ */
+export type ArtifactWindow = {
+    /** The characters in `[offset, offset + content.length)`. */
+    content: string;
+    /** Character offset this window starts at. */
+    offset: number;
+    /** Total character length of the whole payload. */
+    totalLength: number;
+};
+/** One hit from a literal search over an artifact. */
+export type ArtifactSearchMatch = {
+    /** Character offset of the match — pass it back as `offset` to read there. */
+    offset: number;
+    /** 1-based line number the match sits on. */
+    line: number;
+    /** Character offset the snippet starts at (≤ `offset`). */
+    snippetOffset: number;
+    /**
+     * Bounded context around the match. Bounded on purpose: an MCP artifact is
+     * usually one compact JSON line, so "the matching line" would be the whole
+     * payload.
+     */
+    snippet: string;
+};
+/** Result of a literal search over an artifact. */
+export type ArtifactSearchResult = {
+    /** Matches returned, in payload order. */
+    matches: ArtifactSearchMatch[];
+    /** `matches.length`. */
+    matchCount: number;
+    /** Every match in the payload, including the ones not returned. */
+    totalMatches: number;
+    /** True when `totalMatches > matchCount`. */
+    truncated: boolean;
+    /** Character offset to pass as `offset` to search for the next matches. */
+    nextSearchOffset?: number;
+};
+/**
+ * Pluggable storage contract for externalized MCP tool outputs and banked
+ * payloads.
+ *
+ * Shipped backends: `LocalTempArtifactStore` (filesystem, per-process index
+ * with a cross-process sidecar) and `RedisArtifactStore` (TTL-expired, shared
+ * across replicas, range reads). Pick one with `artifacts.storage` or the
+ * `STORAGE_TYPE` environment variable, or inject any implementation via
+ * `artifacts.store` / `setArtifactStore()`.
+ *
+ * Only `store`, `retrieve`, `delete`, `cleanup` and `generatePreview` are
+ * required. `retrieveRange` and `close` are optional capabilities: NeuroLink
+ * uses them when present and falls back cleanly when absent.
  */
 export type ArtifactStore = {
     /**
@@ -100,6 +154,22 @@ export type ArtifactStore = {
      * Returns `null` if the artifact is not found or has been cleaned up.
      */
     retrieve(id: string): Promise<string | null>;
+    /**
+     * Retrieve one character window without materialising the whole payload.
+     *
+     * Optional. When present, `retrieve_context` and `readArtifact` call it for
+     * every paged read instead of `retrieve()` + slice, so a backend with native
+     * range reads (Redis `GETRANGE`, S3 `Range`) moves only the window. The
+     * result carries `totalLength` so `hasMore` never needs the payload.
+     *
+     * `offset` and `limit` are characters. A backend that can only address
+     * bytes must either know the payload is single-byte (ASCII) or fall back to
+     * a full read and slice — it must never return a window that starts at the
+     * wrong character. `limit` omitted means "to the end".
+     *
+     * Returns `null` if the artifact is not found or has expired.
+     */
+    retrieveRange?(id: string, range: ArtifactPageRequest): Promise<ArtifactWindow | null>;
     /** Delete a single artifact. No-op if the ID does not exist. */
     delete(id: string): Promise<void>;
     /**
@@ -109,6 +179,13 @@ export type ArtifactStore = {
     cleanup(olderThanMs: number): Promise<number>;
     /** Generate a short preview string from a serialized payload. */
     generatePreview(payload: string): string;
+    /**
+     * Release whatever the store holds open (a pooled connection, a file
+     * handle). Optional. NeuroLink calls it — from `shutdown()`, and when
+     * `setArtifactStore()` replaces the store — only for stores it built
+     * itself; a store you inject is yours to close.
+     */
+    close?(): Promise<void>;
 };
 /**
  * In-memory index row tracked by LocalTempArtifactStore.
@@ -122,3 +199,47 @@ export type IndexEntry = ArtifactMeta & {
      */
     rehydrated?: boolean;
 };
+/**
+ * Where artifacts live. Mirrors conversation memory's `STORAGE_TYPE`:
+ *  - "local"  OS temp directory, per-process index with a cross-process
+ *             sidecar. Fine for one machine; artifacts do not survive a pod.
+ *  - "redis"  Shared across replicas, expired by TTL, range reads via
+ *             `GETRANGE`. Uses the same connection pool as Redis conversation
+ *             memory.
+ */
+export type ArtifactStorageType = "local" | "redis";
+/**
+ * Artifact storage configuration (`new NeuroLink({ artifacts })`).
+ *
+ * Resolution order for the backend: `store` → `storage` → `STORAGE_TYPE`
+ * environment variable → `"local"`. Resolution order for the Redis connection:
+ * `redisConfig` → `conversationMemory.redisConfig` → `REDIS_URL` / `REDIS_HOST`
+ * environment variables — so a deployment already running conversation memory
+ * on Redis keeps its artifacts on the same Redis without new settings.
+ */
+export type ArtifactStorageConfig = {
+    /** Backend to use. Default: `STORAGE_TYPE` env var, else `"local"`. */
+    storage?: ArtifactStorageType;
+    /**
+     * Redis connection for `storage: "redis"`. `keyPrefix` defaults to
+     * `neurolink:artifact:` (NOT the conversation prefix). `ttl` is seconds,
+     * must be positive, and defaults to 86400; zero or negative is replaced by
+     * the default with a warning — artifacts in Redis always expire.
+     * `userSessionsKeyPrefix` is ignored.
+     */
+    redisConfig?: RedisStorageConfig;
+    /**
+     * A ready-made backend. Wins over `storage`. Use this for S3, a database,
+     * or a wrapped store; `setArtifactStore()` does the same after construction.
+     */
+    store?: ArtifactStore;
+};
+/**
+ * What `RedisArtifactStore` keeps beside each payload. `charLength` is what
+ * makes range reads honest: when it equals `sizeBytes` the payload is pure
+ * ASCII and a byte range IS a character range.
+ */
+export type RedisArtifactRecord = ArtifactMeta & {
+    /** `payload.length` at store time — characters, not bytes. */
+    charLength: number;
+};

package/dist/types/config.d.ts

@@ -6,6 +6,7 @@ import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
 import type { TaskManagerConfig } from "./task.js";
 import type { HITLConfig } from "../types/hitl.js";
 import type { ConversationMemoryConfig } from "./conversation.js";
+import type { ArtifactStorageConfig } from "./artifact.js";
 import type { ObservabilityConfig } from "./observability.js";
 import type { AuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, BetterAuthConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, AuthenticatedContext } from "./auth.js";
 import type { NeurolinkCredentials } from "./providers.js";
@@ -61,6 +62,12 @@ export type NeurolinkConstructorConfig = {
     modelAliasConfig?: ModelAliasConfig;
     /** MCP enhancement modules configuration (cache, router, batcher, annotations, middleware) */
     mcp?: MCPEnhancementsConfig;
+    /**
+     * Artifact storage: where externalized MCP tool outputs and banked payloads
+     * live. The backend follows `STORAGE_TYPE` exactly like conversation memory
+     * unless chosen here. See {@link ArtifactStorageConfig}.
+     */
+    artifacts?: ArtifactStorageConfig;
     /** Authentication provider configuration */
     auth?: NeuroLinkAuthConfig;
     /** TaskManager configuration (scheduled and self-running tasks) */

package/dist/types/generate.d.ts

@@ -1540,3 +1540,20 @@ export type ModelAliasConfig = {
 export type GenerateOptionsNormalized = GenerateOptions & {
     input: NonNullable<GenerateOptions["input"]>;
 };
+/**
+ * Per-call configuration for GenerationHandler's AI-SDK loop invocation,
+ * shared by the initial call and every fallback retry so they cannot drift.
+ */
+export type GenerationCallConfig = {
+    shouldUseTools: boolean;
+    includeStructuredOutput: boolean;
+    /** Anchor for the turn deadline — the ORIGINAL executeGeneration start,
+     *  shared across fallback/provider retries so they can't refresh the
+     *  wall-clock budget. */
+    turnStartMs: number;
+    /** Structured-output fallback retry: also spell the JSON Schema out in the
+     *  system prompt, for vendors that ignore `response_format`. */
+    promptJsonInstruction?: boolean;
+    /** Set on the single toolChoice:"none" re-ask so it can never recurse. */
+    isToolReask?: boolean;
+};

package/dist/types/openaiCompatible.d.ts

@@ -150,13 +150,17 @@ export type OpenAICompatChatStreamChunk = {
     choices: OpenAICompatStreamChunkChoice[];
     usage?: OpenAICompatUsage;
 };
+export type OpenAICompatErrorMessage = string | ReadonlyArray<{
+    msg?: string;
+}>;
 export type OpenAICompatErrorBody = {
     error?: {
-        message?: string;
+        message?: OpenAICompatErrorMessage;
         type?: string;
         code?: string | number;
         param?: string | null;
     };
+    detail?: string;
 };
 export type OpenAICompatConfig = {
     provider: string;

package/dist/types/providerCatalog.generated.d.ts

@@ -1,2 +1,2 @@
-export type CatalogProviderName = "cerebras" | "cloudflare" | "fireworks" | "groq" | "mistral" | "perplexity" | "sambanova" | "together-ai" | "xai";
-export type CatalogCredentialKey = "cerebras" | "cloudflare" | "fireworks" | "groq" | "mistral" | "perplexity" | "sambanova" | "together" | "xai";
+export type CatalogProviderName = "baseten" | "cerebras" | "cloudflare" | "fireworks" | "gmicloud" | "groq" | "inception-labs" | "io-intelligence" | "mistral" | "perplexity" | "sambanova" | "together-ai" | "upstage" | "xai";
+export type CatalogCredentialKey = "baseten" | "cerebras" | "cloudflare" | "fireworks" | "gmicloud" | "groq" | "inceptionLabs" | "ioIntelligence" | "mistral" | "perplexity" | "sambanova" | "together" | "upstage" | "xai";

package/dist/types/providers.d.ts

@@ -166,6 +166,10 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    baseten?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
     cerebras?: {
         apiKey?: string;
         baseURL?: string;
@@ -179,10 +183,22 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    gmicloud?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
     groq?: {
         apiKey?: string;
         baseURL?: string;
     };
+    inceptionLabs?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    ioIntelligence?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
     mistral?: {
         apiKey?: string;
         baseURL?: string;
@@ -199,6 +215,10 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    upstage?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
     xai?: {
         apiKey?: string;
         baseURL?: string;

package/dist/utils/redis.d.ts

@@ -3,6 +3,21 @@
  * Helper functions for Redis storage operations
  */
 import type { ChatMessage, RedisClient, RedisConversationObject, RedisStorageConfig } from "../types/index.js";
+/**
+ * Redact the userinfo of every `scheme://user:pass@host` in `text`.
+ *
+ * Deliberately not a regex. `/:\/\/[^@]+@/` and its relatives backtrack
+ * quadratically on input with many `://` and no `@` (CodeQL
+ * js/polynomial-redos), and the URL here can come straight from a caller —
+ * `RedisStorageConfig.url` reaches this through `RedisArtifactStore` and the
+ * conversation memory manager. One forward pass, every character visited a
+ * bounded number of times.
+ *
+ * Redacts everything before the LAST `@` of the authority, so a password
+ * containing `@` is still hidden. A URL with only a user name is redacted
+ * too; the old regexes let that through.
+ */
+export declare function redactUrlCredentials(text: string): string;
 /**
  * Get a pooled Redis connection. Multiple callers with the same host:port:db
  * share a single connection, reducing connection count.

package/dist/utils/redis.js

@@ -6,17 +6,75 @@ import { randomUUID } from "crypto";
 import { createClient } from "redis";
 import { logger } from "./logger.js";
 const SESSION_ONLY_PREFIX = "session-only:";
+/** Characters that end the authority (`user:pass@host:port`) of a URL in text. */
+const AUTHORITY_TERMINATORS = new Set(["/", "?", "#", " ", "\t", "\n", "\r"]);
+/**
+ * Redact the userinfo of every `scheme://user:pass@host` in `text`.
+ *
+ * Deliberately not a regex. `/:\/\/[^@]+@/` and its relatives backtrack
+ * quadratically on input with many `://` and no `@` (CodeQL
+ * js/polynomial-redos), and the URL here can come straight from a caller —
+ * `RedisStorageConfig.url` reaches this through `RedisArtifactStore` and the
+ * conversation memory manager. One forward pass, every character visited a
+ * bounded number of times.
+ *
+ * Redacts everything before the LAST `@` of the authority, so a password
+ * containing `@` is still hidden. A URL with only a user name is redacted
+ * too; the old regexes let that through.
+ */
+export function redactUrlCredentials(text) {
+    let out = "";
+    let cursor = 0;
+    for (;;) {
+        const schemeEnd = text.indexOf("://", cursor);
+        if (schemeEnd === -1) {
+            return out + text.slice(cursor);
+        }
+        const authorityStart = schemeEnd + 3;
+        let authorityEnd = authorityStart;
+        let lastAt = -1;
+        while (authorityEnd < text.length) {
+            const ch = text[authorityEnd];
+            if (AUTHORITY_TERMINATORS.has(ch)) {
+                break;
+            }
+            if (ch === "@") {
+                lastAt = authorityEnd;
+            }
+            authorityEnd += 1;
+        }
+        if (lastAt === -1) {
+            out += text.slice(cursor, authorityEnd);
+            cursor = authorityEnd;
+        }
+        else {
+            out += `${text.slice(cursor, authorityStart)}[redacted]@`;
+            cursor = lastAt + 1;
+        }
+    }
+}
 // Connection pool - keyed by host:port:db
 const connectionPool = new Map();
 const pendingConnections = new Map();
+/**
+ * One pool key per distinct connection. Shared by acquire AND release: they
+ * used to compute it separately, and the release side never knew about the
+ * `url:` form, so a URL-configured client was acquired under one key and
+ * "released" under another that did not exist — its reference count never
+ * dropped and the connection outlived every owner. Credentials never appear
+ * in the key; it is logged.
+ */
+function poolKeyFor(config) {
+    return config.url
+        ? `url:${redactUrlCredentials(config.url)}`
+        : `${config.host}:${config.port}:${config.db}:${config.password ? "auth" : "noauth"}`;
+}
 /**
  * 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.url
-        ? `url:${config.url.replace(/:\/\/[^:]+:[^@]+@/, "://[redacted]@")}`
-        : `${config.host}:${config.port}:${config.db}:${config.password ? "auth" : "noauth"}`;
+    const key = poolKeyFor(config);
     const existing = connectionPool.get(key);
     if (existing && existing.client.isOpen) {
         existing.refCount++;
@@ -77,7 +135,7 @@ export async function getPooledRedisClient(config) {
  * 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 key = poolKeyFor(config);
     const entry = connectionPool.get(key);
     if (!entry) {
         return;
@@ -140,7 +198,7 @@ export async function createRedisClient(config) {
     // Create client with secured options
     const client = createClient(clientOptions);
     client.on("error", (err) => {
-        const sanitizedMessage = err.message.replace(/redis:\/\/.*?@/g, "redis://[redacted]@");
+        const sanitizedMessage = redactUrlCredentials(err.message);
         logger.error("Redis client error", { error: sanitizedMessage });
     });
     client.on("connect", () => {
@@ -420,7 +478,7 @@ export function getNormalizedConfig(config) {
                 : 0;
         }
         catch (e) {
-            const sanitizedUrl = url.replace(/:\/\/[^@]+@/, "://[redacted]@");
+            const sanitizedUrl = redactUrlCredentials(url);
             logger.warn("[redisUtils] Failed to parse Redis URL, falling back to component-based connection", {
                 url: sanitizedUrl,
                 error: e instanceof Error ? e.message : String(e),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.9.6",
+  "version": "12.11.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -456,7 +456,7 @@
     "exceljs": "^4.4.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.2.1",
-    "fastify": "^5.8.5",
+    "fastify": "^5.12.1",
     "ffmpeg-static": "^5.3.0",
     "fluent-ffmpeg": "^2.1.3",
     "koa": "^3.1.1",
@@ -605,7 +605,7 @@
       "@opentelemetry/sdk-trace-node": "^2.6.0",
       "jws@<4.0.1": ">=4.0.1",
       "tar@<7.5.8": ">=7.5.8",
-      "qs@<6.15.2": ">=6.15.2",
+      "qs@<6.16.0": ">=6.16.0",
       "minimatch@>=10.0.0 <10.2.3": ">=10.2.3",
       "minimatch@>=9.0.0 <9.0.7": ">=9.0.7",
       "typedoc>minimatch": ">=10.2.3",
@@ -622,7 +622,7 @@
       "ajv@>=8.0.0 <8.18.0": ">=8.18.0",
       "@grpc/grpc-js@<1.14.4": ">=1.14.4",
       "@protobufjs/utf8@<1.1.1": ">=1.1.1",
-      "fast-uri@<3.1.5": ">=3.1.5 <4",
+      "fast-uri@<3.1.6": ">=3.1.6 <4",
       "ip-address@<10.1.1": ">=10.1.1",
       "basic-ftp@<5.2.2": ">=5.2.2",
       "fast-xml-builder@<1.1.7": ">=1.1.7",
@@ -632,10 +632,14 @@
       "undici@>=8.0.0": ">=7.24.0 <8.0.0",
       "pdfjs-dist": "5.4.624",
       "markdown-it@<14.2.0": ">=14.2.0",
-      "@xmldom/xmldom@<0.9.11": ">=0.9.11",
+      "@xmldom/xmldom@<0.9.12": ">=0.9.12",
       "protobufjs@<7.6.5": ">=7.6.5",
       "brace-expansion@>=5.0.0 <5.0.9": ">=5.0.9",
-      "@opentelemetry/core@>=2.0.0 <2.8.0": ">=2.8.0"
+      "@opentelemetry/core@>=2.0.0 <2.8.0": ">=2.8.0",
+      "qs": "6.16.0",
+      "fastify": "5.12.1",
+      "fast-uri": "3.1.6",
+      "@xmldom/xmldom": "0.9.12"
     },
     "patchedDependencies": {
       "mammoth@1.12.0": "patches/mammoth@1.12.0.patch"