@juspay/neurolink 12.11.2 → 12.12.0

package/dist/core/nativeGenerateLoop.js

@@ -0,0 +1,261 @@
+/**
+ * The multi-step tool loop that the ai package's `generateText` used to supply.
+ *
+ * It deliberately loops over a provider's own `doGenerate` rather than over any
+ * streaming machinery. That is the whole lesson of the reverted first attempt:
+ * `doGenerate` is where the JSON-versus-SSE wire choice lives, along with the
+ * 400 retry, the context-overflow refit and the provider's own structured-output
+ * handling. Looping around the streaming path instead silently changed
+ * generate() to send `stream: true` and broke ten providers against a
+ * non-streaming body.
+ *
+ * Every provider whose delegating model exposes a v3-shaped `doGenerate` can
+ * share this: the v3 result shape (`content` parts, `finishReason`, `usage`) is
+ * the same across Anthropic, the OpenAI-compatible family and SageMaker.
+ */
+import { guardToolExecutor } from "./toolExecutionGuards.js";
+/**
+ * Narrow a model handle to the delegating shape this loop drives.
+ * `LanguageModel` is a union that includes a bare string id, and a double
+ * assertion through unknown is banned by Critical Rule 14.
+ */
+export const hasNativeDoGenerate = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.doGenerate === "function";
+const asParts = (value) => Array.isArray(value) ? value : [];
+const readTotal = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.total === "number"
+    ? value.total
+    : 0;
+/**
+ * Parse a tool call's arguments, distinguishing "no arguments" from "the model
+ * emitted something that is not JSON". Silently substituting `{}` for the
+ * second case ran the tool with empty input and reported success, so a
+ * malformed call looked identical to a legitimate no-arg one.
+ */
+const parseToolInput = (raw) => {
+    if (typeof raw !== "string") {
+        return { input: raw ?? {} };
+    }
+    if (raw.trim() === "") {
+        return { input: {} };
+    }
+    try {
+        return { input: JSON.parse(raw) };
+    }
+    catch {
+        return { input: {}, error: "arguments were not valid JSON" };
+    }
+};
+/**
+ * Validate parsed input against the tool's own schema when it exposes one.
+ *
+ * `generateText` validated tool input before dispatch; the native loop did
+ * not, so a call whose shape the tool rejects reached `execute` and failed
+ * inside user code — or worse, did not fail. A Zod schema is detected by
+ * `safeParse`; anything else is passed through, since a JSON Schema needs a
+ * validator this loop has no business carrying.
+ */
+const validateToolInput = (tool, input) => {
+    const schema = tool?.inputSchema;
+    if (typeof schema?.safeParse !== "function") {
+        return undefined;
+    }
+    const result = schema.safeParse(input);
+    if (result.success) {
+        return undefined;
+    }
+    const detail = result.error instanceof Error ? result.error.message : "schema mismatch";
+    return `input did not match the tool's schema: ${detail}`;
+};
+/**
+ * Spell a JSON Schema into the conversation's system turn.
+ *
+ * The structured-output fallback for vendors that reject or ignore
+ * `response_format`. Merged into an existing trailing system message rather
+ * than appended as a second one: several self-hosted OpenAI-compatible stacks
+ * honour only the first system message, so a second would be dropped and the
+ * fallback would silently do nothing.
+ */
+export const appendJsonSchemaInstruction = (conversation, schema) => {
+    const instruction = "When you give your final answer, respond with only a single JSON object " +
+        "that conforms to the following JSON Schema. No prose before or after it, " +
+        `and no markdown code fence. JSON Schema: ${JSON.stringify(schema)}`;
+    const lastSystemIndex = conversation.reduce((found, message, index) => (message.role === "system" ? index : found), -1);
+    if (lastSystemIndex === -1) {
+        return [{ role: "system", content: instruction }, ...conversation];
+    }
+    const existing = conversation[lastSystemIndex];
+    const content = typeof existing.content === "string"
+        ? `${existing.content}\n\n${instruction}`
+        : instruction;
+    return conversation.map((message, index) => index === lastSystemIndex ? { ...message, content } : message);
+};
+export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
+    const toolsUsed = [];
+    let text = "";
+    let finishReason = "stop";
+    let rawFinishReason;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let steps = 0;
+    // One bounded recovery re-ask per turn; see the empty-tool-calls branch.
+    let reasked = false;
+    const hasTools = Boolean(args.tools && args.tools.length > 0);
+    for (let step = 0; step < args.maxSteps; step++) {
+        steps = step + 1;
+        const res = await args.runStep(() => args.doGenerate({
+            prompt: args.conversation,
+            ...(args.tools && args.tools.length > 0 ? { tools: args.tools } : {}),
+            // The v3 call option is an OBJECT — `{ type: "none" }`. Passing the
+            // bare string "none" type-checks against `unknown` and is then
+            // dropped by every converter that switches on `choice.type`, so the
+            // re-ask silently went out unchanged. Caught by the stand-in asserting
+            // the wire body, not by any live provider.
+            ...(reasked
+                ? { toolChoice: { type: "none" } }
+                : args.toolChoice !== undefined
+                    ? { toolChoice: args.toolChoice }
+                    : {}),
+            ...(args.responseFormat ? { responseFormat: args.responseFormat } : {}),
+            ...(args.providerOptions
+                ? { providerOptions: args.providerOptions }
+                : {}),
+            ...(args.maxOutputTokens
+                ? { maxOutputTokens: args.maxOutputTokens }
+                : {}),
+            ...(args.temperature !== undefined
+                ? { temperature: args.temperature }
+                : {}),
+            ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+        }));
+        const parts = asParts(res.content);
+        // Each step REPLACES the text rather than appending: the final step's
+        // answer is the turn's answer, matching what generateText reported.
+        text = parts
+            .filter((p) => p.type === "text" && typeof p.text === "string")
+            .map((p) => p.text)
+            .join("");
+        const fr = res.finishReason;
+        if (typeof fr === "string") {
+            finishReason = fr;
+        }
+        else if (typeof fr === "object" && fr !== null) {
+            const shaped = fr;
+            finishReason = shaped.unified ?? finishReason;
+            rawFinishReason = shaped.raw ?? rawFinishReason;
+        }
+        const usage = res.usage;
+        inputTokens += readTotal(usage?.inputTokens);
+        outputTokens += readTotal(usage?.outputTokens);
+        const inShaped = usage?.inputTokens;
+        cacheReadTokens += inShaped?.cacheRead ?? 0;
+        cacheWriteTokens += inShaped?.cacheWrite ?? 0;
+        const calls = parts.filter((p) => p.type === "tool-call");
+        if (calls.length === 0) {
+            // io.net's Llama endpoint ends a tool loop on `finish_reason:
+            // tool_calls` carrying neither a tool call nor any text: the model's
+            // JSON-shaped answer trips the vendor's tool-call parser, which drops it
+            // and reports `content: null` with no `tool_calls`. There is nothing to
+            // execute, so the loop would stop and hand the caller an empty turn even
+            // though the tool ran. Replaying the request once with
+            // `toolChoice: "none"` returns the answer.
+            //
+            // Ported from GenerationHandler.recoverEmptyToolCallsFinish, which runs
+            // this on the ai-package path. That path is unreachable for every
+            // provider driven by this loop — io.net among them, since it is a
+            // Tier-2 catalog provider on the OpenAI-compatible base — so without
+            // this the recovery would simply not happen for the provider it was
+            // written for.
+            const emptyToolCallsFinish = finishReason === "tool-calls" &&
+                text.trim() === "" &&
+                hasTools &&
+                !reasked &&
+                step + 1 < args.maxSteps;
+            if (emptyToolCallsFinish) {
+                reasked = true;
+                args.conversation.push({ role: "assistant", content: parts });
+                continue;
+            }
+            break;
+        }
+        // Tool turns go back in the message-builder shape each provider's own
+        // conversion already round-trips: an assistant message of tool-call parts,
+        // then one tool message of tool-result parts.
+        args.conversation.push({ role: "assistant", content: parts });
+        const resultParts = [];
+        for (const call of calls) {
+            const name = String(call.toolName ?? "");
+            const id = String(call.toolCallId ?? "");
+            const startTime = new Date();
+            const parsed = parseToolInput(call.input);
+            const input = parsed.input;
+            const tool = args.toolsRecord[name];
+            let output;
+            let failure;
+            const rejection = parsed.error ??
+                (typeof tool?.execute === "function"
+                    ? validateToolInput(tool, input)
+                    : undefined);
+            if (typeof tool?.execute !== "function") {
+                failure = `Tool not found: ${name}`;
+                output = { error: failure };
+            }
+            else if (rejection) {
+                // An error tool-result rather than a throw: the model gets to see what
+                // was wrong and correct it on the next step, which is what the SDK's
+                // own validation did.
+                failure = `Tool ${name}: ${rejection}`;
+                output = { error: failure };
+            }
+            else {
+                try {
+                    // The turn's abort signal and the per-tool cap have to reach the
+                    // tool, or a wedged tool parks the loop inside `await execute` and
+                    // outlives the deadline that withTurnTimeout composed. Reuses the
+                    // guard every other native loop already applies.
+                    const guarded = guardToolExecutor(name, tool.execute, {
+                        ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+                        ...(args.toolTimeoutMs !== undefined
+                            ? { toolTimeoutMs: args.toolTimeoutMs }
+                            : {}),
+                    });
+                    output = await guarded(input, {
+                        toolCallId: id,
+                        messages: [],
+                        ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+                    });
+                    toolsUsed.push(name);
+                }
+                catch (err) {
+                    failure = err instanceof Error ? err.message : String(err);
+                    output = { error: failure };
+                }
+            }
+            toolExecutionSummaries.push({
+                toolCallId: id,
+                toolName: name,
+                input,
+                ...(failure ? { error: failure } : { output }),
+                startTime,
+                endTime: new Date(),
+            });
+            resultParts.push({ type: "tool-result", toolCallId: id, output });
+        }
+        args.conversation.push({ role: "tool", content: resultParts });
+    }
+    return {
+        text,
+        finishReason,
+        ...(rawFinishReason ? { rawFinishReason } : {}),
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        toolsUsed,
+        steps,
+    };
+}

package/dist/files/fileTools.d.ts

@@ -18,7 +18,7 @@ import type { FileReferenceRegistry } from "./fileReferenceRegistry.js";
  * ```
  */
 export declare function createFileTools(registry: FileReferenceRegistry): {
-    list_attached_files: import("ai").Tool<Record<string, never>, {
+    list_attached_files: import("../index.js").Tool<Record<string, never>, {
         success: boolean;
         message: string;
         fileCount: number;
@@ -53,7 +53,7 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         files?: undefined;
         formatted?: undefined;
     }>;
-    read_file_section: import("ai").Tool<{
+    read_file_section: import("../index.js").Tool<{
         file_id: string;
         start_line: number;
         token_budget: number;
@@ -79,7 +79,7 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         guidance: string | undefined;
         error?: undefined;
     }>;
-    search_in_file: import("ai").Tool<{
+    search_in_file: import("../index.js").Tool<{
         file_id: string;
         pattern: string;
         max_matches: number;
@@ -107,7 +107,7 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         }[];
         error?: undefined;
     }>;
-    get_file_preview: import("ai").Tool<{
+    get_file_preview: import("../index.js").Tool<{
         file_id: string;
     }, {
         success: boolean;
@@ -140,7 +140,7 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         hasSummary: boolean;
         error?: undefined;
     }>;
-    extract_file_content: import("ai").Tool<{
+    extract_file_content: import("../index.js").Tool<{
         file_id: string;
         start_time?: number | undefined;
         end_time?: number | undefined;

package/dist/index.d.ts

@@ -82,6 +82,7 @@ export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, get
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+export { tool, jsonSchema, stepCountIs } from "./utils/tool.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";
 export { getMetricsAggregator, MetricsAggregator, resetMetricsAggregator, } from "./observability/metricsAggregator.js";

package/dist/index.js

@@ -165,6 +165,10 @@ runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+// Tool + schema helpers. Previously a consumer reached for `tool()` and
+// `jsonSchema()` from the ai package to build tools for generate({tools}).
+// That package is no longer a dependency, so the equivalents ship here.
+export { tool, jsonSchema, stepCountIs } from "./utils/tool.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";
 // Observability modules and types

package/dist/mcp/toolRegistry.js

@@ -167,6 +167,7 @@ export class MCPToolRegistry extends MCPRegistry {
             const toolId = isCustomTool ? tool.name : `${serverId}.${tool.name}`;
             const toolTimeoutMs = serverInfo.metadata?.toolTimeoutMs;
             const toolMaxRetries = serverInfo.metadata?.toolMaxRetries;
+            const toolTotalTimeoutMs = serverInfo.metadata?.toolTotalTimeoutMs;
             const toolInfo = {
                 name: tool.name,
                 description: tool.description,
@@ -180,6 +181,9 @@ export class MCPToolRegistry extends MCPRegistry {
                 permissions: [], // MCPServerInfo.tools doesn't have permissions
                 ...(toolTimeoutMs !== undefined && { timeoutMs: toolTimeoutMs }),
                 ...(toolMaxRetries !== undefined && { maxRetries: toolMaxRetries }),
+                ...(toolTotalTimeoutMs !== undefined && {
+                    totalTimeoutMs: toolTotalTimeoutMs,
+                }),
             };
             // Register only with fully-qualified toolId to avoid collisions
             this.tools.set(toolId, toolInfo);
@@ -197,6 +201,9 @@ export class MCPToolRegistry extends MCPRegistry {
                 }),
                 ...(toolTimeoutMs !== undefined && { timeoutMs: toolTimeoutMs }),
                 ...(toolMaxRetries !== undefined && { maxRetries: toolMaxRetries }),
+                ...(toolTotalTimeoutMs !== undefined && {
+                    totalTimeoutMs: toolTotalTimeoutMs,
+                }),
             });
             // Tool registered successfully
         }

package/dist/middleware/builtin/guardrails.d.ts

@@ -1,7 +1,2 @@
 import type { NeuroLinkMiddleware, GuardrailsMiddlewareConfig } from "../../types/index.js";
-/**
- * Create Guardrails AI middleware for content filtering and policy enforcement
- * @param config Configuration for the guardrails middleware
- * @returns NeuroLink middleware instance
- */
 export declare function createGuardrailsMiddleware(config?: GuardrailsMiddlewareConfig): NeuroLinkMiddleware;

package/dist/middleware/builtin/guardrails.js

@@ -1,11 +1,36 @@
 import { createBlockedResponse, createBlockedStream, applyContentFiltering, handlePrecallGuardrails, } from "../utils/guardrailsUtils.js";
 import { logger } from "../../utils/logger.js";
-import { generateText } from "../../utils/generation.js";
+import { generateOnceNative } from "../../utils/nativeSingleShot.js";
 /**
  * Create Guardrails AI middleware for content filtering and policy enforcement
  * @param config Configuration for the guardrails middleware
  * @returns NeuroLink middleware instance
  */
+/**
+ * Turn whatever a caller put in `filterModel` into a model handle.
+ *
+ * A handle is used as-is. A string is resolved through NeuroLink's own
+ * provider factory, accepting either "provider:model" or a bare model id.
+ * Imported lazily so the middleware module does not pull the provider factory
+ * into every bundle that merely registers guardrails.
+ */
+async function resolveFilterModel(filterModel) {
+    if (typeof filterModel !== "string") {
+        return filterModel;
+    }
+    const [maybeProvider, ...rest] = filterModel.split(":");
+    const hasProvider = rest.length > 0;
+    const { ProviderFactory } = await import("../../factories/providerFactory.js");
+    const provider = await ProviderFactory.createProvider(hasProvider ? maybeProvider : undefined, hasProvider ? rest.join(":") : filterModel);
+    // `getModel()` is BaseProvider's sanctioned public handle but is not on the
+    // narrower `AIProvider` type, so narrow at the boundary rather than assert
+    // through it (Critical Rule 14).
+    const handle = provider;
+    if (typeof handle.getModel !== "function") {
+        throw new Error(`guardrails: provider for "${filterModel}" exposes no model handle`);
+    }
+    return handle.getModel();
+}
 export function createGuardrailsMiddleware(config = {}) {
     const metadata = {
         id: "guardrails",
@@ -44,10 +69,13 @@ export function createGuardrailsMiddleware(config = {}) {
                 logger.debug(`[GuardrailsMiddleware] Invoking model-based filter.`);
                 try {
                     const filterPrompt = `Is the following text safe? Respond with only "safe" or "unsafe".\n\nText: "${result.text}"`;
-                    const { text: filterResponse } = await generateText({
-                        model: config.modelFilter.filterModel,
-                        prompt: filterPrompt,
-                    });
+                    // `ModelFilterConfig.filterModel` is typed `LanguageModel`, which
+                    // admits a bare model id, and the documented examples used one.
+                    // `generateOnceNative` needs a handle exposing doGenerate, so a
+                    // string threw, the catch below logged it, and the turn returned
+                    // unfiltered — a security control that silently did nothing.
+                    const filterModel = await resolveFilterModel(config.modelFilter.filterModel);
+                    const { text: filterResponse } = await generateOnceNative(filterModel, { prompt: filterPrompt });
                     if (filterResponse.toLowerCase().trim() === "unsafe") {
                         logger.warn(`[GuardrailsMiddleware] Model-based filter flagged content as unsafe.`);
                         result = { ...result, text: "<REDACTED BY AI GUARDRAIL>" };

package/dist/middleware/factory.js

@@ -4,7 +4,7 @@ import { createGuardrailsMiddleware } from "./builtin/guardrails.js";
 import { createAutoEvaluationMiddleware } from "./builtin/autoEvaluation.js";
 import { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 import { logger } from "../utils/logger.js";
-import { wrapLanguageModel } from "../utils/generation.js";
+import { wrapLanguageModel } from "./wrapLanguageModel.js";
 /**
  * Middleware factory for creating and applying middleware chains.
  * Each factory instance manages its own registry and configuration.

package/dist/middleware/wrapLanguageModel.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Local `wrapLanguageModel`.
+ *
+ * Upstream is a reduce over the middleware array that returns a model whose
+ * `doGenerate` / `doStream` route through `transformParams` and the optional
+ * `wrapGenerate` / `wrapStream` hooks. Reproduced here so the middleware
+ * factory no longer needs the ai package.
+ *
+ * Worth recording: `wrapStream` does not currently run in this codebase. Every
+ * streaming path is native and bypasses the wrapped model entirely, so only
+ * `wrapGenerate` is reachable. That is a pre-existing gap, not one this
+ * introduced.
+ */
+import type { LanguageModelV3, LanguageModelV3Middleware } from "../types/index.js";
+export declare const wrapLanguageModel: ({ model, middleware, }: {
+    model: LanguageModelV3;
+    middleware: LanguageModelV3Middleware | LanguageModelV3Middleware[];
+}) => LanguageModelV3;

package/dist/middleware/wrapLanguageModel.js

@@ -0,0 +1,53 @@
+/**
+ * Local `wrapLanguageModel`.
+ *
+ * Upstream is a reduce over the middleware array that returns a model whose
+ * `doGenerate` / `doStream` route through `transformParams` and the optional
+ * `wrapGenerate` / `wrapStream` hooks. Reproduced here so the middleware
+ * factory no longer needs the ai package.
+ *
+ * Worth recording: `wrapStream` does not currently run in this codebase. Every
+ * streaming path is native and bypasses the wrapped model entirely, so only
+ * `wrapGenerate` is reachable. That is a pre-existing gap, not one this
+ * introduced.
+ */
+const doWrap = (model, middleware) => {
+    const transform = async (params, type) => middleware.transformParams
+        ? await middleware.transformParams({ type, params, model })
+        : params;
+    return {
+        specificationVersion: "v3",
+        provider: middleware.overrideProvider?.({ model }) ?? model.provider,
+        modelId: middleware.overrideModelId?.({ model }) ?? model.modelId,
+        supportedUrls: middleware.overrideSupportedUrls?.({ model }) ?? model.supportedUrls,
+        async doGenerate(params) {
+            const transformed = await transform(params, "generate");
+            const doGenerate = () => model.doGenerate(transformed);
+            const doStream = () => model.doStream(transformed);
+            return middleware.wrapGenerate
+                ? await middleware.wrapGenerate({
+                    doGenerate,
+                    doStream,
+                    params: transformed,
+                    model,
+                })
+                : await doGenerate();
+        },
+        async doStream(params) {
+            const transformed = await transform(params, "stream");
+            const doGenerate = () => model.doGenerate(transformed);
+            const doStream = () => model.doStream(transformed);
+            return middleware.wrapStream
+                ? await middleware.wrapStream({
+                    doGenerate,
+                    doStream,
+                    params: transformed,
+                    model,
+                })
+                : await doStream();
+        },
+    };
+};
+export const wrapLanguageModel = ({ model, middleware, }) => (Array.isArray(middleware) ? [...middleware] : [middleware])
+    .reverse()
+    .reduce((wrapped, m) => doWrap(wrapped, m), model);

package/dist/neurolink.d.ts

@@ -1587,8 +1587,15 @@ export declare class NeuroLink {
      * @returns Tool execution result
      */
     executeTool<T = unknown>(toolName: string, params?: unknown, options?: {
+        /** Bound on ONE attempt. */
         timeout?: number;
         maxRetries?: number;
+        /**
+         * Bound on the WHOLE execution — every attempt plus the delays between
+         * them. Defaults to `timeout * (maxRetries + 1)`, which is what the
+         * retry loop already spent, so omitting it changes nothing.
+         */
+        totalTimeoutMs?: number;
         retryDelayMs?: number;
         /** Disable tool result caching for this call */
         disableToolCache?: boolean;

package/dist/neurolink.js

@@ -9566,7 +9566,7 @@ Current user's request: ${currentInput}`;
                 };
             }
             // SMART DEFAULTS: Use utility to eliminate boilerplate creation
-            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool, options?.timeout, options?.maxRetries);
+            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool, options?.timeout, options?.maxRetries, options?.totalTimeoutMs);
             // Register with toolRegistry using MCPServerInfo directly
             this.toolRegistry.registerServer(mcpServerInfo);
             // Re-registration replaces options wholesale: omitting `cacheable`
@@ -10010,14 +10010,32 @@ Current user's request: ${currentInput}`;
             executionId: executionContext.executionId,
         }));
         const toolInfo = this.toolRegistry.getToolInfo(toolName);
+        const attemptTimeout = options?.timeout ??
+            toolInfo?.tool?.timeoutMs ??
+            TOOL_TIMEOUTS.EXECUTION_BATCH_MS;
+        const maxRetries = options?.maxRetries ??
+            toolInfo?.tool?.maxRetries ??
+            RETRY_ATTEMPTS.DEFAULT;
+        const retryDelayMs = options?.retryDelayMs || RETRY_DELAYS.BASE_MS;
         const finalOptions = {
-            timeout: options?.timeout ??
-                toolInfo?.tool?.timeoutMs ??
-                TOOL_TIMEOUTS.EXECUTION_BATCH_MS,
-            maxRetries: options?.maxRetries ??
-                toolInfo?.tool?.maxRetries ??
-                RETRY_ATTEMPTS.DEFAULT,
-            retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
+            timeout: attemptTimeout,
+            maxRetries,
+            // Ceiling on the whole execution, not one attempt. The default is what
+            // the retry loop already spent, and that is BOTH terms: every attempt at
+            // full length PLUS the fixed wait between them. Omitting the delays
+            // makes the default ceiling shorter than the envelope it is meant to
+            // reproduce, so `attemptTimeout = min(timeout, remaining)` clamps a
+            // later attempt below its configured timeout — the opposite of the
+            // "unchanged unless you ask for less" contract this default exists to
+            // keep. Before any of this the total was unbounded and merely implied:
+            // a tool that reliably hung burned every attempt at full length, and
+            // the surfaced error reported the per-attempt bound beside the
+            // whole-execution elapsed time, which reads as a timeout that was never
+            // enforced.
+            totalTimeout: options?.totalTimeoutMs ??
+                toolInfo?.tool?.totalTimeoutMs ??
+                attemptTimeout * (maxRetries + 1) + retryDelayMs * maxRetries,
+            retryDelayMs,
             authContext: options?.authContext,
             disableToolCache: options?.disableToolCache,
         };
@@ -10062,11 +10080,43 @@ Current user's request: ${currentInput}`;
                 options: prepared.finalOptions,
                 circuitBreakerState: prepared.circuitBreaker.getState(),
             });
+            const maxAttempts = prepared.finalOptions.maxRetries + 1;
+            const totalTimeout = prepared.finalOptions.totalTimeout;
+            const budgetStart = Date.now();
+            const deadline = budgetStart + totalTimeout;
+            let attemptNumber = 0;
             const result = await prepared.circuitBreaker.execute(async () => {
-                return withRetry(async () => withTimeout(this.executeToolInternal(toolName, params, prepared.finalOptions, executionContext.hitlState), prepared.finalOptions.timeout, ErrorFactory.toolTimeout(toolName, prepared.finalOptions.timeout)), {
-                    maxAttempts: prepared.finalOptions.maxRetries + 1,
+                return withRetry(async () => {
+                    attemptNumber++;
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0) {
+                        throw ErrorFactory.toolTimeout(toolName, totalTimeout, undefined, {
+                            attempt: attemptNumber,
+                            maxAttempts,
+                            attemptTimeoutMs: prepared.finalOptions.timeout,
+                            totalTimeoutMs: totalTimeout,
+                            elapsedMs: Date.now() - budgetStart,
+                            exhausted: true,
+                        });
+                    }
+                    // Clamping to what is left is what makes the ceiling hard. Gating
+                    // retries alone would not: the last attempt could start just under
+                    // the deadline and still run a full attempt timeout past it.
+                    const attemptTimeout = Math.min(prepared.finalOptions.timeout, remaining);
+                    return withTimeout(this.executeToolInternal(toolName, params, prepared.finalOptions, executionContext.hitlState), attemptTimeout, ErrorFactory.toolTimeout(toolName, attemptTimeout, undefined, {
+                        attempt: attemptNumber,
+                        maxAttempts,
+                        attemptTimeoutMs: prepared.finalOptions.timeout,
+                        totalTimeoutMs: totalTimeout,
+                        elapsedMs: Date.now() - budgetStart,
+                    }));
+                }, {
+                    maxAttempts,
                     delayMs: prepared.finalOptions.retryDelayMs,
-                    isRetriable: isRetriableError,
+                    // Stop when there is not enough budget left for the retry delay
+                    // plus any real work after it.
+                    isRetriable: (error) => Date.now() + prepared.finalOptions.retryDelayMs < deadline &&
+                        isRetriableError(error),
                     onRetry: (attempt, error) => {
                         toolRetryCount = attempt;
                         mcpLogger.warn(`[${executionContext.functionTag}] Retrying tool execution (attempt ${attempt})`, {