@animalabs/membrane 0.5.80 → 0.5.82

package/dist/cache-wire-receipt.d.ts

@@ -0,0 +1,13 @@
+export interface CacheWireMarkerReceipt {
+    ordinal: number;
+    prefixHash: string;
+    estimatedOffset: number;
+}
+export interface CacheWireReceipt {
+    requestHash: string;
+    markers: CacheWireMarkerReceipt[];
+}
+/** Hash the exact post-format/post-hook provider request and every marked
+ * prefix. Token offsets are estimates; provider usage reconciles them later. */
+export declare function computeCacheWireReceipt(rawRequest: unknown): CacheWireReceipt;
+//# sourceMappingURL=cache-wire-receipt.d.ts.map

package/dist/cache-wire-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-wire-receipt.d.ts","sourceRoot":"","sources":["../src/cache-wire-receipt.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAED;gFACgF;AAChF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,OAAO,GAAG,gBAAgB,CAkB7E"}

package/dist/cache-wire-receipt.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+/** Hash the exact post-format/post-hook provider request and every marked
+ * prefix. Token offsets are estimates; provider usage reconciles them later. */
+export function computeCacheWireReceipt(rawRequest) {
+    const requestHash = sha(stableStringify(rawRequest));
+    const blocks = flattenWireBlocks(rawRequest);
+    const prefix = [];
+    const markers = [];
+    let chars = 0;
+    for (const unit of blocks) {
+        prefix.push(unit.identity);
+        chars += unit.estimatedChars;
+        if (unit.marked) {
+            markers.push({
+                ordinal: markers.length,
+                prefixHash: sha(stableStringify(prefix)),
+                estimatedOffset: Math.ceil(chars / 4),
+            });
+        }
+    }
+    return { requestHash, markers };
+}
+function flattenWireBlocks(rawRequest) {
+    if (!rawRequest || typeof rawRequest !== 'object') {
+        return [{ identity: rawRequest, marked: false, estimatedChars: stableStringify(rawRequest).length }];
+    }
+    const request = rawRequest;
+    const out = [];
+    if (Array.isArray(request.tools)) {
+        request.tools.forEach((tool, index) => out.push({
+            identity: { surface: 'tool', index, tool },
+            marked: hasCacheControl(tool),
+            estimatedChars: stableStringify(tool).length,
+        }));
+    }
+    else if (request.tools !== undefined) {
+        out.push({
+            identity: { surface: 'tools', value: request.tools },
+            marked: hasCacheControl(request.tools),
+            estimatedChars: stableStringify(request.tools).length,
+        });
+    }
+    if (request.system !== undefined) {
+        const system = request.system;
+        if (Array.isArray(system)) {
+            system.forEach((block, index) => out.push({
+                identity: { surface: 'system', index, block },
+                marked: hasCacheControl(block),
+                estimatedChars: stableStringify(block).length,
+            }));
+        }
+        else {
+            out.push({
+                identity: { surface: 'system', value: system },
+                marked: hasCacheControl(system),
+                estimatedChars: stableStringify(system).length,
+            });
+        }
+    }
+    if (Array.isArray(request.messages)) {
+        request.messages.forEach((message, messageIndex) => {
+            if (!message || typeof message !== 'object') {
+                out.push({
+                    identity: { surface: 'message', messageIndex, value: message },
+                    marked: false,
+                    estimatedChars: stableStringify(message).length,
+                });
+                return;
+            }
+            const record = message;
+            const content = message.content;
+            if (Array.isArray(content)) {
+                content.forEach((block, blockIndex) => out.push({
+                    identity: {
+                        surface: 'message-block', messageIndex, blockIndex,
+                        role: record.role, block,
+                    },
+                    marked: hasCacheControl(block),
+                    estimatedChars: stableStringify({ role: record.role, content: [block] }).length,
+                }));
+            }
+            else {
+                out.push({
+                    identity: { surface: 'message', messageIndex, role: record.role, content },
+                    marked: hasCacheControl(message),
+                    estimatedChars: stableStringify(message).length,
+                });
+            }
+        });
+    }
+    return out;
+}
+function hasCacheControl(value) {
+    return Boolean(value && typeof value === 'object' && value.cache_control);
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function sha(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+//# sourceMappingURL=cache-wire-receipt.js.map

package/dist/cache-wire-receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-wire-receipt.js","sourceRoot":"","sources":["../src/cache-wire-receipt.ts"],"names":[],"mappings":"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"}

package/dist/context/index.d.ts

@@ -7,6 +7,6 @@
 export { processContext } from './process.js';
 export { shouldRoll, truncateMessages, placeCacheMarkers, applyCacheMarkers, calculateCharacters, } from './process.js';
 export type { RollDecision, MessageWithTokens, } from './process.js';
-export { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, } from './types.js';
+export { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, MembraneContextIdentityError, } from './types.js';
 export type { ContextInput, ContextOutput, ContextState, ContextConfig, ContextInfo, ContextStreamOptions, ContextToolCallback, ContextPreToolCallback, CacheMarker, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,YAAY,EACZ,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,YAAY,EACZ,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/context/index.js

@@ -7,5 +7,5 @@
 export { processContext } from './process.js';
 // Rolling helpers - can be used standalone by callers doing their own transforms
 export { shouldRoll, truncateMessages, placeCacheMarkers, applyCacheMarkers, calculateCharacters, } from './process.js';
-export { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, } from './types.js';
+export { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, MembraneContextIdentityError, } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,iFAAiF;AACjF,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,iFAAiF;AACjF,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,YAAY,CAAC"}

package/dist/context/process.d.ts

@@ -26,6 +26,8 @@ export interface RollDecision {
     reason?: 'threshold' | 'grace_exceeded' | 'hard_limit';
     targetTokens?: number;
     targetMessages?: number;
+    /** Character budget the kept window must fit (set by the maxCharacters limit). */
+    targetCharacters?: number;
     enteredGrace: boolean;
 }
 export declare function shouldRoll(state: ContextState, messageCount: number, totalTokens: number, totalCharacters: number, config: ContextConfig): RollDecision;
@@ -34,7 +36,7 @@ export interface MessageWithTokens {
     tokens: number;
     id: string;
 }
-export declare function truncateMessages(messages: MessageWithTokens[], targetTokens?: number, targetMessages?: number, config?: ContextConfig): {
+export declare function truncateMessages(messages: MessageWithTokens[], targetTokens?: number, targetMessages?: number, config?: ContextConfig, targetCharacters?: number): {
     kept: MessageWithTokens[];
     dropped: number;
 };

package/dist/context/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/context/process.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EAEb,aAAa,EACb,oBAAoB,EACpB,WAAW,EACZ,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,aAAa,CAAC,CAgIxB;AA2CD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAgBzE;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,aAAa,GACpB,YAAY,CAiEd;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,YAAY,CAAC,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,aAAa,GACrB;IAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA+ChD;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,aAAa,EAAE,iBAAiB,EAAE,EAClC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,aAAa,GACpB,WAAW,EAAE,CAqGf;AA4BD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,YAAY,EAAE,WAAW,EAAE,GAC1B,iBAAiB,EAAE,CAmBrB"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/context/process.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EAEb,aAAa,EACb,oBAAoB,EACpB,WAAW,EACZ,MAAM,YAAY,CAAC;AA6BpB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,aAAa,CAAC,CAkJxB;AAuGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAgBzE;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,aAAa,GACpB,YAAY,CAuEd;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,YAAY,CAAC,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,aAAa,EACtB,gBAAgB,CAAC,EAAE,MAAM,GACxB;IAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkDhD;AA0GD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,aAAa,EAAE,iBAAiB,EAAE,EAClC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,aAAa,GACpB,WAAW,EAAE,CAqHf;AA0CD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,YAAY,EAAE,WAAW,EAAE,GAC1B,iBAAiB,EAAE,CAuBrB"}

package/dist/context/process.js

@@ -1,7 +1,23 @@
 /**
  * Context processing - main entry point
  */
-import { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, } from './types.js';
+import { createInitialState, defaultTokenEstimator, DEFAULT_CONTEXT_CONFIG, MembraneContextIdentityError, } from './types.js';
+/**
+ * Ceiling on markers this module places, regardless of `cache.points`.
+ *
+ * Anthropic accepts at most 4 `cache_control` blocks per request, and the
+ * request builders spend from that same budget (a system/tools fallback
+ * block, a `contextPrefix` block when that option is set, the floating
+ * tool-loop marker). Nothing reconciles those spends against
+ * `cache.points`, so the module keeps one slot free rather than risk a 400
+ * on the default XML path, which always marks the system block. A caller
+ * combining this module with MORE than one formatter spend (e.g. system
+ * prompt AND `contextPrefix`) can still exceed the provider budget: the
+ * module cannot see the formatter's choices from here, which is why the
+ * request-side wire clamp (the cache-marker budget PR) is the layer that
+ * makes the ceiling safe by construction rather than by convention.
+ */
+const MAX_MODULE_CACHE_POINTS = 3;
 // ============================================================================
 // Main Entry Point
 // ============================================================================
@@ -24,6 +40,9 @@ export async function processContext(membrane, input, state, options) {
     // Merge config with defaults
     const contextConfig = mergeConfig(input.context);
     const tokenEstimator = contextConfig.tokenEstimator ?? defaultTokenEstimator;
+    // Stable identity is a precondition, not a nicety: without it every call
+    // looks like a new conversation and rolling/caching silently stop working.
+    assertStableMessageIds(input.messages);
     // Initialize or continue state
     let currentState = state ?? createInitialState();
     // Detect discontinuity (new conversation or branch switch)
@@ -47,10 +66,13 @@ export async function processContext(membrane, input, state, options) {
     let didRoll = false;
     let hardLimitHit = false;
     if (rollDecision.shouldRoll) {
-        const truncateResult = truncateMessages(messageTokens, rollDecision.targetTokens, rollDecision.targetMessages, contextConfig);
+        const truncateResult = truncateMessages(messageTokens, rollDecision.targetTokens, rollDecision.targetMessages, contextConfig, rollDecision.targetCharacters);
         keptMessages = truncateResult.kept.map(m => m.message);
         messagesDropped = truncateResult.dropped;
-        didRoll = true;
+        // A roll that dropped nothing is not a roll: reporting it as one both
+        // lies to the caller and resets the roll counters every call, which is
+        // exactly when threshold rolling is needed most.
+        didRoll = messagesDropped > 0;
         hardLimitHit = rollDecision.reason === 'hard_limit';
     }
     // Recalculate tokens after truncation
@@ -60,6 +82,10 @@ export async function processContext(membrane, input, state, options) {
         id: getMessageId(m),
     }));
     const keptTotalTokens = keptTokens.reduce((sum, m) => sum + m.tokens, 0);
+    // Re-assert the hard limits against the truncated window. The window is
+    // floored at one message, so a single oversize message survives every
+    // truncation - the caller is told rather than handed an empty array.
+    const residualOverflow = measureResidualOverflow(keptMessages, keptTotalTokens, contextConfig);
     // Place cache markers
     const cacheMarkers = placeCacheMarkers(keptMessages, keptTokens, currentState, didRoll, contextConfig);
     // Apply cache markers to messages
@@ -111,6 +137,7 @@ export async function processContext(membrane, input, state, options) {
         totalTokens: keptTotalTokens,
         hardLimitHit,
         cachedStartMessageId,
+        ...(residualOverflow ? { residualOverflow } : {}),
     };
     return { response, state: newState, info };
 }
@@ -118,7 +145,13 @@ export async function processContext(membrane, input, state, options) {
 // Helper Functions
 // ============================================================================
 function mergeConfig(config) {
+    // The caller's config is the base, so a top-level field is carried through
+    // by default and only the three sub-objects that have defaults are merged.
+    // Enumerating the survivors instead silently dropped assistantParticipant:
+    // every helper test passed a config straight in, so the loss was invisible
+    // until an end-to-end call classified the configured assistant as a user.
     return {
+        ...config,
         rolling: {
             ...DEFAULT_CONTEXT_CONFIG.rolling,
             ...config.rolling,
@@ -131,12 +164,50 @@ function mergeConfig(config) {
             ...DEFAULT_CONTEXT_CONFIG.cache,
             ...config.cache,
         },
-        tokenEstimator: config.tokenEstimator,
     };
 }
 function getMessageId(message) {
     return message.metadata?.sourceId ?? `msg-${Math.random().toString(36).slice(2)}`;
 }
+function assertStableMessageIds(messages) {
+    const messageIndicesWithoutSourceId = [];
+    messages.forEach((message, index) => {
+        const sourceId = message.metadata?.sourceId;
+        if (typeof sourceId !== 'string' || sourceId.length === 0) {
+            messageIndicesWithoutSourceId.push(index);
+        }
+    });
+    if (messageIndicesWithoutSourceId.length === 0) {
+        return;
+    }
+    const shown = messageIndicesWithoutSourceId.slice(0, 10).join(', ');
+    const ellipsis = messageIndicesWithoutSourceId.length > 10 ? ', ...' : '';
+    throw new MembraneContextIdentityError(`processContext requires stable message identity: ` +
+        `${messageIndicesWithoutSourceId.length} of ${messages.length} messages carry no ` +
+        `metadata.sourceId (indices ${shown}${ellipsis}). Without it every call is detected ` +
+        `as a new conversation, so the roll threshold never accumulates, cache markers never ` +
+        `stay stable, and cachedStartMessageId is meaningless. Populate metadata.sourceId ` +
+        `with the originating system's message id.`, messageIndicesWithoutSourceId);
+}
+function measureResidualOverflow(keptMessages, keptTotalTokens, config) {
+    const limits = config.limits;
+    if (!limits) {
+        return undefined;
+    }
+    if (limits.maxCharacters) {
+        const keptCharacters = calculateCharacters(keptMessages);
+        if (keptCharacters > limits.maxCharacters) {
+            return { unit: 'characters', limit: limits.maxCharacters, actual: keptCharacters };
+        }
+    }
+    if (limits.maxTokens && keptTotalTokens > limits.maxTokens) {
+        return { unit: 'tokens', limit: limits.maxTokens, actual: keptTotalTokens };
+    }
+    if (limits.maxMessages && keptMessages.length > limits.maxMessages) {
+        return { unit: 'messages', limit: limits.maxMessages, actual: keptMessages.length };
+    }
+    return undefined;
+}
 function detectDiscontinuity(messages, state) {
     if (state.windowMessageIds.length === 0) {
         return false; // First call, not a discontinuity
@@ -177,6 +248,7 @@ export function shouldRoll(state, messageCount, totalTokens, totalCharacters, co
             reason: 'hard_limit',
             targetTokens: limits.maxTokens,
             targetMessages: limits.maxMessages,
+            targetCharacters: limits.maxCharacters,
             enteredGrace: false,
         };
     }
@@ -186,6 +258,7 @@ export function shouldRoll(state, messageCount, totalTokens, totalCharacters, co
             reason: 'hard_limit',
             targetTokens: limits.maxTokens,
             targetMessages: limits.maxMessages,
+            targetCharacters: limits.maxCharacters,
             enteredGrace: false,
         };
     }
@@ -195,11 +268,15 @@ export function shouldRoll(state, messageCount, totalTokens, totalCharacters, co
             reason: 'hard_limit',
             targetTokens: limits.maxTokens,
             targetMessages: limits.maxMessages,
+            targetCharacters: limits.maxCharacters,
             enteredGrace: false,
         };
     }
-    // Check rolling threshold
-    const current = unit === 'messages' ? state.messagesSinceRoll : state.tokensSinceRoll;
+    // Check rolling threshold against the MEASURED window. state.messagesSinceRoll
+    // counts calls (not messages) and state.tokensSinceRoll re-adds the whole
+    // window every call, so both cross any threshold as a function of call count
+    // alone; they stay as telemetry and no longer decide the roll.
+    const current = unit === 'messages' ? messageCount : totalTokens;
     if (current >= maxThreshold) {
         // Exceeded grace, must roll
         return {
@@ -222,53 +299,132 @@ export function shouldRoll(state, messageCount, totalTokens, totalCharacters, co
         enteredGrace: false,
     };
 }
-export function truncateMessages(messages, targetTokens, targetMessages, config) {
-    // Truncate from the beginning, keeping most recent
-    if (targetMessages && messages.length > targetMessages) {
-        const startIdx = messages.length - targetMessages;
-        return {
-            kept: messages.slice(startIdx),
-            dropped: startIdx,
-        };
+export function truncateMessages(messages, targetTokens, targetMessages, config, targetCharacters) {
+    // Truncate from the beginning, keeping most recent.
+    // Every supplied target contributes a candidate start index; the window has
+    // to satisfy all of them, so the deepest cut wins.
+    if (messages.length === 0) {
+        return { kept: messages, dropped: 0 };
+    }
+    const candidateStartIndices = [];
+    if (targetMessages !== undefined && messages.length > targetMessages) {
+        candidateStartIndices.push(messages.length - targetMessages);
+    }
+    if (targetTokens !== undefined) {
+        candidateStartIndices.push(startIndexForBudget(messages, targetTokens, m => m.tokens));
+    }
+    if (targetCharacters !== undefined) {
+        candidateStartIndices.push(startIndexForBudget(messages, targetCharacters, m => calculateCharacters([m.message])));
     }
-    if (targetTokens) {
-        let tokenSum = 0;
-        let startIdx = messages.length;
-        // Count from end backwards
-        for (let i = messages.length - 1; i >= 0; i--) {
-            tokenSum += messages[i].tokens;
-            if (tokenSum > targetTokens) {
-                startIdx = i + 1;
-                break;
+    if (candidateStartIndices.length === 0) {
+        // Default: use buffer from config
+        const buffer = config?.rolling.buffer ?? 20;
+        const unit = config?.rolling.unit ?? 'messages';
+        if (unit === 'messages') {
+            const targetCount = Math.max(buffer * 2, messages.length - buffer);
+            if (messages.length > targetCount) {
+                candidateStartIndices.push(messages.length - targetCount);
             }
-            startIdx = i;
         }
-        return {
-            kept: messages.slice(startIdx),
-            dropped: startIdx,
-        };
     }
-    // Default: use buffer from config
-    const buffer = config?.rolling.buffer ?? 20;
-    const unit = config?.rolling.unit ?? 'messages';
-    if (unit === 'messages') {
-        const targetCount = Math.max(buffer * 2, messages.length - buffer);
-        if (messages.length > targetCount) {
-            const startIdx = messages.length - targetCount;
-            return {
-                kept: messages.slice(startIdx),
-                dropped: startIdx,
-            };
+    if (candidateStartIndices.length === 0) {
+        return { kept: messages, dropped: 0 };
+    }
+    const startIdx = resolveWindowStart(messages, Math.max(0, ...candidateStartIndices));
+    return {
+        kept: messages.slice(startIdx),
+        dropped: startIdx,
+    };
+}
+/**
+ * Walk backwards from the newest message, accumulating cost, and return the
+ * first index whose window fits the budget. Mirrors the original token walk:
+ * the message that tips the sum past the budget is excluded.
+ */
+function startIndexForBudget(messages, budget, costOf) {
+    let sum = 0;
+    let startIdx = messages.length;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        sum += costOf(messages[i]);
+        if (sum > budget) {
+            return i + 1;
+        }
+        startIdx = i;
+    }
+    return startIdx;
+}
+/**
+ * Resolve the index the kept window actually starts at: the deepest cut at or
+ * after the requested one whose window is both non-empty and free of
+ * tool_results whose tool_use was dropped.
+ *
+ * Snapping forward and flooring at one message used to be two independent
+ * steps that could undo each other. When the newest message is a tool_result,
+ * the forward snap runs off the end of the array and the floor pulls the index
+ * back onto that same orphan - so truncating a final tool cycle to one message
+ * kept exactly the result, which is what the snap exists to prevent. A cut that
+ * cannot go forward now walks BACKWARD to the call that opens the final cycle:
+ * the window overshoots the requested size (reported through
+ * ContextInfo.residualOverflow) rather than shipping a corrupt transcript.
+ */
+function resolveWindowStart(messages, desiredStartIdx) {
+    const lastIdx = messages.length - 1;
+    if (desiredStartIdx <= 0) {
+        return 0;
+    }
+    const windowIsCleanAt = markCleanWindowStarts(messages);
+    const cappedStartIdx = Math.min(desiredStartIdx, lastIdx);
+    for (let idx = cappedStartIdx; idx <= lastIdx; idx++) {
+        if (windowIsCleanAt[idx]) {
+            return idx;
+        }
+    }
+    for (let idx = cappedStartIdx - 1; idx >= 0; idx--) {
+        if (windowIsCleanAt[idx]) {
+            return idx;
+        }
+    }
+    // No clean boundary exists anywhere: the supplied history itself carries a
+    // tool_result whose tool_use is not in it. Dropping messages cannot repair
+    // that, so the requested cut stands, floored at one message.
+    return cappedStartIdx;
+}
+/**
+ * For every index, whether the window starting there contains no tool_result
+ * whose tool_use is missing from it. A result is matched by a tool_use in an
+ * earlier message or earlier in its own message, so one backward pass carrying
+ * the still-unmatched result ids answers every index in linear time.
+ */
+function markCleanWindowStarts(messages) {
+    const windowIsCleanAt = new Array(messages.length).fill(false);
+    const resultIdsAwaitingTheirCall = new Set();
+    for (let idx = messages.length - 1; idx >= 0; idx--) {
+        const callIdsInMessage = new Set();
+        const resultIdsNeedingAnEarlierCall = [];
+        for (const block of messages[idx].message.content) {
+            if (block.type === 'tool_use') {
+                callIdsInMessage.add(block.id);
+            }
+            else if (block.type === 'tool_result' && !callIdsInMessage.has(block.toolUseId)) {
+                resultIdsNeedingAnEarlierCall.push(block.toolUseId);
+            }
+        }
+        for (const callId of callIdsInMessage) {
+            resultIdsAwaitingTheirCall.delete(callId);
+        }
+        for (const resultId of resultIdsNeedingAnEarlierCall) {
+            resultIdsAwaitingTheirCall.add(resultId);
         }
+        windowIsCleanAt[idx] = resultIdsAwaitingTheirCall.size === 0;
     }
-    return { kept: messages, dropped: 0 };
+    return windowIsCleanAt;
 }
 export function placeCacheMarkers(messages, messageTokens, state, didRoll, config) {
     const cacheConfig = config.cache ?? {};
     if (cacheConfig.enabled === false) {
         return [];
     }
-    const numPoints = cacheConfig.points ?? 1;
+    const numPoints = Math.min(cacheConfig.points ?? 1, MAX_MODULE_CACHE_POINTS);
     const minTokens = cacheConfig.minTokens ?? 1024;
     const preferUser = cacheConfig.preferUserMessages ?? true;
     const totalTokens = messageTokens.reduce((sum, m) => sum + m.tokens, 0);
@@ -281,8 +437,16 @@ export function placeCacheMarkers(messages, messageTokens, state, didRoll, confi
         const currentIds = new Set(messages.map(m => getMessageId(m)));
         const validMarkers = state.cacheMarkers.filter(m => currentIds.has(m.messageId));
         if (validMarkers.length > 0) {
-            // Recalculate token estimates for valid markers
-            return validMarkers.map(marker => {
+            // Recalculate token estimates for valid markers, then apply the same cap
+            // fresh placement obeys. The cap is a property of the REQUEST (Anthropic
+            // accepts four cache_control blocks and the builders spend from the same
+            // budget), so honouring it only on the fresh path let a state written
+            // before the cap existed - or by a caller that asked for four points -
+            // keep re-spending four slots on every subsequent call, which is where
+            // the builders' own marker turns the request into a 400. The deepest
+            // markers cover the longest prefixes, so those are the ones kept.
+            const retainedMarkers = validMarkers
+                .map(marker => {
                 const idx = messages.findIndex(m => getMessageId(m) === marker.messageId);
                 const tokenEstimate = messageTokens
                     .slice(0, idx + 1)
@@ -292,7 +456,9 @@ export function placeCacheMarkers(messages, messageTokens, state, didRoll, confi
                     messageIndex: idx,
                     tokenEstimate,
                 };
-            });
+            })
+                .sort((a, b) => a.messageIndex - b.messageIndex);
+            return retainedMarkers.slice(-MAX_MODULE_CACHE_POINTS);
         }
     }
     // Place new markers using arithmetic positioning
@@ -322,7 +488,7 @@ export function placeCacheMarkers(messages, messageTokens, state, didRoll, confi
         let markerTokens = runningTokens;
         // Adjust to user message if preferred
         if (preferUser) {
-            const adjusted = findNearestUserMessage(messages, markerIdx, messageTokens);
+            const adjusted = findNearestUserMessage(messages, markerIdx, messageTokens, config.assistantParticipant);
             if (adjusted) {
                 markerIdx = adjusted.index;
                 markerTokens = adjusted.tokens;
@@ -344,15 +510,26 @@ export function placeCacheMarkers(messages, messageTokens, state, didRoll, confi
     }
     return markers;
 }
-function findNearestUserMessage(messages, startIdx, messageTokens) {
+/** Assistant names assumed when the deployment configures none. */
+const LEGACY_ASSISTANT_PARTICIPANTS = ['claude', 'assistant', 'bot', 'ai'];
+function findNearestUserMessage(messages, startIdx, messageTokens, assistantParticipant) {
     // Search backwards for a user message (non-assistant participant)
     const maxSearch = 5;
+    // A deployment whose assistant is named anything else (Sol, a persona name)
+    // had every assistant turn classified as a user turn by the legacy list.
+    const assistantNames = assistantParticipant
+        ? [assistantParticipant.toLowerCase()]
+        : LEGACY_ASSISTANT_PARTICIPANTS;
     let tokens = messageTokens.slice(0, startIdx + 1).reduce((sum, m) => sum + m.tokens, 0);
     for (let i = startIdx; i >= Math.max(0, startIdx - maxSearch); i--) {
         const msg = messages[i];
-        // Heuristic: if participant isn't a common assistant name, it's probably a user
-        const participant = msg.participant.toLowerCase();
-        const isUser = !['claude', 'assistant', 'bot', 'ai'].includes(participant);
+        // Heuristic: if participant isn't a known assistant name, it's probably a
+        // user. A message with no participant at all (role-shaped producers) falls
+        // through the same way rather than crashing the whole call.
+        const participant = typeof msg.participant === 'string'
+            ? msg.participant.toLowerCase()
+            : '';
+        const isUser = !assistantNames.includes(participant);
         if (isUser) {
             return { index: i, tokens };
         }
@@ -369,6 +546,10 @@ export function applyCacheMarkers(messages, cacheMarkers) {
         if (markerIndices.has(idx)) {
             return {
                 ...msg,
+                // cacheBreakpoint is the field every request builder reads; the
+                // metadata.cacheControl write has no reader inside membrane and is
+                // kept only for external consumers that may already read it.
+                cacheBreakpoint: true,
                 metadata: {
                     ...msg.metadata,
                     cacheControl: { type: 'ephemeral' },