@juspay/neurolink 10.10.3 → 10.10.5

package/dist/lib/context/openaiCompatLoopGuard.js

@@ -0,0 +1,173 @@
+/**
+ * In-turn context guard for the OpenAI-compatible chat-completions loop.
+ *
+ * `openaiChatCompletionsBase` runs its own hand-written tool loop
+ * (`for step < maxSteps` → `streamOneStep` → `executeToolBatch`) and appends an
+ * assistant tool-call message plus one `role: "tool"` message per result on
+ * every step. Nothing bounded that growth: the loop had no context guard of any
+ * kind, so a long agentic run walked into a provider "context length exceeded"
+ * after dozens of tool calls and lost every completed step.
+ *
+ * This is the widest-reach gap in the codebase — the chat-completions base
+ * backs LiteLLM, DeepSeek, OpenRouter, NVIDIA NIM, LM Studio, llama.cpp and
+ * every `openai-compatible` provider.
+ *
+ * The reclaim POLICY lives in `loopGuardCore` and is shared with the other
+ * provider loops. This module owns only the shape mapping: OpenAI-compatible
+ * messages in, neutral entries out, plan applied back.
+ */
+import { estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
+import { exceedsToolOutputPreviewBudget, generateToolOutputPreview, } from "./toolOutputLimits.js";
+import { planLoopGuardReclaim } from "./loopGuardCore.js";
+import { logger } from "../utils/logger.js";
+/** Preview budget for an old tool output. Matches the AI-SDK guard. */
+const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
+const OLD_TOOL_OUTPUT_PREVIEW_LINES = 60;
+/** Marker left where dropped history used to be. */
+const ELISION_NOTE = "[Earlier tool exchanges were removed to fit the context window.]";
+/** Serialize message content to text for estimation. Never throws. */
+function contentToText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (content === null || content === undefined) {
+        return "";
+    }
+    try {
+        return JSON.stringify(content) ?? "";
+    }
+    catch {
+        // A payload past V8's string cap is enormous by definition; charge it a
+        // large fixed size rather than aborting the estimate and the turn.
+        return "x".repeat(200_000);
+    }
+}
+/** Cost of one message, including per-message framing. */
+function messageTokens(message, provider) {
+    let text = contentToText(message.content);
+    if (message.role === "assistant" && message.tool_calls) {
+        // Tool-call arguments are a first-class cost here: the model's arguments
+        // for a Write/Edit-style tool dwarf the message body.
+        text += contentToText(message.tool_calls);
+    }
+    return estimateTokens(text, provider) + TOKENS_PER_MESSAGE;
+}
+/** Preview cost of a `role: "tool"` message, or undefined when it cannot shrink. */
+function previewTokensFor(message, provider) {
+    if (message.role !== "tool") {
+        return undefined;
+    }
+    const text = contentToText(message.content);
+    const previewOptions = {
+        maxBytes: OLD_TOOL_OUTPUT_PREVIEW_BYTES,
+        maxLines: OLD_TOOL_OUTPUT_PREVIEW_LINES,
+    };
+    if (!exceedsToolOutputPreviewBudget(text, previewOptions)) {
+        return undefined;
+    }
+    const { preview } = generateToolOutputPreview(text, previewOptions);
+    return estimateTokens(preview, provider) + TOKENS_PER_MESSAGE;
+}
+/** Map the loop's history onto the neutral view the policy operates on. */
+function toEntries(conversation, provider) {
+    return conversation.map((message) => {
+        const tokens = messageTokens(message, provider);
+        if (message.role === "tool") {
+            const previewTokens = previewTokensFor(message, provider);
+            return {
+                kind: "toolResult",
+                tokens,
+                ...(previewTokens !== undefined ? { previewTokens } : {}),
+            };
+        }
+        if (message.role === "assistant" && message.tool_calls?.length) {
+            return { kind: "toolCall", tokens };
+        }
+        return { kind: "other", tokens };
+    });
+}
+/**
+ * Reclaim context budget from a chat-completions loop's conversation.
+ *
+ * Returns a NEW array when it acted, or `undefined` when the loop fits and the
+ * history must be left byte-identical — any rewrite invalidates the provider's
+ * cached prompt prefix, so "no change" has to mean no change.
+ *
+ * @param observedPromptTokens the provider's reported prompt token count for
+ * the previous step, used to calibrate the char-based estimate for free.
+ * @param previousSentEstimate this guard's own estimate for the request that
+ * produced `observedPromptTokens`. The two must describe the SAME request.
+ * @param onSentEstimate receives the estimate for the request about to be sent,
+ * so the caller can feed it back as the next step's `previousSentEstimate`.
+ */
+export function guardOpenAICompatConversation(args) {
+    const { conversation, availableInputTokens, fixedOverheadTokens, provider, observedPromptTokens, previousSentEstimate, onSentEstimate, } = args;
+    const entries = toEntries(conversation, provider);
+    const rawEstimate = fixedOverheadTokens + entries.reduce((sum, e) => sum + e.tokens, 0);
+    // Calibration compares a real prompt-token count against THIS guard's
+    // estimate for the very request that produced it. Dividing by the estimate
+    // for the CURRENT conversation would be a category error: the loop has since
+    // appended an assistant tool-call message plus its results, so the
+    // denominator is always larger than the numerator's request. The ratio then
+    // reads below 1 and the `Math.max(1, …)` floor pins calibration at 1 — the
+    // correction silently never applies, which is exactly when a dense-code run
+    // overflows the window.
+    let calibration = 1;
+    if (observedPromptTokens &&
+        observedPromptTokens > 0 &&
+        previousSentEstimate &&
+        previousSentEstimate > 0) {
+        // Clamped: real tokenizers run up to ~1.3x the char estimate on dense
+        // code, and an unbounded ratio would compact the loop into uselessness.
+        calibration = Math.min(3, Math.max(1, observedPromptTokens / previousSentEstimate));
+    }
+    const plan = planLoopGuardReclaim(entries, {
+        availableInputTokens,
+        fixedOverheadTokens,
+        calibration,
+    });
+    if (!plan.fire) {
+        onSentEstimate?.(rawEstimate);
+        return undefined;
+    }
+    const truncateSet = new Set(plan.truncate);
+    const dropSet = new Set(plan.drop);
+    const result = [];
+    for (let i = 0; i < conversation.length; i++) {
+        if (dropSet.has(i)) {
+            continue;
+        }
+        const message = conversation[i];
+        if (truncateSet.has(i) && message.role === "tool") {
+            const { preview } = generateToolOutputPreview(contentToText(message.content), {
+                maxBytes: OLD_TOOL_OUTPUT_PREVIEW_BYTES,
+                maxLines: OLD_TOOL_OUTPUT_PREVIEW_LINES,
+            });
+            result.push({ ...message, content: preview });
+            continue;
+        }
+        result.push(message);
+    }
+    if (dropSet.size > 0) {
+        // Place the note where the removed history was, i.e. before the first
+        // surviving tool message — never at the end, where a "history was removed"
+        // cue would land after the content it refers to.
+        let noteIndex = result.findIndex((m) => m.role === "tool" || (m.role === "assistant" && m.tool_calls));
+        if (noteIndex < 0) {
+            noteIndex = Math.min(1, result.length);
+        }
+        result.splice(noteIndex, 0, { role: "user", content: ELISION_NOTE });
+    }
+    logger.info("[OpenAICompatLoopGuard] Reclaimed agent-loop context", {
+        provider,
+        messagesBefore: conversation.length,
+        messagesAfter: result.length,
+        toolOutputsTruncated: plan.truncate.length,
+        messagesDropped: plan.drop.length,
+        projectedTokens: plan.projectedTokens,
+        calibration,
+    });
+    onSentEstimate?.(plan.projectedTokens);
+    return result;
+}
+//# sourceMappingURL=openaiCompatLoopGuard.js.map

package/dist/lib/context/stepBudgetGuard.js

@@ -46,6 +46,22 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
 const MAX_CALIBRATION_RATIO = 3;
 /** Messages at the end of the conversation the guard never modifies. */
 const PROTECTED_TAIL_MESSAGES = 4;
+/**
+ * Fraction of the context window the guard reclaims DOWN TO once it fires.
+ *
+ * The high-water mark (`thresholdRatio`) decides *when* to act; this low-water
+ * mark decides *how far*. Reclaiming only back to the threshold meant the very
+ * next step — which appends an assistant turn plus its tool results — crossed
+ * it again, so the guard mutated the message prefix on every single step of a
+ * long agentic run. Each of those mutations invalidates the Anthropic
+ * `cache_control` prefix from the edit point onward (see
+ * anthropicCacheBreakpoints), turning a ~0.1x cached read into full-price
+ * input every step.
+ *
+ * One deeper reclaim every N steps saves the same tokens and leaves the prefix
+ * stable in between, which is what makes the cache worth having.
+ */
+const CONTEXT_GUARD_LOW_WATER_RATIO = 0.6;
 /** Stage-1 preview budget for an old tool output (bytes). */
 const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
 /** Stage-1 preview budget for an old tool output (lines). */
@@ -295,14 +311,22 @@ export function createStepBudgetGuard(config) {
             lastRawEstimate = rawEstimate;
             return undefined;
         }
+        // Reclaim down to the LOW-WATER mark, not merely back under the threshold.
+        // See CONTEXT_GUARD_LOW_WATER_RATIO: stopping at the threshold guaranteed
+        // the next step crossed it again, mutating the cached prefix every step.
+        const lowWaterTokens = Math.floor((availableInput * CONTEXT_GUARD_LOW_WATER_RATIO) / calibration);
         // Stage 1: shrink old tool outputs to previews.
         const stage1 = truncateOldToolOutputs([...messages]);
         let compacted = stage1.messages;
         let newEstimate = overheadTokens + estimateStepMessagesTokens(compacted, provider);
-        // Stage 2: drop oldest complete tool exchanges if still over.
+        // Stage 2: drop oldest complete tool exchanges until under the low-water
+        // mark. Stage order is deliberately unchanged — truncating first preserves
+        // a preview of each output, and since BOTH stages edit the oldest messages
+        // the cache prefix is invalidated at roughly the same point either way.
+        // Frequency, not stage order, is what governs cache retention here.
         let droppedExchanges = 0;
-        if (newEstimate > effectiveThreshold) {
-            const stage2 = dropOldestToolExchanges(compacted, effectiveThreshold, overheadTokens, provider);
+        if (newEstimate > lowWaterTokens) {
+            const stage2 = dropOldestToolExchanges(compacted, lowWaterTokens, overheadTokens, provider);
             compacted = stage2.messages;
             droppedExchanges = stage2.droppedExchanges;
             newEstimate =
@@ -317,8 +341,13 @@ export function createStepBudgetGuard(config) {
             model,
             estimatedTokens: rawEstimate,
             thresholdTokens: effectiveThreshold,
+            lowWaterTokens,
             calibration,
             afterTokens: newEstimate,
+            // Headroom reclaimed below the firing threshold. Roughly how many further
+            // steps can run before the guard mutates the prefix again — a value near
+            // zero means the cache is being invalidated every step.
+            headroomTokens: effectiveThreshold - newEstimate,
             toolOutputsTruncated: stage1.truncated,
             exchangesDropped: droppedExchanges,
         });

package/dist/lib/context/toolOutputLimits.d.ts

@@ -14,6 +14,17 @@ export declare const DEFAULT_HEAD_RATIO = 0.25;
 export declare const RETRIEVE_CONTEXT_TOOL_NAME = "retrieve_context";
 /** Default tail ratio (75% of preview budget) */
 export declare const DEFAULT_TAIL_RATIO = 0.75;
+/**
+ * True when `generateToolOutputPreview` would actually shrink this output.
+ *
+ * Callers gate on this before paying for a preview. It exists so the gate and
+ * the generator can never disagree: the budget is expressed in BYTES, and
+ * testing it against `String.length` (UTF-16 code units) under-reports every
+ * multibyte payload — CJK or emoji tool output would be judged small enough to
+ * leave alone while the generator would have truncated it. Line count matters
+ * for the same reason: a short-but-tall output exceeds `maxLines` alone.
+ */
+export declare function exceedsToolOutputPreviewBudget(output: string, options?: ToolOutputPreviewOptions): boolean;
 /**
  * Generate a head/tail preview of a tool output string.
  * If the output is within limits, returns it unchanged with truncated: false.

package/dist/lib/context/toolOutputLimits.js

@@ -13,6 +13,22 @@ export const DEFAULT_HEAD_RATIO = 0.25;
 export const RETRIEVE_CONTEXT_TOOL_NAME = "retrieve_context";
 /** Default tail ratio (75% of preview budget) */
 export const DEFAULT_TAIL_RATIO = 0.75;
+/**
+ * True when `generateToolOutputPreview` would actually shrink this output.
+ *
+ * Callers gate on this before paying for a preview. It exists so the gate and
+ * the generator can never disagree: the budget is expressed in BYTES, and
+ * testing it against `String.length` (UTF-16 code units) under-reports every
+ * multibyte payload — CJK or emoji tool output would be judged small enough to
+ * leave alone while the generator would have truncated it. Line count matters
+ * for the same reason: a short-but-tall output exceeds `maxLines` alone.
+ */
+export function exceedsToolOutputPreviewBudget(output, options) {
+    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_PREVIEW_BYTES;
+    const maxLines = options?.maxLines ?? DEFAULT_MAX_PREVIEW_LINES;
+    return (Buffer.byteLength(output, "utf-8") > maxBytes ||
+        output.split("\n").length > maxLines);
+}
 /**
  * Generate a head/tail preview of a tool output string.
  * If the output is within limits, returns it unchanged with truncated: false.

package/dist/lib/providers/anthropic/client.js

@@ -14,6 +14,9 @@ import { createProxyFetch } from "../../proxy/proxyFetch.js";
 import { getCapturedLimitSnapshot, getCapturedResponseHeaders, logClaudeLimitSnapshot, runInLimitCaptureScope, setLimitSpanAttributes, withLimitCapture, wrapFetchWithLimitCapture, } from "./rateLimitCapture.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { logger } from "../../utils/logger.js";
+import { ANTHROPIC_ELISION_NOTE, planAnthropicLoopReclaim, previewAnthropicToolResultText, } from "../../context/anthropicLoopGuard.js";
+import { getAvailableInputTokens } from "../../constants/contextWindows.js";
+import { estimateTokens } from "../../utils/tokenEstimation.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
 import { ANTHROPIC_MAX_CACHE_BREAKPOINTS, applyAnthropicHistoryCacheBreakpoints, countAnthropicCacheMarkers, } from "../../utils/anthropicCacheBreakpoints.js";
 import { calculateCost } from "../../utils/pricing.js";
@@ -1509,8 +1512,30 @@ export class AnthropicProvider extends BaseProvider {
         // and stay fully incremental.
         let bufferedText = "";
         let finalResultText;
+        /** System prompt + tool definitions: they ride outside `messages`. */
+        const estimateAnthropicFixedOverhead = (system, tools) => {
+            const text = (value) => {
+                if (typeof value === "string") {
+                    return value;
+                }
+                try {
+                    return JSON.stringify(value) ?? "";
+                }
+                catch {
+                    return "";
+                }
+            };
+            return (estimateTokens(text(system), "anthropic") +
+                estimateTokens(text(tools), "anthropic"));
+        };
         const runLoop = async () => {
             const conversation = payload.messages.slice();
+            // The provider's REAL prompt-token count for the previous step,
+            // calibrating the guard's char-based estimate for free, paired with the
+            // guard's own estimate for that same request — a ratio between counts of
+            // two different payloads would be meaningless.
+            let lastObservedPromptTokens;
+            let lastSentEstimate;
             for (let step = 0; step < maxSteps; step++) {
                 // Mid-turn discovery sync: search_tools (tools.discovery) hydrates
                 // new tools into toolsRecord between steps; Claude only calls tools
@@ -1524,6 +1549,71 @@ export class AnthropicProvider extends BaseProvider {
                         logger.info(`[Anthropic] ${Object.keys(hydrated).length} tool(s) hydrated mid-turn via discovery: ${Object.keys(hydrated).join(", ")}`);
                     }
                 }
+                // In-turn context guard. This loop appends an assistant tool_use
+                // message plus a user tool_result message every step — growth the
+                // pre-dispatch budget check never sees. Without it a long agentic run
+                // overflows the window mid-loop and loses every completed step.
+                // Returns undefined while the request still fits, leaving the history
+                // byte-identical so the rolling cache prefix below stays valid.
+                const reclaim = planAnthropicLoopReclaim({
+                    conversation,
+                    availableInputTokens: getAvailableInputTokens("anthropic", modelId, options.maxTokens ?? undefined),
+                    fixedOverheadTokens: estimateAnthropicFixedOverhead(payload.system, anthropicTools),
+                    provider: "anthropic",
+                    observedPromptTokens: lastObservedPromptTokens,
+                    // Both halves of the calibration ratio must describe the same
+                    // request: the tokens the provider reported, and this guard's own
+                    // estimate for what was sent to earn them.
+                    previousSentEstimate: lastSentEstimate,
+                    onSentEstimate: (tokens) => {
+                        lastSentEstimate = tokens;
+                    },
+                });
+                if (reclaim) {
+                    // Applied HERE, in the loop's own concrete types: the guard decides,
+                    // the caller mutates. Dropping an assistant tool_use message together
+                    // with its user tool_result message is what keeps blocks paired.
+                    const dropSet = new Set(reclaim.drop);
+                    const truncateSet = new Set(reclaim.truncate);
+                    const rebuilt = [];
+                    for (let i = 0; i < conversation.length; i++) {
+                        if (dropSet.has(i)) {
+                            continue;
+                        }
+                        const message = conversation[i];
+                        if (truncateSet.has(i) && Array.isArray(message.content)) {
+                            rebuilt.push({
+                                ...message,
+                                content: message.content.map((block) => block.type === "tool_result"
+                                    ? {
+                                        ...block,
+                                        content: previewAnthropicToolResultText(typeof block.content === "string"
+                                            ? block.content
+                                            : (JSON.stringify(block.content) ?? "")),
+                                    }
+                                    : block),
+                            });
+                            continue;
+                        }
+                        rebuilt.push(message);
+                    }
+                    if (dropSet.size > 0) {
+                        // Anthropic requires user/assistant alternation around tool blocks;
+                        // the note is a user turn placed immediately before the first
+                        // surviving assistant tool_use turn, which preserves it.
+                        let noteIndex = rebuilt.findIndex((m) => Array.isArray(m.content) &&
+                            m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
+                        if (noteIndex < 0) {
+                            noteIndex = Math.min(1, rebuilt.length);
+                        }
+                        rebuilt.splice(noteIndex, 0, {
+                            role: "user",
+                            content: [{ type: "text", text: ANTHROPIC_ELISION_NOTE }],
+                        });
+                    }
+                    conversation.length = 0;
+                    conversation.push(...rebuilt);
+                }
                 // Prompt-cache parity with the native Vertex+Claude path — rolling
                 // history breakpoints, re-applied per step so the stable prefix
                 // stays byte-identical while the breakpoint follows the growing
@@ -1587,6 +1677,14 @@ export class AnthropicProvider extends BaseProvider {
                         totalCacheRead += event.message.usage.cache_read_input_tokens ?? 0;
                         totalCacheWrite +=
                             event.message.usage.cache_creation_input_tokens ?? 0;
+                        // Calibration signal for the in-turn guard: the FULL prompt size,
+                        // which on this path means uncached input plus both cache tiers.
+                        // Using input_tokens alone would read a cache-hit step as tiny and
+                        // let the guard drift far under the real cost.
+                        lastObservedPromptTokens =
+                            (event.message.usage.input_tokens ?? 0) +
+                                (event.message.usage.cache_read_input_tokens ?? 0) +
+                                (event.message.usage.cache_creation_input_tokens ?? 0);
                     }
                     else if (event.type === "content_block_start") {
                         blockTypes.set(event.index, event.content_block.type);

package/dist/lib/providers/openaiChatCompletionsBase.js

@@ -17,7 +17,8 @@
  * Nothing here imports from "ai" or "@ai-sdk/*". The base class is a
  * direct HTTP client + multi-step tool-execution loop driven by SSE.
  */
-import { getRuntimeContextWindow, getRuntimeOutputCeiling, registerRuntimeContextWindow, } from "../constants/contextWindows.js";
+import { getAvailableInputTokens, getRuntimeContextWindow, getRuntimeOutputCeiling, registerRuntimeContextWindow, } from "../constants/contextWindows.js";
+import { guardOpenAICompatConversation } from "../context/openaiCompatLoopGuard.js";
 import { isContextOverflowError, parseProviderOverflowDetails, } from "../context/errorDetection.js";
 import { ContextBudgetExceededError } from "../context/errors.js";
 import { BaseProvider } from "../core/baseProvider.js";
@@ -770,6 +771,12 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             // May grow mid-turn: hydrated tools with wire-unsafe names need
             // reverse-mapping even when the initial name set required none.
             let effectiveToolNameFromWire = toolNameFromWire;
+            // The provider's REAL prompt-token count for the previous step, used to
+            // calibrate the guard's char-based estimate for free, paired with the
+            // guard's own estimate for that same request — a ratio between counts of
+            // two different payloads would be meaningless.
+            let lastObservedPromptTokens;
+            let lastSentEstimate;
             for (let step = 0; step < maxSteps; step++) {
                 // Mid-turn discovery sync: search_tools (tools.discovery) hydrates
                 // new tools into toolsRecord between steps. Dispatch already re-reads
@@ -795,6 +802,35 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                         logger.info(`${this.providerName}: ${Object.keys(hydrated).length} tool(s) hydrated mid-turn via discovery: ${Object.keys(hydrated).join(", ")}`);
                     }
                 }
+                // In-turn context guard. This loop appends an assistant tool-call
+                // message plus one tool message per result on every step — growth the
+                // pre-dispatch budget check never sees. Without this, a long agentic
+                // run walks into a provider "context length exceeded" and loses every
+                // completed step. Shares its reclaim policy with the other provider
+                // loops via loopGuardCore; returns undefined (leaving `conversation`
+                // byte-identical) whenever the request still fits, so a loop that fits
+                // never pays a prompt-cache invalidation.
+                const guarded = guardOpenAICompatConversation({
+                    conversation,
+                    availableInputTokens: getAvailableInputTokens(this.providerName, modelId, options.maxTokens ?? undefined),
+                    // Tool definitions ride outside the message array. Passing an empty
+                    // message list yields the tools-only overhead, and reuses the same
+                    // estimator the wire path already trusts.
+                    fixedOverheadTokens: estimateWireTokens([], openAITools, this.providerName),
+                    provider: this.providerName,
+                    observedPromptTokens: lastObservedPromptTokens,
+                    // Both halves of the calibration ratio must describe the same
+                    // request: the tokens the provider reported, and this guard's own
+                    // estimate for what was sent to earn them.
+                    previousSentEstimate: lastSentEstimate,
+                    onSentEstimate: (tokens) => {
+                        lastSentEstimate = tokens;
+                    },
+                });
+                if (guarded) {
+                    conversation.length = 0;
+                    conversation.push(...guarded);
+                }
                 const stepResult = await this.streamOneStep({
                     modelId,
                     url,
@@ -806,6 +842,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     openAIToolChoice,
                     pushChunk,
                 });
+                lastObservedPromptTokens = stepResult.usage?.prompt_tokens;
                 stepFinish = stepResult.finishReason;
                 if (stepResult.usage) {
                     stepUsage = mergeUsage(stepUsage, stepResult.usage);

package/dist/lib/types/context.d.ts

@@ -412,6 +412,79 @@ export type RepairResult = {
     orphanedCallsFixed: number;
     orphanedResultsFixed: number;
 };
+/**
+ * Provider-neutral view of ONE message in an agent loop's history.
+ *
+ * Every native provider loop keeps its history in a different shape (AI-SDK
+ * `ModelMessage`, OpenAI-compatible `{role,tool_calls}`, Gemini `contents`
+ * parts, Anthropic content blocks). The reclaim POLICY is identical across all
+ * of them, so adapters map their own shape onto this view, ask the core what to
+ * do, and apply the answer themselves.
+ */
+export type LoopGuardEntry = {
+    /** `toolCall` and `toolResult` form the batches the policy keeps intact. */
+    kind: "other" | "toolCall" | "toolResult";
+    /** Estimated tokens this entry currently costs. */
+    tokens: number;
+    /**
+     * Tokens this entry would cost with its payload replaced by a head/tail
+     * preview. Omitted when the entry cannot usefully shrink — which is exactly
+     * the case that forces the policy to drop batches instead.
+     */
+    previewTokens?: number;
+};
+/** What the caller should do to reclaim budget. Indices refer to the input array. */
+export type LoopGuardPlan = {
+    /** False when the loop is under threshold and nothing should change. */
+    fire: boolean;
+    /** Entries whose payload should be replaced by a preview. */
+    truncate: number[];
+    /** Entries to remove entirely — always whole batches, never a partial pair. */
+    drop: number[];
+    /** Estimated total after applying the plan, including fixed overhead. */
+    projectedTokens: number;
+};
+/**
+ * Structural view of one Anthropic content block, loose enough to accept the
+ * official SDK's `ContentBlockParam` union and NeuroLink's own
+ * `VertexAnthropicMessage` blocks without a cast at either call site.
+ */
+export type AnthropicGuardBlock = {
+    type: string;
+    /** Payload of a `tool_result` block. Other block kinds carry other fields. */
+    content?: unknown;
+    /** Text of a `text` block. */
+    text?: string;
+};
+/**
+ * Structural view of one Anthropic-shaped message, as used by both the direct
+ * Anthropic loop and the native Vertex+Claude path. Tool calls ride as
+ * `tool_use` blocks on an assistant message; their answers ride as
+ * `tool_result` blocks on the following user message.
+ */
+export type AnthropicGuardMessage = {
+    /**
+     * `system` is included because the installed `@anthropic-ai/sdk` widens
+     * `MessageParam["role"]` to accept it; narrowing here would make the SDK's
+     * own array unassignable at the call site.
+     */
+    role: "user" | "assistant" | "system";
+    content: string | AnthropicGuardBlock[];
+};
+/** Tuning for {@link planLoopGuardReclaim}. */
+export type LoopGuardPolicy = {
+    availableInputTokens: number;
+    /** System prompt + tool definitions — rides outside the message array. */
+    fixedOverheadTokens: number;
+    /** Fraction of the window at which the guard fires. */
+    thresholdRatio?: number;
+    /** Fraction of the window the guard reclaims down to once it fires. */
+    lowWaterRatio?: number;
+    /** Newest entries the guard must never modify. */
+    protectedTailCount?: number;
+    /** Observed/estimated token ratio, used to tighten both marks. */
+    calibration?: number;
+};
 /**
  * One contiguous tool batch: the run of `tool_call` messages emitted by a
  * single agent step, plus the run of `tool_result` messages that follows it.

package/dist/lib/utils/tokenEstimation.d.ts

@@ -52,7 +52,7 @@ export declare function estimateTokens(text: string, provider?: string, isCode?:
  * Includes message framing overhead.
  *
  * Counts `content` AND `args`. A `tool_call` is persisted with an EMPTY
- * `content` and its entire payload in `args` (see flushPendingToolExecutions),
+ * `content` and its entire payload in `args` (see flushPendingToolData),
  * so a content-only estimate scored a 39 KB Write call at ~28 tokens against a
  * real cost near 9,750 — the budget checker, the compaction trigger and the
  * summarization threshold were all blind to the single largest source of

package/dist/lib/utils/tokenEstimation.js

@@ -109,7 +109,7 @@ function serializeForEstimate(value) {
  * Includes message framing overhead.
  *
  * Counts `content` AND `args`. A `tool_call` is persisted with an EMPTY
- * `content` and its entire payload in `args` (see flushPendingToolExecutions),
+ * `content` and its entire payload in `args` (see flushPendingToolData),
  * so a content-only estimate scored a 39 KB Write call at ~28 tokens against a
  * real cost near 9,750 — the budget checker, the compaction trigger and the
  * summarization threshold were all blind to the single largest source of