@juspay/neurolink 12.14.8 → 12.14.10

package/dist/providers/googleVertex/client.js

@@ -977,9 +977,13 @@ export class GoogleVertexProvider extends BaseProvider {
     async createVertexGenAIClient(regionOverride) {
         warnGoogleSdkIgnoresProxy("GoogleVertex");
         const expressApiKey = this.resolveExpressApiKey();
-        // Resolved only on the ADC path: getVertexProjectId() throws when no
-        // project is configured, which an Express request legitimately has none of.
-        const project = expressApiKey ? "" : getVertexProjectId();
+        // Resolved only on the ADC path, and from the per-instance projectId the
+        // constructor already settled (credentials.projectId if supplied, else
+        // the same ambient getVertexProjectId() fallback) — not re-read from
+        // ambient env here, or a per-request projectId override would be built
+        // into the client with the wrong project while call sites elsewhere
+        // (generateContent's `project:` param) correctly used this.projectId.
+        const project = expressApiKey ? "" : this.projectId;
         const location = regionOverride || this.location || getVertexLocation();
         const mod = await import("@google/genai");
         const ctor = mod.GoogleGenAI;
@@ -1060,94 +1064,6 @@ export class GoogleVertexProvider extends BaseProvider {
         ].some((name) => (process.env[name] ?? "").trim().length > 0);
         return projectConfigured ? undefined : fromEnv;
     }
-    /**
-     * Convert one AI-SDK tool into a Vertex Gemini function declaration.
-     * Single source for the pre-loop snapshot AND the mid-turn discovery
-     * refresh, so tools hydrated by search_tools get the exact same schema
-     * treatment (inline, typed, additionalProperties stripped).
-     */
-    buildGeminiFunctionDeclaration(name, tool) {
-        const decl = {
-            name,
-            description: tool.description || `Tool: ${name}`,
-        };
-        // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
-        const legacyTool = tool;
-        const toolParams = legacyTool.parameters || tool.inputSchema;
-        if (toolParams) {
-            // Convert and inline schema to resolve $ref/definitions
-            const rawSchema = convertZodToJsonSchema(toolParams, "openApi3");
-            const inlinedSchema = inlineJsonSchema(rawSchema);
-            // Remove $schema if present - @google/genai doesn't need it
-            if (inlinedSchema.$schema) {
-                delete inlinedSchema.$schema;
-            }
-            // CRITICAL: Google Vertex AI requires ALL nested schemas to have a type field
-            // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
-            // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
-            const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
-            // Strip `additionalProperties` recursively — Vertex Gemini's
-            // function-call validator rejects it on object schemas (returns
-            // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
-            // field has no semantic meaning to the model, so dropping it
-            // before send is safe for every caller.
-            stripAdditionalPropertiesDeep(typedSchema);
-            decl.parametersJsonSchema = typedSchema;
-        }
-        return decl;
-    }
-    /**
-     * Mid-turn tool sync for the native Gemini loops. `search_tools` hydrates
-     * discovered tools into the live `options.tools` record between steps, but
-     * the loop's declarations + executeMap are a pre-loop snapshot — without
-     * this refresh, a tool discovered this turn stays invisible to the rest of
-     * the turn and every call to it dies as TOOL_NOT_FOUND. Mutates the
-     * declaration array in place (the request config holds it by reference)
-     * and clears breaker strikes accrued while the tool was still deferred.
-     */
-    refreshGeminiToolDeclarations(liveTools, declarations, executeMap, failedTools) {
-        if (!liveTools || !declarations) {
-            return;
-        }
-        const declared = new Set(declarations.map((d) => d.name));
-        for (const [name, tool] of Object.entries(liveTools)) {
-            if (declared.has(name)) {
-                continue;
-            }
-            declarations.push(this.buildGeminiFunctionDeclaration(name, tool));
-            if (tool.execute) {
-                executeMap.set(name, tool.execute);
-            }
-            failedTools.delete(name);
-            logger.info(`[GoogleVertex] Tool "${name}" hydrated mid-turn via discovery — added to Gemini declarations.`);
-        }
-    }
-    /**
-     * Dispatch-miss recovery for the native Gemini loops: the model called a
-     * name missing from the executeMap snapshot. Re-read the live record (a
-     * tool hydrated by search_tools in this very step batch) or auto-hydrate a
-     * deferred catalog tool the model called directly by its advertised name.
-     * Returns the dedup-wrapped executor, or undefined when the name is
-     * genuinely unknown — callers keep TOOL_NOT_FOUND for that case.
-     */
-    resolveGeminiToolOnMiss(name, liveTools, declarations, executeMap, failedTools) {
-        if (!declarations) {
-            return undefined;
-        }
-        const tool = resolveLiveTool(liveTools, name);
-        if (!tool?.execute) {
-            return undefined;
-        }
-        if (!declarations.some((d) => d.name === name)) {
-            declarations.push(this.buildGeminiFunctionDeclaration(name, tool));
-        }
-        executeMap.set(name, tool.execute);
-        // NOT_FOUND strikes accrued while the tool was deferred are snapshot
-        // artifacts, not real failures — reset so the breaker starts clean.
-        failedTools.delete(name);
-        logger.info(`[GoogleVertex] Tool "${name}" resolved mid-turn via discovery — executing.`);
-        return executeMap.get(name);
-    }
     /**
      * Convert one AI-SDK tool into an Anthropic (Claude-on-Vertex) tool
      * declaration. Single source for the pre-loop snapshot AND the mid-turn
@@ -1179,8 +1095,7 @@ export class GoogleVertexProvider extends BaseProvider {
         return anthropicTool;
     }
     /**
-     * Mid-turn tool sync for the Claude-on-Vertex loops — the Anthropic
-     * counterpart of refreshGeminiToolDeclarations. Claude only calls tools
+     * Mid-turn tool sync for the Claude-on-Vertex loops. Claude only calls tools
      * present in the request's `tools` array, so without this per-step refresh
      * a tool discovered via search_tools is unreachable for the rest of the
      * turn. Mutates the array in place (requestParams holds it by reference).
@@ -1203,8 +1118,7 @@ export class GoogleVertexProvider extends BaseProvider {
         }
     }
     /**
-     * Dispatch-miss recovery for the Claude-on-Vertex loops — the Anthropic
-     * counterpart of resolveGeminiToolOnMiss.
+     * Dispatch-miss recovery for the Claude-on-Vertex loops.
      */
     resolveAnthropicToolOnMiss(name, liveTools, declarations, executeMap, failedTools) {
         if (!declarations) {
@@ -1222,6 +1136,31 @@ export class GoogleVertexProvider extends BaseProvider {
         logger.info(`[GoogleVertex] Tool "${name}" resolved mid-turn via discovery — executing.`);
         return executeMap.get(name);
     }
+    /**
+     * Build the synthetic `final_result` tool used to force structured output
+     * on Claude-on-Vertex. Anthropic has no native responseSchema, so a schema
+     * is instead enforced by requiring the model to call this tool with
+     * matching arguments. Single source for the non-streaming and streaming
+     * paths — both previously built this object independently from their own
+     * schema variable, byte-identical apart from that variable's name.
+     */
+    buildFinalResultTool(schema) {
+        const schemaAsJson = convertZodToJsonSchema(schema);
+        const inlinedSchema = inlineJsonSchema(schemaAsJson);
+        if (inlinedSchema.$schema) {
+            delete inlinedSchema.$schema;
+        }
+        const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
+        return {
+            name: "final_result",
+            description: "Return the final structured result. You MUST call this tool when you have gathered all information and are ready to provide the final answer. The arguments should contain the structured data matching the expected schema.",
+            input_schema: {
+                type: "object",
+                properties: typedSchema.properties || typedSchema,
+                required: typedSchema.required || [],
+            },
+        };
+    }
     /**
      * Execute stream using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
@@ -3132,23 +3071,8 @@ export class GoogleVertexProvider extends BaseProvider {
         let schemaSystemPromptSuffix = "";
         if (streamOptions.schema) {
             useFinalResultTool = true;
-            // Convert schema to JSON schema format
-            const schemaAsJson = convertZodToJsonSchema(streamOptions.schema);
-            const inlinedSchema = inlineJsonSchema(schemaAsJson);
-            if (inlinedSchema.$schema) {
-                delete inlinedSchema.$schema;
-            }
-            const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
             // Create final_result tool
-            const finalResultTool = {
-                name: "final_result",
-                description: "Return the final structured result. You MUST call this tool when you have gathered all information and are ready to provide the final answer. The arguments should contain the structured data matching the expected schema.",
-                input_schema: {
-                    type: "object",
-                    properties: typedSchema.properties || typedSchema,
-                    required: typedSchema.required || [],
-                },
-            };
+            const finalResultTool = this.buildFinalResultTool(streamOptions.schema);
             // Add to tools array or create new array
             if (!tools) {
                 tools = [];
@@ -3158,7 +3082,7 @@ export class GoogleVertexProvider extends BaseProvider {
             schemaSystemPromptSuffix =
                 "\n\nIMPORTANT: You MUST call the 'final_result' tool to return your response in the required structured format. Do not respond with plain text - always use the final_result tool.";
             logger.debug("[GoogleVertex] Added final_result tool for Anthropic structured output (stream)", {
-                schemaKeys: Object.keys(typedSchema),
+                schemaKeys: Object.keys(finalResultTool.input_schema.properties ?? {}),
                 totalTools: tools.length,
             });
         }
@@ -3719,10 +3643,19 @@ export class GoogleVertexProvider extends BaseProvider {
                     // with text in step 2 would look unfinished and fall into terminal
                     // handling. The finish reason is the per-turn signal — the engine
                     // reports "tool-calls" only when the cap was hit with tools still
-                    // pending.
+                    // pending. That signal is not enough on its own, though: Anthropic
+                    // reports stop_reason "tool_use" — which maps to finishReason
+                    // "tool-calls" — for ANY tool_use block, including a genuine
+                    // terminal `final_result` call. Without the third clause, a turn
+                    // that called a real tool earlier (toolCalls.length > 0) and then
+                    // legitimately finished via final_result reads as unfinished and
+                    // falls into the terminal-handling block below, which forces a
+                    // redundant second final_result call and pushes its JSON onto the
+                    // stream a second time.
                     modelFinished =
                         engineResult.toolCalls.length === 0 ||
-                            engineResult.finishReason !== "tool-calls";
+                            engineResult.finishReason !== "tool-calls" ||
+                            (useFinalResultTool && structuredOutputRef.value !== undefined);
                     // Replace in place: the terminal block and the finalization call both
                     // read `currentMessages`.
                     currentMessages.length = 0;
@@ -4361,23 +4294,8 @@ export class GoogleVertexProvider extends BaseProvider {
         let schemaSystemPromptSuffix = "";
         if (options.schema) {
             useFinalResultTool = true;
-            // Convert schema to JSON schema format
-            const schemaAsJson = convertZodToJsonSchema(options.schema);
-            const inlinedSchema = inlineJsonSchema(schemaAsJson);
-            if (inlinedSchema.$schema) {
-                delete inlinedSchema.$schema;
-            }
-            const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
             // Create final_result tool
-            const finalResultTool = {
-                name: "final_result",
-                description: "Return the final structured result. You MUST call this tool when you have gathered all information and are ready to provide the final answer. The arguments should contain the structured data matching the expected schema.",
-                input_schema: {
-                    type: "object",
-                    properties: typedSchema.properties || typedSchema,
-                    required: typedSchema.required || [],
-                },
-            };
+            const finalResultTool = this.buildFinalResultTool(options.schema);
             // Add to tools array or create new array
             if (!tools) {
                 tools = [];
@@ -4387,7 +4305,7 @@ export class GoogleVertexProvider extends BaseProvider {
             schemaSystemPromptSuffix =
                 "\n\nIMPORTANT: You MUST call the 'final_result' tool to return your response in the required structured format. Do not respond with plain text - always use the final_result tool.";
             logger.debug("[GoogleVertex] Added final_result tool for Anthropic structured output (generate)", {
-                schemaKeys: Object.keys(typedSchema),
+                schemaKeys: Object.keys(finalResultTool.input_schema.properties ?? {}),
                 totalTools: tools.length,
             });
         }

package/dist/providers/huggingFace/client.d.ts

@@ -19,13 +19,36 @@ export declare class HuggingFaceProvider extends OpenAIChatCompletionsProvider {
     protected getDefaultModel(): string;
     protected getFallbackModelName(): string;
     /**
-     * HuggingFace serves a huge variety of models, many of which reject the
-     * OpenAI `tools` field. The base reports supportsTools() === true
-     * unconditionally, which would merge tools into requests for models
-     * (including the default DialoGPT-medium) that don't accept them. Preserve
-     * the pre-migration allowlist: only known tool-calling-capable model
-     * families opt in; everything else runs tool-free.
+     * Tool support is resolved by the base through MODEL_REGISTRY's
+     * `modelSupports()` facade, which defaults unknown models to supported.
+     *
+     * This class used to override that with a 13-entry allowlist of model-name
+     * substrings, written for the old per-model Inference API where many
+     * endpoints rejected the OpenAI `tools` field. The router replaced that, and
+     * the list did not keep up. Measured against the 142 models
+     * `GET router.huggingface.co/v1/models` served on 2026-09-13 (the
+     * catalogue drifts, so treat the totals as a snapshot; the ratio is the
+     * point):
+     *
+     *   allowlist entries matching ANY served model   1 of 13
+     *   served models the allowlist ADMITS            1 of 142
+     *   served models the allowlist BLOCKS          141
+     *
+     * So it suppressed tool calling for 99% of the catalogue, including
+     * Qwen/Qwen2.5-72B-Instruct, which the router demonstrably tool-calls. A
+     * spread of the blocked models — GLM-5.3-Flash, gemma-4-31B-it,
+     * DeepSeek-V4-Flash — all accept `tools` with HTTP 200 and return
+     * `tool_calls`; none rejected the field.
+     *
+     * The allowlist's own comment named `microsoft/DialoGPT-medium` — which
+     * `getDefaultModel()`, not `getFallbackModelName()`, used to return — as a
+     * model that rejects `tools`. The router does not serve it under any
+     * request shape, so that path was never reachable; the default now points
+     * at a served model (see `getDefaultHuggingFaceModel`).
+     *
+     * A model that genuinely cannot use tools simply does not emit `tool_calls`,
+     * which the loop already handles, so the optimistic default costs nothing
+     * that the allowlist was protecting.
      */
-    supportsTools(): boolean;
     protected formatProviderError(error: unknown): Error;
 }

package/dist/providers/huggingFace/client.js

@@ -1,3 +1,4 @@
+import { HuggingFaceModels } from "../../constants/enums.js";
 import { AuthenticationError, InvalidModelError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../../utils/errorClassifier.js";
 import { logger } from "../../utils/logger.js";
@@ -6,7 +7,19 @@ import { createHuggingFaceConfig, getProviderModel, validateApiKey, } from "../.
 import { OpenAIChatCompletionsProvider } from "../openaiChatCompletionsBase.js";
 const HUGGINGFACE_DEFAULT_BASE_URL = "https://router.huggingface.co/v1";
 const getHuggingFaceApiKey = () => validateApiKey(createHuggingFaceConfig());
-const getDefaultHuggingFaceModel = () => getProviderModel("HUGGINGFACE_MODEL", "microsoft/DialoGPT-medium");
+/**
+ * Must stay the same id `providerRegistry` passes as the registration default
+ * (`process.env.HUGGINGFACE_MODEL || HuggingFaceModels.QWEN_2_5_72B_INSTRUCT`),
+ * hence the shared constant rather than a second literal.
+ *
+ * The registry supplies `modelName` on every factory-created provider, so this
+ * only decides a directly-constructed `new HuggingFaceProvider()`. It still
+ * matters: it previously read `microsoft/DialoGPT-medium`, which the router
+ * does not serve under any request shape — it answers 400 "not supported by
+ * any provider you have enabled" with or without `tools` — and that stale id
+ * was what the docs and setup guidance advertised as the default.
+ */
+const getDefaultHuggingFaceModel = () => getProviderModel("HUGGINGFACE_MODEL", HuggingFaceModels.QWEN_2_5_72B_INSTRUCT);
 /**
  * HuggingFace Provider — direct HTTP, no AI SDK.
  *
@@ -47,32 +60,37 @@ export class HuggingFaceProvider extends OpenAIChatCompletionsProvider {
         return "meta-llama/Llama-3.1-8B-Instruct";
     }
     /**
-     * HuggingFace serves a huge variety of models, many of which reject the
-     * OpenAI `tools` field. The base reports supportsTools() === true
-     * unconditionally, which would merge tools into requests for models
-     * (including the default DialoGPT-medium) that don't accept them. Preserve
-     * the pre-migration allowlist: only known tool-calling-capable model
-     * families opt in; everything else runs tool-free.
+     * Tool support is resolved by the base through MODEL_REGISTRY's
+     * `modelSupports()` facade, which defaults unknown models to supported.
+     *
+     * This class used to override that with a 13-entry allowlist of model-name
+     * substrings, written for the old per-model Inference API where many
+     * endpoints rejected the OpenAI `tools` field. The router replaced that, and
+     * the list did not keep up. Measured against the 142 models
+     * `GET router.huggingface.co/v1/models` served on 2026-09-13 (the
+     * catalogue drifts, so treat the totals as a snapshot; the ratio is the
+     * point):
+     *
+     *   allowlist entries matching ANY served model   1 of 13
+     *   served models the allowlist ADMITS            1 of 142
+     *   served models the allowlist BLOCKS          141
+     *
+     * So it suppressed tool calling for 99% of the catalogue, including
+     * Qwen/Qwen2.5-72B-Instruct, which the router demonstrably tool-calls. A
+     * spread of the blocked models — GLM-5.3-Flash, gemma-4-31B-it,
+     * DeepSeek-V4-Flash — all accept `tools` with HTTP 200 and return
+     * `tool_calls`; none rejected the field.
+     *
+     * The allowlist's own comment named `microsoft/DialoGPT-medium` — which
+     * `getDefaultModel()`, not `getFallbackModelName()`, used to return — as a
+     * model that rejects `tools`. The router does not serve it under any
+     * request shape, so that path was never reachable; the default now points
+     * at a served model (see `getDefaultHuggingFaceModel`).
+     *
+     * A model that genuinely cannot use tools simply does not emit `tool_calls`,
+     * which the loop already handles, so the optimistic default costs nothing
+     * that the allowlist was protecting.
      */
-    supportsTools() {
-        const modelName = this.modelName.toLowerCase();
-        const toolCapableModels = [
-            "llama-3.1-8b-instruct",
-            "llama-3.1-70b-instruct",
-            "llama-3.1-405b-instruct",
-            "llama-3.1-nemotron-ultra",
-            "hermes-3-llama-3.2",
-            "hermes-2-pro",
-            "codellama-34b-instruct",
-            "codellama-13b-instruct",
-            "mistral-7b-instruct-v0.3",
-            "mistral-8x7b-instruct",
-            "nous-hermes",
-            "openchat",
-            "wizardcoder",
-        ];
-        return toolCapableModels.some((capable) => modelName.includes(capable));
-    }
     formatProviderError(error) {
         const rules = [
             {
@@ -97,6 +115,6 @@ export class HuggingFaceProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "huggingface", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
 }

package/dist/providers/llamaCpp.js

@@ -74,6 +74,6 @@ export class LlamaCppProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "llamacpp", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
 }

package/dist/providers/lmStudio.js

@@ -69,7 +69,7 @@ export class LMStudioProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "lm-studio", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
     async validateConfiguration() {
         return this.probeModelsEndpoint(this.config.apiKey && this.config.apiKey !== LM_STUDIO_PLACEHOLDER_KEY

package/dist/providers/nvidiaNim/client.js

@@ -281,7 +281,7 @@ export class NvidiaNimProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "nvidia-nim", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
     async validateConfiguration() {
         return (typeof this.config.apiKey === "string" &&

package/dist/providers/ollama/client.js

@@ -136,7 +136,7 @@ export class OllamaProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "ollama", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
     // ===========================================================================
     // Optional hooks — Ollama-specific behaviour

package/dist/providers/openRouter/client.js

@@ -149,7 +149,7 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "openrouter", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
     // ===========================================================================
     // Optional hooks — provider-specific quirks

package/dist/providers/openaiCompatible/client.js

@@ -85,6 +85,6 @@ export class OpenAICompatibleProvider extends OpenAIChatCompletionsProvider {
             },
             ...DEFAULT_ERROR_RULES,
         ];
-        return classifyProviderError(error, rules, "openai-compatible", this.modelName);
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
 }

package/dist/utils/providerSetupMessages.js

@@ -71,8 +71,8 @@ export function getProviderSetupMessage(provider, missingVars) {
             envVars: [
                 'HUGGINGFACE_API_KEY="hf_your_huggingface_token"',
                 "# Optional:",
-                'HUGGINGFACE_MODEL="microsoft/DialoGPT-medium"',
-                'HUGGINGFACE_ENDPOINT="https://api-inference.huggingface.co"',
+                'HUGGINGFACE_MODEL="Qwen/Qwen2.5-72B-Instruct"',
+                'HUGGINGFACE_BASE_URL="https://router.huggingface.co/v1"',
             ],
         },
         mistral: {

package/dist/utils/timeout.d.ts

@@ -5,10 +5,21 @@
  * Supports multiple time formats: milliseconds, seconds, minutes, hours.
  */
 import type { TimeoutConfig, TimeoutResult } from "../types/index.js";
+import { TimeoutError as BaseTimeoutError } from "./async/withTimeout.js";
 /**
- * Custom error class for timeout operations
+ * Custom error class for timeout operations.
+ *
+ * Extends the base {@link BaseTimeoutError} (from `./async/withTimeout.js`)
+ * rather than `Error` directly, merging what were two independent internal
+ * `TimeoutError` classes onto one prototype chain — an `instanceof` check
+ * against either module's `TimeoutError` now recognizes errors thrown by
+ * this class. Constructor signature, `.name`, and the extra
+ * `timeout`/`provider`/`operation` fields are unchanged so all 15 existing
+ * `instanceof TimeoutError` call sites keep working exactly as before;
+ * `super(message, timeout)` additionally populates the base class's
+ * `timeoutMs` field (equal to `timeout`) as a byproduct.
  */
-export declare class TimeoutError extends Error {
+export declare class TimeoutError extends BaseTimeoutError {
     readonly timeout: number;
     readonly provider?: string | undefined;
     readonly operation?: "generate" | "stream" | undefined;

package/dist/utils/timeout.js

@@ -4,15 +4,26 @@
  * Provides flexible timeout parsing and error handling for AI operations.
  * Supports multiple time formats: milliseconds, seconds, minutes, hours.
  */
+import { TimeoutError as BaseTimeoutError } from "./async/withTimeout.js";
 /**
- * Custom error class for timeout operations
+ * Custom error class for timeout operations.
+ *
+ * Extends the base {@link BaseTimeoutError} (from `./async/withTimeout.js`)
+ * rather than `Error` directly, merging what were two independent internal
+ * `TimeoutError` classes onto one prototype chain — an `instanceof` check
+ * against either module's `TimeoutError` now recognizes errors thrown by
+ * this class. Constructor signature, `.name`, and the extra
+ * `timeout`/`provider`/`operation` fields are unchanged so all 15 existing
+ * `instanceof TimeoutError` call sites keep working exactly as before;
+ * `super(message, timeout)` additionally populates the base class's
+ * `timeoutMs` field (equal to `timeout`) as a byproduct.
  */
-export class TimeoutError extends Error {
+export class TimeoutError extends BaseTimeoutError {
     timeout;
     provider;
     operation;
     constructor(message, timeout, provider, operation) {
-        super(message);
+        super(message, timeout);
         this.timeout = timeout;
         this.provider = provider;
         this.operation = operation;