@juspay/neurolink 12.16.0 → 12.17.0

package/dist/context/nativeGenerateGuard.d.ts

@@ -0,0 +1,6 @@
+import type { NativeGenerateGuardConfig } from "../types/index.js";
+/** V3-shape adapter for the reclaim policy shared with streaming guards. */
+export declare function createNativeGenerateGuard(config: NativeGenerateGuardConfig): {
+    observeUsage(usage: unknown): void;
+    guardConversation(conversation: Array<Record<string, unknown>>): Array<Record<string, unknown>> | undefined;
+};

package/dist/context/nativeGenerateGuard.js

@@ -0,0 +1,192 @@
+import { estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
+import { logger } from "../utils/logger.js";
+import { planLoopGuardReclaim } from "./loopGuardCore.js";
+import { DEFAULT_CONTEXT_GUARD_RATIO } from "../core/constants.js";
+import { generateToolOutputPreview } from "./toolOutputLimits.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const partsOf = (value) => Array.isArray(value) ? value.filter(isRecord) : [];
+const textOf = (value) => {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "x".repeat(200_000);
+    }
+};
+const previewMessage = (message) => ({
+    ...message,
+    // Do not stringify the whole message: call IDs, result types and metadata
+    // must survive the wire conversion. Only the result payload is shortened.
+    content: partsOf(message.content).map((part) => {
+        if (part.type !== "tool-result") {
+            return part;
+        }
+        const output = part.output;
+        const wrapped = isRecord(output) &&
+            ["text", "json", "error-text", "error-json"].includes(String(output.type)) &&
+            "value" in output;
+        const { preview, truncated } = generateToolOutputPreview(textOf(wrapped ? output.value : output), { maxBytes: 2048, maxLines: 60 });
+        if (!truncated) {
+            return part;
+        }
+        return {
+            ...part,
+            output: wrapped
+                ? {
+                    ...output,
+                    type: String(output.type).startsWith("error")
+                        ? "error-text"
+                        : "text",
+                    value: preview,
+                }
+                : preview,
+        };
+    }),
+});
+/** V3-shape adapter for the reclaim policy shared with streaming guards. */
+export function createNativeGenerateGuard(config) {
+    let previousSentEstimate;
+    let observedPromptTokens;
+    const cost = (message) => estimateTokens(textOf(message), config.provider) + TOKENS_PER_MESSAGE;
+    return {
+        observeUsage(usage) {
+            const input = isRecord(usage) ? usage.inputTokens : undefined;
+            const total = isRecord(input) ? input.total : input;
+            observedPromptTokens =
+                typeof total === "number" && Number.isFinite(total) && total > 0
+                    ? total
+                    : undefined;
+        },
+        guardConversation(conversation) {
+            // Policy entry zero is protected. Fold the entire initial task prefix
+            // into it so leading system messages cannot displace task protection.
+            const taskIndex = conversation.findIndex((message) => message.role === "user");
+            const prefixLength = Math.max(1, taskIndex + 1);
+            const tail = conversation.slice(prefixLength);
+            const previews = tail.map(previewMessage);
+            const entries = [
+                {
+                    kind: "other",
+                    tokens: conversation
+                        .slice(0, prefixLength)
+                        .reduce((sum, message) => sum + cost(message), 0),
+                },
+                ...tail.map((message, index) => {
+                    const parts = partsOf(message.content);
+                    if (message.role === "assistant" &&
+                        parts.some((part) => part.type === "tool-call")) {
+                        return { kind: "toolCall", tokens: cost(message) };
+                    }
+                    if (message.role === "tool" &&
+                        parts.some((part) => part.type === "tool-result")) {
+                        return {
+                            kind: "toolResult",
+                            tokens: cost(message),
+                            previewTokens: cost(previews[index]),
+                        };
+                    }
+                    return { kind: "other", tokens: cost(message) };
+                }),
+            ];
+            const overhead = config.getFixedOverheadTokens();
+            const calibration = observedPromptTokens && previousSentEstimate
+                ? Math.min(3, Math.max(1, observedPromptTokens / previousSentEstimate))
+                : 1;
+            const plan = planLoopGuardReclaim(entries, {
+                availableInputTokens: config.availableInputTokens,
+                fixedOverheadTokens: overhead,
+                calibration,
+            });
+            // The policy fires at a RATIO of the window, not at the window itself, so
+            // every number below is measured against that same threshold. Comparing
+            // against the raw budget leaves a ~15% band in which the guard has
+            // already crossed its reclaim point while the log still reads "under
+            // budget" with positive headroom — defeating the purpose of making the
+            // threshold measurable, since a probe sizing a payload from that headroom
+            // would aim past the point it meant to cross.
+            const reclaimThresholdTokens = Math.floor((config.availableInputTokens * DEFAULT_CONTEXT_GUARD_RATIO) /
+                (calibration > 0 ? calibration : 1));
+            const estimatedBeforeTokens = overhead + entries.reduce((sum, entry) => sum + entry.tokens, 0);
+            if (!plan.fire) {
+                previousSentEstimate = estimatedBeforeTokens;
+                // Staying under budget is the common case and must not be noisy, but
+                // silence here is unfalsifiable: no line at all reads the same whether
+                // the conversation fit, the guard was never installed, or this hook was
+                // never called. Two live attempts to demonstrate the reclaim against a
+                // real vendor produced nothing and could not distinguish those, because
+                // the budget is not observable from outside the process. Emitting the
+                // budget and the headroom at debug makes the threshold measurable, so a
+                // probe can size a payload to cross it instead of guessing.
+                // Two very different situations reach this branch and must not share a
+                // message. Fitting is routine and belongs at debug. Being over budget
+                // with nothing reclaimable is neither: the planner only touches entries
+                // strictly between the task and the newest
+                // DEFAULT_LOOP_GUARD_PROTECTED_TAIL, so a conversation whose oversize
+                // content sits inside that protected tail — one large tool result, the
+                // common case — yields an empty plan, and the request is sent over the
+                // window anyway to be rejected or silently truncated by the vendor.
+                // Observed live against deepseek: 186,847 estimated against a 62,500
+                // budget, empty plan, no signal of any kind before this warning.
+                if (estimatedBeforeTokens > reclaimThresholdTokens) {
+                    logger.warn("[NativeGenerateGuard] Over threshold, nothing reclaimable", {
+                        provider: config.provider,
+                        availableInputTokens: config.availableInputTokens,
+                        reclaimThresholdTokens,
+                        estimatedPromptTokens: estimatedBeforeTokens,
+                        overThresholdByTokens: estimatedBeforeTokens - reclaimThresholdTokens,
+                        calibration,
+                    });
+                }
+                else {
+                    logger.debug("[NativeGenerateGuard] Under threshold", {
+                        provider: config.provider,
+                        availableInputTokens: config.availableInputTokens,
+                        reclaimThresholdTokens,
+                        estimatedPromptTokens: estimatedBeforeTokens,
+                        headroomToThresholdTokens: reclaimThresholdTokens - estimatedBeforeTokens,
+                        calibration,
+                    });
+                }
+                return undefined;
+            }
+            const drop = new Set(plan.drop);
+            const truncate = new Set(plan.truncate);
+            const result = [...conversation.slice(0, prefixLength)];
+            let noted = false;
+            tail.forEach((message, index) => {
+                const entry = index + 1;
+                if (drop.has(entry)) {
+                    if (!noted) {
+                        result.push({
+                            role: "user",
+                            content: "[Earlier tool exchanges were removed to fit the context window.]",
+                        });
+                    }
+                    noted = true;
+                }
+                else {
+                    result.push(truncate.has(entry) ? previews[index] : message);
+                }
+            });
+            previousSentEstimate =
+                overhead + result.reduce((sum, message) => sum + cost(message), 0);
+            logger.info("[NativeGenerateGuard] Reclaimed context", {
+                provider: config.provider,
+                // The budget and both estimates travel with the event so a reader can
+                // see WHY it fired and by how much it overshot, rather than only that
+                // it did.
+                availableInputTokens: config.availableInputTokens,
+                reclaimThresholdTokens,
+                estimatedBeforeTokens,
+                estimatedAfterTokens: previousSentEstimate,
+                truncated: plan.truncate.length,
+                dropped: plan.drop.length,
+                calibration,
+            });
+            return result;
+        },
+    };
+}

package/dist/context/toolOutputLimits.js

@@ -29,6 +29,27 @@ export function exceedsToolOutputPreviewBudget(output, options) {
     return (Buffer.byteLength(output, "utf-8") > maxBytes ||
         output.split("\n").length > maxLines);
 }
+/**
+ * First `limit` bytes of `value`, cut on a code-point boundary.
+ *
+ * `Buffer.subarray().toString()` mid-sequence emits U+FFFD, which is itself
+ * three bytes and can push the result back over the very budget the cut was
+ * made to satisfy — so back off to the start of the split character instead.
+ */
+function takeBytes(value, limit) {
+    if (limit <= 0) {
+        return "";
+    }
+    const buf = Buffer.from(value, "utf-8");
+    if (buf.length <= limit) {
+        return value;
+    }
+    let end = limit;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80) {
+        end--;
+    }
+    return buf.subarray(0, end).toString("utf-8");
+}
 /**
  * Generate a head/tail preview of a tool output string.
  * If the output is within limits, returns it unchanged with truncated: false.
@@ -81,11 +102,61 @@ export function generateToolOutputPreview(output, options) {
         const tailBuf = Buffer.from(tail, "utf-8");
         tail = tailBuf.subarray(tailBuf.length - tailMaxBytes).toString("utf-8");
     }
-    const omittedBytes = Math.max(0, originalSize -
-        Buffer.byteLength(head, "utf-8") -
-        Buffer.byteLength(tail, "utf-8"));
-    const notice = `\n\n[... ${omittedBytes} bytes omitted. ` +
-        `Use ${RETRIEVE_CONTEXT_TOOL_NAME} tool to access full output ...]\n\n`;
+    // Default notice names retrieve_context; callers whose instance never
+    // registers that tool (see RETRIEVE_CONTEXT_TOOL_NAME usages in
+    // ToolsManager) pass their own `notice` so the model isn't pointed at a
+    // tool that doesn't exist.
+    const renderNotice = (omitted) => options?.notice === undefined
+        ? `\n\n[... ${omitted} bytes omitted. ` +
+            `Use ${RETRIEVE_CONTEXT_TOOL_NAME} tool to access full output ...]\n\n`
+        : typeof options.notice === "function"
+            ? options.notice(omitted)
+            : options.notice;
+    const omittedFor = (h, t) => Math.max(0, originalSize -
+        Buffer.byteLength(h, "utf-8") -
+        Buffer.byteLength(t, "utf-8"));
+    // `headMaxBytes + tailMaxBytes` is exactly `maxBytes`, leaving no room for
+    // the notice — so appending it unmeasured pushed every truncated preview
+    // over the caller's budget (82 bytes over, for the default notice). Give the
+    // notice its space back out of the tail, then the head. Two passes, because
+    // shrinking them raises `omittedBytes` and can lengthen the notice by a
+    // digit; the second pass settles that.
+    let notice = renderNotice(omittedFor(head, tail));
+    for (let pass = 0; pass < 2; pass++) {
+        const excess = Buffer.byteLength(head, "utf-8") +
+            Buffer.byteLength(notice, "utf-8") +
+            Buffer.byteLength(tail, "utf-8") -
+            maxBytes;
+        if (excess <= 0) {
+            break;
+        }
+        const tailBuf = Buffer.from(tail, "utf-8");
+        const takeFromTail = Math.min(excess, tailBuf.length);
+        tail = tailBuf.subarray(takeFromTail).toString("utf-8");
+        const stillOver = excess - takeFromTail;
+        if (stillOver > 0) {
+            const headBuf = Buffer.from(head, "utf-8");
+            head = headBuf
+                .subarray(0, Math.max(0, headBuf.length - stillOver))
+                .toString("utf-8");
+        }
+        notice = renderNotice(omittedFor(head, tail));
+    }
+    // A notice at least as long as the whole budget cannot be paid for out of
+    // `head` and `tail`: the loop above empties both and the notice alone is
+    // still over `maxBytes`. `maxBytes` is a hard cap the caller sizes its
+    // context window against, so bound the notice itself rather than handing
+    // back more than was asked for.
+    if (Buffer.byteLength(head, "utf-8") +
+        Buffer.byteLength(notice, "utf-8") +
+        Buffer.byteLength(tail, "utf-8") >
+        maxBytes) {
+        return {
+            preview: takeBytes(notice, maxBytes),
+            truncated: true,
+            originalSize,
+        };
+    }
     return {
         preview: head + notice + tail,
         truncated: true,

package/dist/core/modules/ToolsManager.d.ts

@@ -18,9 +18,6 @@ export declare function buildMCPSchemaValidator(toolName: string, schema: Record
     success: false;
     error: Error;
 }) | undefined>;
-/**
- * ToolsManager class - Handles all tool management operations
- */
 export declare class ToolsManager {
     private readonly providerName;
     private readonly directTools;
@@ -42,6 +39,51 @@ export declare class ToolsManager {
      * every tool uncancellable (deadline overshoot / ghost executions).
      */
     private wrapExecuteWithTruncation;
+    /**
+     * Byte budget for BZ-666 truncation. Reads the instance-level
+     * `tools.outputTruncationMaxBytes` config (see `ToolConfig` /
+     * `NeuroLink.getToolsConfig()`) so hosts can raise or lower the ceiling
+     * without a new env var or constructor param; falls back to the original
+     * hard-coded 51,200 bytes (== DEFAULT_MAX_PREVIEW_BYTES) so existing
+     * consumers see no behavior change.
+     */
+    private resolveTruncationMaxBytes;
+    /**
+     * The default omission notice names `retrieve_context` as the on-demand
+     * read-back tool. That is only true when this NeuroLink instance actually
+     * registered it (Redis or an artifact store must exist — see
+     * `retrieveContextRegistered` in neurolink.ts). Otherwise hand
+     * `generateToolOutputPreview` a notice that doesn't mention it.
+     */
+    private resolveTruncationNotice;
+    /**
+     * Truncate an MCP `CallToolResult`-shaped envelope (`{content:[...],
+     * isError?}`) — at the top level, or nested under `data` the way
+     * NeuroLink's own `executeExternalMCPTool` / `{success, data}` wrapper
+     * shapes it — WITHOUT collapsing it to the generic `_truncated` sentinel,
+     * while still honouring `maxBytes` for the envelope AS A WHOLE.
+     *
+     * Only TEXT content items are rewritten (byte-accurate head/tail preview,
+     * same mechanism as a plain string result). `isError` and any non-text
+     * items (images, resources, embedded resources, …) pass through
+     * untouched, and every other top-level field on the result is preserved.
+     *
+     * The budget is enforced on the serialized envelope, not per item: the
+     * bytes the envelope occupies with every text item emptied (structure,
+     * non-text items, other fields) come off the top, and what remains is
+     * water-filled across the text items — items that already fit keep their
+     * text and donate the rest of their share to the larger ones. JSON
+     * escaping and the per-item notice add bytes the raw allocation cannot
+     * see, so the result is re-measured and the text budget tightened until
+     * the whole envelope fits.
+     *
+     * Returns `undefined` when `result` doesn't have this shape at all, AND
+     * when the shape cannot be kept within `maxBytes` — no text items, the
+     * non-text payload alone exceeds the budget, or tightening did not
+     * converge — so the caller's generic sentinel path bounds it instead.
+     * Preserving the shape never buys the right to exceed the ceiling.
+     */
+    private truncateMcpContentEnvelope;
     /**
      * BZ-666: Apply generateToolOutputPreview to tool results to prevent
      * context overflow when large results flow into the AI SDK accumulator.

package/dist/core/modules/ToolsManager.js

@@ -5,7 +5,7 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { logger } from "../../utils/logger.js";
 import { getKeyCount } from "../../utils/transformationUtils.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
-import { generateToolOutputPreview } from "../../context/toolOutputLimits.js";
+import { generateToolOutputPreview, DEFAULT_MAX_PREVIEW_BYTES, RETRIEVE_CONTEXT_TOOL_NAME, } from "../../context/toolOutputLimits.js";
 import { tool as createAISDKTool, jsonSchema } from "../../utils/tool.js";
 /** Abort-shaped error so provider loops route it to their cancellation path. */
 function makeToolAbortError() {
@@ -133,6 +133,44 @@ function raceWithAbortSignal(promise, signal) {
 /**
  * ToolsManager class - Handles all tool management operations
  */
+/** Upper bound on re-measure-and-tighten rounds in truncateMcpContentEnvelope. */
+const MAX_ENVELOPE_TIGHTENING_PASSES = 6;
+function serializedByteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function isTextContentItem(item) {
+    return (item !== null &&
+        typeof item === "object" &&
+        item.type === "text" &&
+        typeof item.text === "string");
+}
+/**
+ * Split `total` bytes across items of the given sizes, water-filling:
+ * smallest first, each item takes the lesser of its own size and an equal
+ * share of what is left, so items that already fit keep everything and the
+ * remainder flows to the larger ones.
+ */
+function waterFillTextBudget(sizes, total) {
+    const allocations = new Array(sizes.length).fill(0);
+    const order = sizes
+        .map((_, index) => index)
+        .sort((a, b) => sizes[a] - sizes[b]);
+    let remaining = Math.max(0, total);
+    let left = order.length;
+    for (const index of order) {
+        const share = Math.floor(remaining / left);
+        const give = Math.min(sizes[index], share);
+        allocations[index] = give;
+        remaining -= give;
+        left--;
+    }
+    return allocations;
+}
 export class ToolsManager {
     providerName;
     directTools;
@@ -176,6 +214,139 @@ export class ToolsManager {
             return this.truncateToolResult(toolName, result);
         };
     }
+    /**
+     * Byte budget for BZ-666 truncation. Reads the instance-level
+     * `tools.outputTruncationMaxBytes` config (see `ToolConfig` /
+     * `NeuroLink.getToolsConfig()`) so hosts can raise or lower the ceiling
+     * without a new env var or constructor param; falls back to the original
+     * hard-coded 51,200 bytes (== DEFAULT_MAX_PREVIEW_BYTES) so existing
+     * consumers see no behavior change.
+     */
+    resolveTruncationMaxBytes() {
+        const configured = this.neurolink?.getToolsConfig?.()?.outputTruncationMaxBytes;
+        return typeof configured === "number" &&
+            Number.isFinite(configured) &&
+            configured > 0
+            ? configured
+            : DEFAULT_MAX_PREVIEW_BYTES;
+    }
+    /**
+     * The default omission notice names `retrieve_context` as the on-demand
+     * read-back tool. That is only true when this NeuroLink instance actually
+     * registered it (Redis or an artifact store must exist — see
+     * `retrieveContextRegistered` in neurolink.ts). Otherwise hand
+     * `generateToolOutputPreview` a notice that doesn't mention it.
+     */
+    resolveTruncationNotice() {
+        const hasRetrieveContext = this.neurolink?.getCustomTools?.()?.has(RETRIEVE_CONTEXT_TOOL_NAME) ??
+            false;
+        if (hasRetrieveContext) {
+            return undefined; // defer to generateToolOutputPreview's own default
+        }
+        return (omittedBytes) => `\n\n[... ${omittedBytes} bytes omitted ...]\n\n`;
+    }
+    /**
+     * Truncate an MCP `CallToolResult`-shaped envelope (`{content:[...],
+     * isError?}`) — at the top level, or nested under `data` the way
+     * NeuroLink's own `executeExternalMCPTool` / `{success, data}` wrapper
+     * shapes it — WITHOUT collapsing it to the generic `_truncated` sentinel,
+     * while still honouring `maxBytes` for the envelope AS A WHOLE.
+     *
+     * Only TEXT content items are rewritten (byte-accurate head/tail preview,
+     * same mechanism as a plain string result). `isError` and any non-text
+     * items (images, resources, embedded resources, …) pass through
+     * untouched, and every other top-level field on the result is preserved.
+     *
+     * The budget is enforced on the serialized envelope, not per item: the
+     * bytes the envelope occupies with every text item emptied (structure,
+     * non-text items, other fields) come off the top, and what remains is
+     * water-filled across the text items — items that already fit keep their
+     * text and donate the rest of their share to the larger ones. JSON
+     * escaping and the per-item notice add bytes the raw allocation cannot
+     * see, so the result is re-measured and the text budget tightened until
+     * the whole envelope fits.
+     *
+     * Returns `undefined` when `result` doesn't have this shape at all, AND
+     * when the shape cannot be kept within `maxBytes` — no text items, the
+     * non-text payload alone exceeds the budget, or tightening did not
+     * converge — so the caller's generic sentinel path bounds it instead.
+     * Preserving the shape never buys the right to exceed the ceiling.
+     */
+    truncateMcpContentEnvelope(toolName, obj, maxBytes) {
+        const atTopLevel = Array.isArray(obj.content);
+        const dataObj = !atTopLevel && obj.data && typeof obj.data === "object"
+            ? obj.data
+            : undefined;
+        const nestedUnderData = !atTopLevel && Array.isArray(dataObj?.content);
+        if (!atTopLevel && !nestedUnderData) {
+            return undefined;
+        }
+        const envelope = atTopLevel ? obj : dataObj;
+        const serializedSize = serializedByteLength(obj);
+        if (serializedSize === undefined) {
+            return obj; // unserializable — leave the envelope exactly as-is
+        }
+        if (serializedSize <= maxBytes) {
+            return obj;
+        }
+        const content = envelope.content;
+        const textIndexes = [];
+        content.forEach((item, index) => {
+            if (isTextContentItem(item)) {
+                textIndexes.push(index);
+            }
+        });
+        if (textIndexes.length === 0) {
+            return undefined; // nothing trimmable — let the sentinel bound it
+        }
+        const rebuild = (replacements) => {
+            const newContent = content.map((item, index) => {
+                const text = replacements.get(index);
+                return text === undefined
+                    ? item
+                    : { ...item, text };
+            });
+            const newEnvelope = { ...envelope, content: newContent };
+            return atTopLevel ? newEnvelope : { ...obj, data: newEnvelope };
+        };
+        // Bytes the envelope costs with every text item emptied. If that alone
+        // is over budget, no amount of text trimming honours the ceiling while
+        // keeping the shape.
+        const fixedBytes = serializedByteLength(rebuild(new Map(textIndexes.map((index) => [index, ""]))));
+        if (fixedBytes === undefined || fixedBytes >= maxBytes) {
+            return undefined;
+        }
+        const notice = this.resolveTruncationNotice();
+        const sizes = textIndexes.map((index) => Buffer.byteLength(content[index].text, "utf-8"));
+        let textBudget = maxBytes - fixedBytes;
+        for (let pass = 0; pass < MAX_ENVELOPE_TIGHTENING_PASSES; pass++) {
+            const allocations = waterFillTextBudget(sizes, textBudget);
+            const replacements = new Map();
+            textIndexes.forEach((index, k) => {
+                const item = content[index];
+                const { preview, truncated, originalSize } = generateToolOutputPreview(item.text, { maxBytes: allocations[k], notice });
+                if (truncated) {
+                    logger.debug(`[ToolsManager] Truncated '${toolName}' MCP content text item ${index}: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes (envelope budget ${maxBytes})`);
+                    replacements.set(index, preview);
+                }
+            });
+            const candidate = rebuild(replacements);
+            const candidateSize = serializedByteLength(candidate);
+            if (candidateSize !== undefined && candidateSize <= maxBytes) {
+                return candidate;
+            }
+            if (candidateSize === undefined || replacements.size === 0) {
+                break;
+            }
+            // Over by the escaping/notice overhead the allocation could not see:
+            // take that overage (plus a margin) back out of the text budget.
+            textBudget -= candidateSize - maxBytes + Math.ceil(maxBytes * 0.02) + 1;
+            if (textBudget <= 0) {
+                break;
+            }
+        }
+        return undefined; // could not fit while preserving the shape — sentinel
+    }
     /**
      * BZ-666: Apply generateToolOutputPreview to tool results to prevent
      * context overflow when large results flow into the AI SDK accumulator.
@@ -184,9 +355,10 @@ export class ToolsManager {
         if (result === null || result === undefined) {
             return result;
         }
+        const maxBytes = this.resolveTruncationMaxBytes();
         // Handle string results directly
         if (typeof result === "string") {
-            const { preview, truncated, originalSize } = generateToolOutputPreview(result);
+            const { preview, truncated, originalSize } = generateToolOutputPreview(result, { maxBytes, notice: this.resolveTruncationNotice() });
             if (truncated) {
                 logger.debug(`[ToolsManager] Truncated '${toolName}' string output: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
             }
@@ -196,9 +368,10 @@ export class ToolsManager {
         if (typeof result === "object") {
             const obj = result;
             let nextObj = null;
-            // Truncate "content" if present and oversized
+            // Truncate "content" if present and oversized (string form only —
+            // an ARRAY "content" is an MCP envelope, handled below)
             if (typeof obj.content === "string") {
-                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.content);
+                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.content, { maxBytes, notice: this.resolveTruncationNotice() });
                 if (truncated) {
                     logger.debug(`[ToolsManager] Truncated '${toolName}' content field: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
                     nextObj = { ...(nextObj ?? obj), content: preview };
@@ -206,7 +379,7 @@ export class ToolsManager {
             }
             // Truncate "data" if present and oversized — both fields can coexist
             if (typeof obj.data === "string") {
-                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.data);
+                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.data, { maxBytes, notice: this.resolveTruncationNotice() });
                 if (truncated) {
                     logger.debug(`[ToolsManager] Truncated '${toolName}' data field: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
                     nextObj = { ...(nextObj ?? obj), data: preview };
@@ -215,12 +388,24 @@ export class ToolsManager {
             if (nextObj) {
                 return nextObj;
             }
+            // MCP CallToolResult envelope — { content: [{type,text}, ...], isError? }
+            // — either at the top level or nested under `data` (NeuroLink's own
+            // executeExternalMCPTool / {success, data} wrapper shape). Preserve the
+            // envelope and truncate only the oversized text items instead of
+            // collapsing the whole thing to the generic sentinel below.
+            const envelopeResult = this.truncateMcpContentEnvelope(toolName, obj, maxBytes);
+            if (envelopeResult !== undefined) {
+                return envelopeResult;
+            }
             // For other objects, check if their JSON serialization is too large.
-            // Use UTF-8 byte length, not string length, to match the 50KB budget.
+            // Use UTF-8 byte length, not string length, to match the byte budget.
             try {
                 const jsonStr = JSON.stringify(result);
-                if (Buffer.byteLength(jsonStr, "utf-8") > 51_200) {
-                    const { preview, truncated, originalSize } = generateToolOutputPreview(jsonStr);
+                if (Buffer.byteLength(jsonStr, "utf-8") > maxBytes) {
+                    const { preview, truncated, originalSize } = generateToolOutputPreview(jsonStr, {
+                        maxBytes,
+                        notice: this.resolveTruncationNotice(),
+                    });
                     if (truncated) {
                         logger.debug(`[ToolsManager] Truncated '${toolName}' JSON output: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
                         // Preserve object shape so callers reading structured fields don't

package/dist/core/nativeGenerateLoop.js

@@ -118,6 +118,20 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
     const hasTools = Boolean(args.tools && args.tools.length > 0);
     for (let step = 0; step < args.maxSteps; step++) {
         steps = step + 1;
+        // Per-step context reclaim. The pre-dispatch budget check runs ONCE and
+        // never sees the assistant turns and tool results this loop appends, which
+        // is how a long agentic run overflows the model window mid-loop and loses
+        // every completed step to a provider 400. The streaming paths have guarded
+        // this for a while; generate() did not, so the identical turn reclaimed on
+        // stream() and overflowed on generate().
+        //
+        // The provider supplies the guard because only it knows its wire shape.
+        // Returning undefined leaves the conversation byte-identical, so a turn
+        // that fits never pays a prompt-cache invalidation.
+        const guarded = args.guardConversation?.(args.conversation);
+        if (guarded) {
+            args.conversation.splice(0, args.conversation.length, ...guarded);
+        }
         const runThisStep = () => args.runStep(() => args.doGenerate({
             prompt: args.conversation,
             ...(args.tools && args.tools.length > 0 ? { tools: args.tools } : {}),
@@ -169,6 +183,7 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
             throw stepError;
         }
         reaskPending = false;
+        args.observeUsage?.(res.usage);
         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.
@@ -177,11 +192,16 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
             .map((p) => p.text)
             .join("");
         // Reasoner models (DeepSeek `reasoning_content`, gateway `reasoning`,
-        // OpenAI o-series) emit reasoning as its own V3 content part. Join it on
-        // the same replace-per-step rule as the text so the caller can surface
-        // `result.reasoning`; without this the provider builds the part and the
-        // loop drops it.
-        reasoning = parts
+        // OpenAI o-series) emit reasoning as its own V3 content part.
+        //
+        // Unlike `text`, this ACCUMULATES across steps. Each step's answer
+        // supersedes the last, but each step's reasoning is its own thought:
+        // replacing meant a tool loop reported only whatever the final step
+        // happened to think, which is usually the shortest part and frequently
+        // empty once the model just answers from the tool result. Concatenating
+        // with nothing between them is what a stream() consumer accumulates from
+        // the per-step reasoning chunks, so both surfaces agree on the turn.
+        reasoning += parts
             .filter((p) => p.type === "reasoning" && typeof p.text === "string")
             .map((p) => p.text)
             .join("");