mixdog 0.9.41 → 0.9.43

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -6,6 +6,8 @@ import { randomUUID } from 'crypto';
 import { smartReadTruncate } from '../tools/builtin/read-formatting.mjs';
 import { shutdownStdioChild, killStdioChildTreeFast } from './child-tree.mjs';
 import { readServicePort, markServiceUnreachable, isConnRefuseError } from '../../../shared/service-discovery.mjs';
+import { makeToolEnvelope, normalizeToolEnvelope } from '../session/tool-envelope.mjs';
+import { classifyResultKind } from '../session/result-classification.mjs';
 // --- Types ---
 /** Known auto-detect targets: port file path relative to tmpdir.
  *  Note: `mixdog` used to self-loopback via active-instance.json's
@@ -215,6 +217,16 @@ export async function executeMcpTool(name, args) {
             throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
         }
     }
+    const normalized = normalizeToolEnvelope(normalizeMcpToolResult(result));
+    const text = capMcpOutput(normalized.result);
+    return normalized.explicitSuccess
+        ? makeToolEnvelope(text, [], { explicitSuccess: true })
+        : text;
+}
+
+// Preserve MCP failure metadata across the object→string boundary. The
+// session loop classifies the canonical Error: prefix as toolKind:error.
+export function normalizeMcpToolResult(result) {
     const content = result.content;
     let text;
     if (Array.isArray(content)) {
@@ -224,7 +236,11 @@ export async function executeMcpTool(name, args) {
     } else {
         text = typeof content === 'string' ? content : JSON.stringify(content);
     }
-    return capMcpOutput(text);
+    if (result.isError === true) return !text.startsWith('Error:') ? `Error: ${text}` : text;
+    if (result.isError === false && classifyResultKind(text) === 'error') {
+        return makeToolEnvelope(text, [], { explicitSuccess: true });
+    }
+    return text;
 }
 
 // MCP per-tool-call timeout. Default 2min: a hung/unresponsive MCP server

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-credentials.mjs

@@ -53,7 +53,10 @@ const OAUTH_SUCCESS_REDIRECT_URL = process.env.ANTHROPIC_OAUTH_SUCCESS_REDIRECT_
 const OAUTH_LOGIN_TIMEOUT_MS = 5 * 60_000;
 const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
 
-export const DEFAULT_CLI_VERSION = '2.1.77';
+// Anthropic's token edge validates the Claude Code client identity. Keep this
+// fallback aligned with the current official CLI while retaining the env
+// override for seats where Claude Code is updated ahead of Mixdog.
+export const DEFAULT_CLI_VERSION = '2.1.207';
 
 export function resolveCliVersion() {
     return process.env.MIXDOG_CLI_VERSION
@@ -210,14 +213,41 @@ export function _normalizeExpiresAt(value) {
     return value < 1e12 ? value * 1000 : value;
 }
 
-export function _scrubTokens(text) {
-    return String(text || '')
-        .replace(/Bearer [A-Za-z0-9._\-]+/g, 'Bearer [REDACTED]')
+export function _scrubTokens(text, secretValues = []) {
+    let scrubbed = String(text || '')
+        .replace(/Bearer [A-Za-z0-9._\-]+/gi, 'Bearer [REDACTED]')
         .replace(/sk-ant-[A-Za-z0-9._\-]+/g, '[REDACTED]')
         .replace(/"access[Tt]oken"\s*:\s*"[^"]+"/g, '"accessToken":"[REDACTED]"')
         .replace(/"refresh[Tt]oken"\s*:\s*"[^"]+"/g, '"refreshToken":"[REDACTED]"')
         .replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token":"[REDACTED]"')
         .replace(/"refresh_token"\s*:\s*"[^"]+"/g, '"refresh_token":"[REDACTED]"');
+    // Token services sometimes echo submitted values in non-JSON diagnostics.
+    // Scrub the exact request secrets as a final guard without logging them.
+    for (const secret of secretValues) {
+        if (typeof secret === 'string' && secret) {
+            scrubbed = scrubbed.split(secret).join('[REDACTED]');
+        }
+    }
+    return scrubbed;
+}
+
+function _tokenEndpointError(operation, status, text, secretValues = []) {
+    const safeDetail = _scrubTokens(text, secretValues)
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 500);
+    const detail = safeDetail ? `: ${safeDetail}` : '';
+    const compatibility = status === 403
+        ? (
+            ` Anthropic returned HTTP 403 for a request sent as claude-cli/${resolveCliVersion()}.`
+            + ' Possible causes include OAuth client compatibility, account or scope policy,'
+            + ' an intercepting proxy/VPN/WAF, or regional endpoint restrictions.'
+            + ' Verify the account has Claude Code access and the required scopes;'
+            + ' update Mixdog or set MIXDOG_CLI_VERSION to the installed official Claude Code version;'
+            + ' then retry sign-in via /providers without an intercepting network layer if applicable.'
+        )
+        : '';
+    return new Error(`${operation} ${status}${detail}.${compatibility}`);
 }
 
 export function isAnthropicOAuthRefreshDisabled() {
@@ -261,7 +291,15 @@ async function _refreshOAuthCredentialsUnlocked(creds) {
         try { json = text ? JSON.parse(text) : null; } catch { /* handled below */ }
         if (!res.ok) {
             const isInvalidGrant = text.includes('invalid_grant') || json?.error === 'invalid_grant';
-            throw Object.assign(new Error(`token refresh ${res.status}: ${_scrubTokens(text).slice(0, 200)}`), { isInvalidGrant });
+            throw Object.assign(
+                _tokenEndpointError(
+                    'token refresh',
+                    res.status,
+                    text,
+                    [creds.refreshToken, creds.accessToken],
+                ),
+                { isInvalidGrant },
+            );
         }
 
         const accessToken = json?.access_token || json?.accessToken;
@@ -495,7 +533,12 @@ async function exchangeAuthorizationCode({ pkce, code, state, redirectUri }) {
     });
     if (!tokenRes.ok) {
         const text = await tokenRes.text().catch(() => '');
-        throw new Error(`[anthropic-oauth] token exchange ${tokenRes.status}: ${_scrubTokens(text).slice(0, 500)}`);
+        throw _tokenEndpointError(
+            '[anthropic-oauth] token exchange',
+            tokenRes.status,
+            text,
+            [cleanCode, pkce.verifier, state],
+        );
     }
     const json = await tokenRes.json();
     const accessToken = json?.access_token || json?.accessToken;

package/src/runtime/agent/orchestrator/providers/anthropic-sse.mjs

@@ -111,6 +111,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
     let toolCalls = [];
     let usage = { inputTokens: 0, outputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, raw: null };
     let stopReason = null;
+    let stopDetails;
     let buffer = '';
     let idleTimedOut = false;
     let firstMessageTimedOut = false;
@@ -546,6 +547,18 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                         if (event.delta?.stop_reason) {
                             stopReason = event.delta.stop_reason;
                         }
+                        if (event.delta && (event.delta.stop_details != null || event.delta.category != null)) {
+                            const details = event.delta.stop_details;
+                            stopDetails = details && typeof details === 'object' && !Array.isArray(details)
+                                ? {
+                                    ...details,
+                                    ...(event.delta.category != null ? { category: event.delta.category } : {}),
+                                }
+                                : {
+                                    ...(details != null ? { value: details } : {}),
+                                    ...(event.delta.category != null ? { category: event.delta.category } : {}),
+                                };
+                        }
                         if (event.usage) {
                             usage.outputTokens = event.usage.output_tokens || 0;
                             usage.raw = { ...(usage.raw || {}), ...event.usage };
@@ -615,6 +628,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
             toolCalls: toolCalls.length ? toolCalls : undefined,
             usage,
             stopReason,
+            stopDetails,
             hasThinkingContent,
             contentBlockTypes: Array.from(contentBlockTypes),
             // Ordered extended-thinking blocks (verbatim thinking text +

package/src/runtime/agent/orchestrator/providers/media-normalization.mjs

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 const DEFAULT_IMAGE_MIME = 'image/png';
 
 function cleanMimeType(value) {
@@ -96,6 +98,9 @@ function contentParts(content) {
     if (content && typeof content === 'object' && Array.isArray(content.content)) {
         return content.content;
     }
+    if (content && typeof content === 'object'
+        && (imageUrlFromPart(content) || imageFileIdFromPart(content)
+            || imageFileUriFromPart(content) || geminiInlineInfo(content))) return [content];
     return null;
 }
 
@@ -108,9 +113,61 @@ function jsonFallbackFromPart(block) {
 }
 
 export function contentHasImage(content) {
+    return contentImageCount(content) > 0;
+}
+
+export function contentImageCount(content) {
+    return contentImageDescriptors(content).length;
+}
+
+function positiveDimension(...values) {
+    for (const value of values) {
+        const number = Number(value);
+        if (Number.isFinite(number) && number > 0) return number;
+    }
+    return null;
+}
+
+function imageIdentity(kind, value, mimeType = '') {
+    return createHash('sha256')
+        .update(`${kind}\0${mimeType}\0`)
+        .update(String(value || ''))
+        .digest('hex');
+}
+
+function imageDescriptor(part) {
+    if (!part || typeof part !== 'object') return null;
+    const info = imageInfo(part);
+    const inline = geminiInlineInfo(part);
+    const url = imageUrlFromPart(part);
+    const fileId = imageFileIdFromPart(part);
+    const fileUri = imageFileUriFromPart(part);
+    if (!info && !inline && !url && !fileId && !fileUri) return null;
+    const imageUrl = part.image_url && typeof part.image_url === 'object' ? part.image_url : null;
+    const source = part.source && typeof part.source === 'object' ? part.source : null;
+    const inlineData = part.inlineData || part.inline_data;
+    const dimensions = part.dimensions && typeof part.dimensions === 'object' ? part.dimensions : null;
+    const width = positiveDimension(part.width, dimensions?.width, imageUrl?.width, source?.width, inlineData?.width);
+    const height = positiveDimension(part.height, dimensions?.height, imageUrl?.height, source?.height, inlineData?.height);
+    const detail = String(part.detail ?? imageUrl?.detail ?? source?.detail ?? inlineData?.detail ?? 'auto').toLowerCase();
+    if (info || inline) {
+        const raw = info || inline;
+        return {
+            identity: imageIdentity('inline', raw.data, raw.mimeType),
+            width,
+            height,
+            detail,
+        };
+    }
+    if (fileId) return { identity: imageIdentity('file-id', fileId), width, height, detail };
+    if (fileUri) return { identity: imageIdentity('file-uri', fileUri.fileUri, fileUri.mimeType), width, height, detail };
+    return { identity: imageIdentity('url', url), width, height, detail };
+}
+
+export function contentImageDescriptors(content) {
     const parts = contentParts(content);
-    if (!parts) return false;
-    return parts.some((part) => !!imageUrlFromPart(part) || !!imageFileIdFromPart(part) || !!imageFileUriFromPart(part) || !!geminiInlineInfo(part));
+    if (!parts) return [];
+    return parts.map(imageDescriptor).filter(Boolean);
 }
 
 export function contentToText(content, fallback = '') {

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -145,6 +145,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     let lastUsage;
     let firstTurnUsage;
     let response;
+    let lastSendTools = tools;
     let contextOverflowRetryUsed = false;
     // Set when the hard iteration-cap break below fires. Consumed at the final
     // return to tag terminationReason='iteration_cap' so a worker that exhausts
@@ -281,6 +282,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     // the loop as an explicit empty termination instead.
     let _emptyNudgeStreak = 0;
     const EMPTY_NUDGE_MAX = 3;
+    let _refusalRetryUsed = false;
     let _maxOutputRecoveryCount = 0;
     const _maxOutputContentParts = [];
     // Claude Code parity: queued prompt/task notifications are attached after a
@@ -435,6 +437,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         const sendTools = _capFinalToolsDisabled
             ? tools
             : (forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools);
+        lastSendTools = sendTools;
         // Eager-dispatch queue: when the provider streams a tool-call event,
         // start read-only tools immediately so execution overlaps with the
         // remaining SSE parse. Writes and unknown tools wait until send()
@@ -572,6 +575,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     // additive — callers that ignore these fields keep working.
                     deltaCachedRead: response.usage.cachedTokens || 0,
                     deltaCacheWrite: response.usage.cacheWriteTokens || 0,
+                    sendTools,
                     ts: Date.now(),
                 });
             } catch { /* best-effort — never break the loop */ }
@@ -633,6 +637,19 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 };
                 break;
             }
+            if (!hasContent && stopReason === 'refusal') {
+                if (_refusalRetryUsed) {
+                    process.stderr.write(`[loop] safety-classifier refusal persisted after one context-changing retry (sess=${sessionId || 'unknown'}); ending loop as refusal termination.\n`);
+                    break;
+                }
+                _refusalRetryUsed = true;
+                messages.push({
+                    role: 'user',
+                    content: '[mixdog-runtime] The previous completion was refused by the provider safety classifier (stopReason=refusal). Do not repeat it. Complete your assigned output within policy by omitting or reframing disallowed content; if no compliant output is possible, briefly state the refusal.',
+                    meta: { source: 'refusal-recovery', attempt: 1 },
+                });
+                continue;
+            }
             if (!hasContent && !isHidden) {
                 _emptyNudgeStreak += 1;
                 if (_emptyNudgeStreak > EMPTY_NUDGE_MAX) {
@@ -751,6 +768,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         ...response,
         usage: lastUsage || response.usage,
         lastTurnUsage: response.usage,
+        lastSendTools,
         firstTurnUsage: firstTurnUsage || response.usage,
         iterations,
         toolCallsTotal,

package/src/runtime/agent/orchestrator/session/context-utils.mjs

@@ -1,6 +1,7 @@
 import { isOffloadedToolResultText } from './tool-result-offload.mjs';
 import { createHash } from 'node:crypto';
 import { isAgentOwner } from '../agent-owner.mjs';
+import { contentImageDescriptors, contentToText } from '../providers/media-normalization.mjs';
 
 // ---------------------------------------------------------------------------
 // Conservative, Unicode-aware token estimator.
@@ -26,6 +27,8 @@ function readSafetyMultiplier() {
     return 1.1;
 }
 const TOKEN_ESTIMATE_SAFETY_MULTIPLIER = readSafetyMultiplier();
+export const IMAGE_VISUAL_TOKEN_ALLOWANCE = 4_096;
+const IMAGE_TILE_TOKEN_ALLOWANCE = 512;
 
 // Per-code-point token-cost weight. Tuned to overcount, not match exactly.
 function codePointTokenWeight(cp) {
@@ -72,12 +75,59 @@ export function estimateTokens(text) {
     if (s.length === 0) return 0;
     let weighted = 0;
     for (const ch of s) weighted += codePointTokenWeight(ch.codePointAt(0));
+    // Encoded blobs, minified JSON and generated identifiers do not get the
+    // word/whitespace merges that make prose approach chars/4. Long printable
+    // ASCII runs are commonly 0.5-0.8 tokens/byte; retain a conservative floor
+    // for those runs without penalizing ordinary spaced prose.
+    let denseAsciiFloor = 0;
+    for (const match of s.matchAll(/[\x21-\x7e]{16,}/g)) {
+        denseAsciiFloor += match[0].length * 0.75;
+    }
+    const encodedWords = s.match(/\b(?=[A-Za-z0-9]{8,}\b)(?=[A-Za-z0-9]*[A-Za-z])(?=[A-Za-z0-9]*\d)[A-Za-z0-9]+\b/g) || [];
+    if (encodedWords.length >= 3) {
+        // Encoded/generated identifiers are often wrapped at short columns or
+        // separated by spaces. Their individual runs can stay below the long-
+        // run threshold while still receiving almost no prose-style BPE merges.
+        const encodedChars = encodedWords.reduce((sum, word) => sum + word.length, 0);
+        denseAsciiFloor = Math.max(
+            denseAsciiFloor,
+            (encodedChars * 0.75) + ((s.length - encodedChars) * 0.25),
+        );
+    }
+    const lines = s.split(/\r?\n/).filter(line => line.trim());
+    const nonWhitespace = s.match(/\S/g)?.length || 0;
+    const structural = s.match(/[\[\]{}":,=<>|\\]/g)?.length || 0;
+    const jsonLikeLines = lines.filter(line => /^\s*[\[{].*[\]}],?\s*$/.test(line)).length;
+    if (lines.length >= 3 && nonWhitespace > 0
+        && (jsonLikeLines >= Math.ceil(lines.length / 2) || structural / nonWhitespace >= 0.12)) {
+        // JSONL, compact tables and generated line protocols can consist
+        // entirely of short runs while still tokenizing like minified data.
+        denseAsciiFloor = Math.max(denseAsciiFloor, (nonWhitespace * 0.7) + ((s.length - nonWhitespace) * 0.25));
+    }
     const asciiFloor = s.length / 4; // never below the legacy chars/4 lower bound
-    return Math.ceil(Math.max(weighted, asciiFloor) * TOKEN_ESTIMATE_SAFETY_MULTIPLIER);
+    return Math.ceil(Math.max(weighted, asciiFloor, denseAsciiFloor) * TOKEN_ESTIMATE_SAFETY_MULTIPLIER);
+}
+
+function nativeBlocksEstimateText(value) {
+    const list = Array.isArray(value) ? value : [value];
+    return list.map((block) => {
+        const images = contentImageDescriptors(block);
+        if (images.length) {
+            return JSON.stringify(images.map(({ width, height, detail }) => ({
+                type: 'image', width, height, detail,
+            })));
+        }
+        try { return JSON.stringify(block); }
+        catch { return String(block ?? ''); }
+    }).join('\n');
 }
 export function messageEstimateText(m) {
     if (!m || typeof m !== 'object') return '';
-    let text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
+    // Multimodal image payloads remain on the live message for provider sends,
+    // but their base64/data-url JSON is not text and must not dominate local
+    // context estimates. Use the same media-aware text projection for every
+    // estimate consumer (live gauge, compaction fallback, and summaries).
+    let text = contentToText(m.content, '');
     if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
         try { text += `\n${JSON.stringify(m.toolCalls)}`; }
         catch { text += `\n[${m.toolCalls.length} tool calls]`; }
@@ -86,14 +136,47 @@ export function messageEstimateText(m) {
     // signature / redacted data) and are re-sent on tool-continuation turns, so
     // they consume real input tokens. Count them or trim/compact undercounts.
     if (m.role === 'assistant' && Array.isArray(m.thinkingBlocks) && m.thinkingBlocks.length) {
-        try { text += `\n${JSON.stringify(m.thinkingBlocks)}`; }
-        catch { text += `\n[${m.thinkingBlocks.length} thinking blocks]`; }
+        text += `\n${nativeBlocksEstimateText(m.thinkingBlocks)}`;
+    }
+    // Some provider adapters replay their native assistant representation
+    // instead of content/toolCalls. Project it through the media normalizer so
+    // text/tool metadata and opaque reasoning are counted without base64 image
+    // bytes dominating the estimate.
+    if (m.role === 'assistant' && Array.isArray(m.assistantBlocks) && m.assistantBlocks.length) {
+        text += `\n${nativeBlocksEstimateText(m.assistantBlocks)}`;
+    }
+    if (m.role === 'assistant' && Array.isArray(m.reasoningItems) && m.reasoningItems.length) {
+        text += `\n${nativeBlocksEstimateText(m.reasoningItems)}`;
     }
     if (m.role === 'tool' && m.toolCallId) text += `\n${m.toolCallId}`;
     return text;
 }
+function imageDescriptorAllowance(descriptor) {
+    if (descriptor.width && descriptor.height) {
+        const tiles = Math.ceil(descriptor.width / 512) * Math.ceil(descriptor.height / 512);
+        // Caller-supplied dimensions/detail are not uniformly preserved by all
+        // provider normalizers, so they may raise the allowance for a known
+        // multi-tile image but can never lower the conservative unknown-image
+        // fallback. This avoids trusting metadata the provider never sees.
+        return Math.max(IMAGE_VISUAL_TOKEN_ALLOWANCE, IMAGE_TILE_TOKEN_ALLOWANCE * (tiles + 1));
+    }
+    // Unknown-size auto/high images may be tiled by the provider. A single
+    // 1k allowance is optimistic for common screenshots and documents.
+    return IMAGE_VISUAL_TOKEN_ALLOWANCE;
+}
+function messageImageDescriptors(m) {
+    if (!m || typeof m !== 'object') return [];
+    return [
+        ...contentImageDescriptors(m.content),
+        ...(m.role === 'assistant' ? contentImageDescriptors(m.assistantBlocks) : []),
+    ];
+}
+function messageImageAllowance(m) {
+    if (!m || typeof m !== 'object') return 0;
+    return messageImageDescriptors(m).reduce((sum, descriptor) => sum + imageDescriptorAllowance(descriptor), 0);
+}
 export function estimateMessageTokens(m) {
-    return estimateTokens(messageEstimateText(m)) + 4;
+    return estimateTokens(messageEstimateText(m)) + messageImageAllowance(m) + 4;
 }
 export function estimateMessagesTokens(messages) {
     return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
@@ -112,28 +195,11 @@ const contextMessageMemo = new WeakMap();
 const contextTranscriptMemo = new WeakMap();
 
 function contextValueFingerprint(value) {
-    if (typeof value === 'string') return { value, entries: null };
-    if (Array.isArray(value)) return {
-        value,
-        entries: value.map(contextBlockFingerprint),
-    };
-    return value && typeof value === 'object'
-        ? { value, entries: [contextBlockFingerprint(value)] }
-        : { value, entries: null };
-}
-
-function contextBlockFingerprint(block) {
-    if (!block || typeof block !== 'object') return { value: block };
-    const fn = block.function;
     return {
-        value: block,
-        text: typeof block.text === 'string' ? block.text : null,
-        content: typeof block.content === 'string' ? block.content : null,
-        args: typeof block.args === 'string' ? block.args : null,
-        arguments: block.arguments,
-        input: typeof block.input === 'string' ? block.input : null,
-        function: fn,
-        functionArguments: typeof fn?.arguments === 'string' ? fn.arguments : null,
+        value,
+        snapshot: typeof value === 'string'
+            ? value
+            : `${nativeBlocksEstimateText(value)}\0${JSON.stringify(contentImageDescriptors(value))}`,
     };
 }
 
@@ -145,6 +211,7 @@ function contextMessageFingerprint(message) {
             toolCalls: contextValueFingerprint(null),
             thinkingBlocks: contextValueFingerprint(null),
             assistantBlocks: contextValueFingerprint(null),
+            reasoningItems: contextValueFingerprint(null),
             toolCallId: null,
         };
     }
@@ -154,30 +221,13 @@ function contextMessageFingerprint(message) {
         toolCalls: contextValueFingerprint(message.toolCalls),
         thinkingBlocks: contextValueFingerprint(message.thinkingBlocks),
         assistantBlocks: contextValueFingerprint(message.assistantBlocks),
+        reasoningItems: contextValueFingerprint(message.reasoningItems),
         toolCallId: message?.toolCallId || null,
     };
 }
 
 function sameContextValueFingerprint(a, b) {
-    if (!a || !b || a.value !== b.value) return false;
-    if (a.entries === null || b.entries === null) return a.entries === b.entries;
-    if (a.entries.length !== b.entries.length) return false;
-    for (let index = 0; index < a.entries.length; index += 1) {
-        if (!sameContextBlockFingerprint(a.entries[index], b.entries[index])) return false;
-    }
-    return true;
-}
-
-function sameContextBlockFingerprint(a, b) {
-    return !!a && !!b
-        && a.value === b.value
-        && a.text === b.text
-        && a.content === b.content
-        && a.args === b.args
-        && Object.is(a.arguments, b.arguments)
-        && a.input === b.input
-        && a.function === b.function
-        && a.functionArguments === b.functionArguments;
+    return !!a && !!b && a.value === b.value && a.snapshot === b.snapshot;
 }
 
 function sameContextMessageFingerprint(a, b) {
@@ -186,6 +236,7 @@ function sameContextMessageFingerprint(a, b) {
         && sameContextValueFingerprint(a.toolCalls, b.toolCalls)
         && sameContextValueFingerprint(a.thinkingBlocks, b.thinkingBlocks)
         && sameContextValueFingerprint(a.assistantBlocks, b.assistantBlocks)
+        && sameContextValueFingerprint(a.reasoningItems, b.reasoningItems)
         && a.toolCallId === b.toolCallId;
 }
 
@@ -197,7 +248,7 @@ function contextMessageContribution(message) {
     }
     const role = ['system', 'user', 'assistant', 'tool'].includes(fingerprint.role) ? fingerprint.role : 'other';
     const text = messageEstimateText(message);
-    const tokens = estimateTokens(text) + 4;
+    const tokens = estimateTokens(text) + messageImageAllowance(message) + 4;
     const contribution = {
         role,
         tokens,
@@ -511,7 +562,7 @@ export function summarizeContextMessages(messages) {
     if (!Array.isArray(messages)) return contextSummaryResult(emptyContextSummaryState(), 0);
     let cached = contextTranscriptMemo.get(messages);
     if (!cached || messages.length < cached.count) {
-        cached = { count: 0, contributions: [], state: emptyContextSummaryState() };
+        cached = { count: 0, contributions: [], state: emptyContextSummaryState(), revision: 0 };
         contextTranscriptMemo.set(messages, cached);
     }
     for (let index = 0; index < messages.length; index += 1) {
@@ -521,12 +572,42 @@ export function summarizeContextMessages(messages) {
         if (previous) applyContextMessageContribution(cached.state, previous, -1);
         cached.contributions[index] = contribution;
         applyContextMessageContribution(cached.state, contribution, 1);
+        cached.revision += 1;
     }
     cached.contributions.length = messages.length;
     cached.count = messages.length;
     return contextSummaryResult(cached.state, messages.length);
 }
 
+// A stable warm-cache generation for consumers that cache a derived view of
+// the whole transcript. summarizeContextMessages() must run first so mutations
+// to any entry, not merely the tail, advance the generation.
+export function contextMessagesRevision(messages) {
+    if (!Array.isArray(messages)) return 0;
+    summarizeContextMessages(messages);
+    return contextTranscriptMemo.get(messages)?.revision || 0;
+}
+
+// Hash only estimator/provider-visible projections. In particular, images
+// contribute their visual count but never their raw data-url/base64 bytes.
+export function contextMessagesSignature(messages, count = messages?.length) {
+    const list = Array.isArray(messages) ? messages : [];
+    const end = Math.max(0, Math.min(list.length, Number.isInteger(count) ? count : list.length));
+    const hash = createHash('sha256');
+    for (let index = 0; index < end; index += 1) {
+        const message = list[index];
+        hash.update(JSON.stringify([
+            message?.role || '',
+            message?.toolCallId || '',
+            messageEstimateText(message),
+            messageImageAllowance(message),
+            messageImageDescriptors(message),
+        ]));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+
 // Per-request overhead the provider injects that never appears in the
 // `messages` array: function-calling preamble + system-prompt framing the
 // provider wraps around the request. The chars/4 message estimate misses all
@@ -535,35 +616,13 @@ const REQUEST_OVERHEAD_TOKENS = 512;
 const toolSchemaTokenMemo = new WeakMap();
 const requestReserveTokenMemo = new WeakMap();
 
-function sameToolArrayEntries(cached, tools) {
-    if (!cached || cached.entries.length !== tools.length) return false;
-    for (let index = 0; index < tools.length; index += 1) {
-        const entry = cached.entries[index];
-        const tool = tools[index];
-        if (entry.tool !== tool
-            || entry.name !== tool?.name
-            || entry.description !== tool?.description
-            || entry.inputSchema !== tool?.inputSchema
-            || entry.input_schema !== tool?.input_schema
-            || entry.parameters !== tool?.parameters
-            || entry.schema !== tool?.schema) return false;
-    }
-    return true;
+function serializeToolSchemas(tools) {
+    try { return JSON.stringify(Array.isArray(tools) ? tools : []); }
+    catch { return (Array.isArray(tools) ? tools : []).map(t => String(t?.name ?? '')).join(''); }
 }
 
-function cacheToolArrayValue(tools, value) {
-    return {
-        entries: tools.map((tool) => ({
-            tool,
-            name: tool?.name,
-            description: tool?.description,
-            inputSchema: tool?.inputSchema,
-            input_schema: tool?.input_schema,
-            parameters: tool?.parameters,
-            schema: tool?.schema,
-        })),
-        value,
-    };
+export function toolSchemaSignature(tools) {
+    return createHash('sha256').update(serializeToolSchemas(tools)).digest('hex');
 }
 
 /**
@@ -576,13 +635,12 @@ function cacheToolArrayValue(tools, value) {
  */
 export function estimateToolSchemaTokens(tools) {
     if (!Array.isArray(tools) || tools.length === 0) return 0;
+    const signature = toolSchemaSignature(tools);
     const cached = toolSchemaTokenMemo.get(tools);
-    if (sameToolArrayEntries(cached, tools)) return cached.value;
-    let text = '';
-    try { text = JSON.stringify(tools); }
-    catch { text = tools.map(t => String(t?.name ?? '')).join(''); }
+    if (cached?.signature === signature) return cached.value;
+    const text = serializeToolSchemas(tools);
     const tokens = estimateTokens(text);
-    toolSchemaTokenMemo.set(tools, cacheToolArrayValue(tools, tokens));
+    toolSchemaTokenMemo.set(tools, { signature, value: tokens });
     return tokens;
 }
 
@@ -594,10 +652,11 @@ export function estimateToolSchemaTokens(tools) {
  */
 export function estimateRequestReserveTokens(tools) {
     if (!Array.isArray(tools)) return estimateToolSchemaTokens(tools) + REQUEST_OVERHEAD_TOKENS;
+    const signature = toolSchemaSignature(tools);
     const cached = requestReserveTokenMemo.get(tools);
-    if (sameToolArrayEntries(cached, tools)) return cached.value;
+    if (cached?.signature === signature) return cached.value;
     const reserve = estimateToolSchemaTokens(tools) + REQUEST_OVERHEAD_TOKENS;
-    requestReserveTokenMemo.set(tools, cacheToolArrayValue(tools, reserve));
+    requestReserveTokenMemo.set(tools, { signature, value: reserve });
     return reserve;
 }