@juspay/neurolink 10.10.4 → 10.10.6

package/dist/context/anthropicLoopGuard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * In-turn context guard for Anthropic-shaped agent loops.
+ *
+ * The direct Anthropic loop (`providers/anthropic/client.ts`) grows a
+ * `conversation` array on every step: an assistant message carrying `tool_use`
+ * blocks, then a user message carrying the matching `tool_result` blocks. It
+ * had no in-turn guard, so a long agentic run overflowed the window mid-loop
+ * and lost every completed step.
+ *
+ * Granularity differs from the OpenAI-compatible shape: there, each tool result
+ * is its own message; here, ONE user message carries every `tool_result` for a
+ * step. That makes the message the natural batch unit — dropping an assistant
+ * `tool_use` message together with its following `tool_result` message can
+ * never orphan a block, which Anthropic rejects outright.
+ *
+ * The reclaim POLICY lives in `loopGuardCore` and is shared with the other
+ * provider loops. This module owns only the shape mapping.
+ */
+import type { AnthropicGuardMessage, LoopGuardPlan } from "../types/index.js";
+/** Marker left where dropped history used to be. */
+export declare const ANTHROPIC_ELISION_NOTE = "[Earlier tool exchanges were removed to fit the context window.]";
+/**
+ * Text-level preview used for an oversized `tool_result` payload. Exposed so
+ * the caller can apply it to its OWN block type — this module never rebuilds
+ * the caller's messages, which keeps it free of generic-spread assignability
+ * problems and of the double type assertions Critical Rule 14 forbids.
+ */
+export declare function previewAnthropicToolResultText(text: string): string;
+/** True when this message carries `tool_result` blocks worth previewing. */
+export declare function isAnthropicToolResultMessage(message: AnthropicGuardMessage): boolean;
+/**
+ * Decide what to reclaim from an Anthropic-shaped agent loop.
+ *
+ * Returns `undefined` when the loop still fits — the caller must then leave its
+ * history byte-identical, because any rewrite invalidates the rolling
+ * `cache_control` prefix this path depends on.
+ */
+export declare function planAnthropicLoopReclaim(args: {
+    conversation: readonly AnthropicGuardMessage[];
+    availableInputTokens: number;
+    fixedOverheadTokens: number;
+    provider?: string;
+    observedPromptTokens?: number;
+    previousSentEstimate?: number;
+    onSentEstimate?: (tokens: number) => void;
+}): LoopGuardPlan | undefined;

package/dist/context/anthropicLoopGuard.js

@@ -0,0 +1,167 @@
+/**
+ * In-turn context guard for Anthropic-shaped agent loops.
+ *
+ * The direct Anthropic loop (`providers/anthropic/client.ts`) grows a
+ * `conversation` array on every step: an assistant message carrying `tool_use`
+ * blocks, then a user message carrying the matching `tool_result` blocks. It
+ * had no in-turn guard, so a long agentic run overflowed the window mid-loop
+ * and lost every completed step.
+ *
+ * Granularity differs from the OpenAI-compatible shape: there, each tool result
+ * is its own message; here, ONE user message carries every `tool_result` for a
+ * step. That makes the message the natural batch unit — dropping an assistant
+ * `tool_use` message together with its following `tool_result` message can
+ * never orphan a block, which Anthropic rejects outright.
+ *
+ * The reclaim POLICY lives in `loopGuardCore` and is shared with the other
+ * provider loops. This module owns only the shape mapping.
+ */
+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 other loop guards. */
+const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
+const OLD_TOOL_OUTPUT_PREVIEW_LINES = 60;
+/** Marker left where dropped history used to be. */
+export const ANTHROPIC_ELISION_NOTE = "[Earlier tool exchanges were removed to fit the context window.]";
+/** Serialize any value to text for estimation. Never throws. */
+function toText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return "";
+    }
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        // Past V8's string cap: enormous by definition, so charge a large fixed
+        // size rather than aborting the estimate and with it the turn.
+        return "x".repeat(200_000);
+    }
+}
+function blocksOf(message) {
+    return Array.isArray(message.content) ? message.content : [];
+}
+function hasBlockType(message, type) {
+    return blocksOf(message).some((block) => block.type === type);
+}
+/** Cost of one message including per-message framing. */
+function messageTokens(message, provider) {
+    return estimateTokens(toText(message.content), provider) + TOKENS_PER_MESSAGE;
+}
+/**
+ * Rewrite a `tool_result` message so every block's payload is a head/tail
+ * preview. `cache_control` and every other block field are preserved — only
+ * the payload shrinks.
+ */
+function previewToolResultMessage(message) {
+    if (!Array.isArray(message.content)) {
+        return message;
+    }
+    const content = message.content.map((block) => {
+        if (block.type !== "tool_result") {
+            return block;
+        }
+        const text = toText(block.content);
+        const previewOptions = {
+            maxBytes: OLD_TOOL_OUTPUT_PREVIEW_BYTES,
+            maxLines: OLD_TOOL_OUTPUT_PREVIEW_LINES,
+        };
+        if (!exceedsToolOutputPreviewBudget(text, previewOptions)) {
+            return block;
+        }
+        const { preview } = generateToolOutputPreview(text, previewOptions);
+        return { ...block, content: preview };
+    });
+    return { ...message, content };
+}
+/** 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 (hasBlockType(message, "tool_result")) {
+            const previewed = previewToolResultMessage(message);
+            const previewTokens = messageTokens(previewed, provider);
+            return {
+                kind: "toolResult",
+                tokens,
+                // Only advertise a preview when it actually saves something — an
+                // already-small result must fall through to stage 2, not look
+                // shrinkable and stall the reclaim.
+                ...(previewTokens < tokens ? { previewTokens } : {}),
+            };
+        }
+        if (hasBlockType(message, "tool_use")) {
+            return { kind: "toolCall", tokens };
+        }
+        return { kind: "other", tokens };
+    });
+}
+/**
+ * Text-level preview used for an oversized `tool_result` payload. Exposed so
+ * the caller can apply it to its OWN block type — this module never rebuilds
+ * the caller's messages, which keeps it free of generic-spread assignability
+ * problems and of the double type assertions Critical Rule 14 forbids.
+ */
+export function previewAnthropicToolResultText(text) {
+    const { preview } = generateToolOutputPreview(text, {
+        maxBytes: OLD_TOOL_OUTPUT_PREVIEW_BYTES,
+        maxLines: OLD_TOOL_OUTPUT_PREVIEW_LINES,
+    });
+    return preview;
+}
+/** True when this message carries `tool_result` blocks worth previewing. */
+export function isAnthropicToolResultMessage(message) {
+    return hasBlockType(message, "tool_result");
+}
+/**
+ * Decide what to reclaim from an Anthropic-shaped agent loop.
+ *
+ * Returns `undefined` when the loop still fits — the caller must then leave its
+ * history byte-identical, because any rewrite invalidates the rolling
+ * `cache_control` prefix this path depends on.
+ */
+export function planAnthropicLoopReclaim(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_use message plus its tool_result, 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;
+    }
+    logger.info("[AnthropicLoopGuard] Reclaiming agent-loop context", {
+        provider,
+        messages: conversation.length,
+        toolResultsTruncated: plan.truncate.length,
+        messagesDropped: plan.drop.length,
+        projectedTokens: plan.projectedTokens,
+        calibration,
+    });
+    onSentEstimate?.(plan.projectedTokens);
+    return plan;
+}

package/dist/context/loopGuardCore.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Provider-neutral agent-loop reclaim policy.
+ *
+ * Every native provider loop grows its own history as the model calls tools,
+ * and every one of them can overflow the model's window mid-turn. The policy
+ * for reclaiming that budget is identical regardless of message shape:
+ *
+ *   Stage 1 — shrink old tool outputs to head/tail previews.
+ *   Stage 2 — drop the oldest complete tool batches, as units, when previews
+ *             are not enough (or when outputs are already small enough that
+ *             truncation buys nothing).
+ *
+ * What differs per provider is only the message SHAPE. So this module owns the
+ * decision and adapters own the mechanics: map your history onto
+ * `LoopGuardEntry[]`, call `planLoopGuardReclaim`, apply the returned indices.
+ *
+ * Two invariants the policy never violates:
+ *   - entry 0 (the task) is never touched
+ *   - a tool batch is dropped whole or not at all, so a `tool_call` never
+ *     loses its `tool_result` (providers hard-reject the orphan)
+ */
+import type { LoopGuardEntry, LoopGuardPlan, LoopGuardPolicy } from "../types/index.js";
+/**
+ * Fraction of the window the guard reclaims DOWN TO once it fires.
+ *
+ * The threshold decides *when*; this decides *how far*. Reclaiming only back to
+ * the threshold means the next step — which appends an assistant turn plus its
+ * tool results — crosses it again, so the guard rewrites the oldest messages on
+ * every single step. That mutation invalidates the provider's cached prompt
+ * prefix each time. One deeper reclaim every N steps saves the same tokens and
+ * leaves the prefix stable in between.
+ */
+export declare const DEFAULT_LOOP_GUARD_LOW_WATER_RATIO = 0.6;
+/** Newest entries the guard never modifies. */
+export declare const DEFAULT_LOOP_GUARD_PROTECTED_TAIL = 4;
+/**
+ * Decide what to reclaim, if anything.
+ *
+ * Returns `fire: false` when the projected request is within threshold — the
+ * caller must then leave its history completely untouched, so a loop that fits
+ * never pays a cache invalidation.
+ */
+export declare function planLoopGuardReclaim(entries: readonly LoopGuardEntry[], policy: LoopGuardPolicy): LoopGuardPlan;

package/dist/context/loopGuardCore.js

@@ -0,0 +1,145 @@
+/**
+ * Provider-neutral agent-loop reclaim policy.
+ *
+ * Every native provider loop grows its own history as the model calls tools,
+ * and every one of them can overflow the model's window mid-turn. The policy
+ * for reclaiming that budget is identical regardless of message shape:
+ *
+ *   Stage 1 — shrink old tool outputs to head/tail previews.
+ *   Stage 2 — drop the oldest complete tool batches, as units, when previews
+ *             are not enough (or when outputs are already small enough that
+ *             truncation buys nothing).
+ *
+ * What differs per provider is only the message SHAPE. So this module owns the
+ * decision and adapters own the mechanics: map your history onto
+ * `LoopGuardEntry[]`, call `planLoopGuardReclaim`, apply the returned indices.
+ *
+ * Two invariants the policy never violates:
+ *   - entry 0 (the task) is never touched
+ *   - a tool batch is dropped whole or not at all, so a `tool_call` never
+ *     loses its `tool_result` (providers hard-reject the orphan)
+ */
+import { DEFAULT_CONTEXT_GUARD_RATIO } from "../core/constants.js";
+/**
+ * Fraction of the window the guard reclaims DOWN TO once it fires.
+ *
+ * The threshold decides *when*; this decides *how far*. Reclaiming only back to
+ * the threshold means the next step — which appends an assistant turn plus its
+ * tool results — crosses it again, so the guard rewrites the oldest messages on
+ * every single step. That mutation invalidates the provider's cached prompt
+ * prefix each time. One deeper reclaim every N steps saves the same tokens and
+ * leaves the prefix stable in between.
+ */
+export const DEFAULT_LOOP_GUARD_LOW_WATER_RATIO = 0.6;
+/** Newest entries the guard never modifies. */
+export const DEFAULT_LOOP_GUARD_PROTECTED_TAIL = 4;
+/** True for the two kinds that make up a tool batch. */
+function isToolEntry(entry) {
+    return entry?.kind === "toolCall" || entry?.kind === "toolResult";
+}
+/**
+ * One agent step's tool batch: the run of calls, then the run of results that
+ * answers them. `end` is exclusive.
+ *
+ * The boundary is calls-then-results, NOT any maximal run of tool entries — a
+ * loop's history is `call,result,call,result,…`, so treating a maximal run as
+ * one batch would collapse the entire conversation into a single droppable
+ * unit and scorch it in one pass. Mirrors `collectBatch` in toolPairRepair.
+ */
+function findToolBatches(entries, minIndex, maxIndexExclusive) {
+    const batches = [];
+    let i = minIndex;
+    while (i < maxIndexExclusive) {
+        if (!isToolEntry(entries[i])) {
+            i++;
+            continue;
+        }
+        const start = i;
+        // Scan each run to its TRUE end rather than clamping at the protected-tail
+        // boundary. A batch is droppable only as a whole: clamping would emit a
+        // batch ending exactly at the boundary, so stage 2 would remove the
+        // tool-call entry while the results at or past the boundary survive with
+        // nothing to pair against. Providers reject an orphaned tool result, so
+        // that turns a reclaim into a hard request failure.
+        while (i < entries.length && entries[i].kind === "toolCall") {
+            i++;
+        }
+        while (i < entries.length && entries[i].kind === "toolResult") {
+            i++;
+        }
+        if (i > maxIndexExclusive) {
+            // Scanning is oldest-first, so this batch reaching into the tail means
+            // every later one starts inside it. Nothing further is droppable.
+            break;
+        }
+        batches.push({ start, end: i });
+    }
+    return batches;
+}
+/**
+ * Decide what to reclaim, if anything.
+ *
+ * Returns `fire: false` when the projected request is within threshold — the
+ * caller must then leave its history completely untouched, so a loop that fits
+ * never pays a cache invalidation.
+ */
+export function planLoopGuardReclaim(entries, policy) {
+    const { availableInputTokens, fixedOverheadTokens, thresholdRatio = DEFAULT_CONTEXT_GUARD_RATIO, lowWaterRatio = DEFAULT_LOOP_GUARD_LOW_WATER_RATIO, protectedTailCount = DEFAULT_LOOP_GUARD_PROTECTED_TAIL, calibration = 1, } = policy;
+    const safeCalibration = calibration > 0 ? calibration : 1;
+    const thresholdTokens = Math.floor((availableInputTokens * thresholdRatio) / safeCalibration);
+    const lowWaterTokens = Math.floor((availableInputTokens * lowWaterRatio) / safeCalibration);
+    let total = fixedOverheadTokens;
+    for (const entry of entries) {
+        total += entry.tokens;
+    }
+    if (total <= thresholdTokens) {
+        return { fire: false, truncate: [], drop: [], projectedTokens: total };
+    }
+    // Entry 0 is the task and the newest `protectedTailCount` entries are the
+    // live working set — the mutable window sits strictly between them.
+    const minIndex = 1;
+    const maxIndexExclusive = Math.max(minIndex, entries.length - protectedTailCount);
+    const truncate = [];
+    const dropped = new Set();
+    // Stage 1: shrink old tool outputs, oldest first.
+    for (let i = minIndex; i < maxIndexExclusive && total > lowWaterTokens; i++) {
+        const entry = entries[i];
+        if (entry.kind !== "toolResult" || entry.previewTokens === undefined) {
+            continue;
+        }
+        const saving = entry.tokens - entry.previewTokens;
+        if (saving <= 0) {
+            continue;
+        }
+        truncate.push(i);
+        total -= saving;
+    }
+    // Stage 2: drop whole batches, oldest first, while still over the low-water
+    // mark. This is the only lever when outputs are already smaller than a
+    // preview — the regime where truncation alone cannot converge.
+    if (total > lowWaterTokens) {
+        const batches = findToolBatches(entries, minIndex, maxIndexExclusive);
+        for (const batch of batches) {
+            if (total <= lowWaterTokens) {
+                break;
+            }
+            for (let i = batch.start; i < batch.end; i++) {
+                const entry = entries[i];
+                // A truncated entry now costs its preview, not its original payload.
+                const effective = truncate.includes(i)
+                    ? (entry.previewTokens ?? entry.tokens)
+                    : entry.tokens;
+                total -= effective;
+                dropped.add(i);
+            }
+        }
+    }
+    // Truncating an entry that is being dropped anyway is wasted work.
+    const effectiveTruncate = truncate.filter((i) => !dropped.has(i));
+    return {
+        fire: effectiveTruncate.length > 0 || dropped.size > 0,
+        truncate: effectiveTruncate,
+        drop: [...dropped].sort((a, b) => a - b),
+        projectedTokens: total,
+    };
+}

package/dist/context/openaiCompatLoopGuard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { OpenAICompatChatMessage } from "../types/index.js";
+/**
+ * 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 declare function guardOpenAICompatConversation(args: {
+    conversation: OpenAICompatChatMessage[];
+    availableInputTokens: number;
+    fixedOverheadTokens: number;
+    provider?: string;
+    observedPromptTokens?: number;
+    previousSentEstimate?: number;
+    onSentEstimate?: (tokens: number) => void;
+}): OpenAICompatChatMessage[] | undefined;

package/dist/context/openaiCompatLoopGuard.js

@@ -0,0 +1,172 @@
+/**
+ * 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;
+}

package/dist/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/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.