@juspay/neurolink 10.10.3 → 10.10.4

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.10.3",
+  "version": "10.10.4",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -84,6 +84,7 @@
     "test:memory": "npx tsx test/continuous-test-suite-memory.ts",
     "test:tool-pairing": "npx tsx test/continuous-test-suite-tool-pairing.ts",
     "test:token-accounting": "npx tsx test/continuous-test-suite-token-accounting.ts",
+    "test:step-guard": "npx tsx test/continuous-test-suite-step-guard.ts",
     "test:middleware": "npx tsx test/continuous-test-suite-middleware.ts",
     "test:observability": "npx tsx test/continuous-test-suite-observability.ts",
     "test:ppt": "npx tsx test/continuous-test-suite-ppt.ts",