@armadra/agent 0.7.3 → 0.7.5

package/dist/ai/apis/max-tokens.js

@@ -0,0 +1,121 @@
+/**
+ * `max_tokens` 的主动收紧与被动修正（docs/model-efficiency-plan.md §1.9、D9）。[ME-C]
+ *
+ * - 主动收紧：窗口已知时 `max_tokens = min(请求值, max(MIN_OUTPUT_TOKENS, 窗口 − 估算输入 − 余量))`，
+ *   输入按请求体字符 / 4 估算（本模块自带，不依赖 compaction/）。预算型思考（`fixed`）不收紧：
+ *   预算由 max_tokens 推导，改它会让消息缓存失效。
+ * - 被动修正：端点以 400 拒收并说出上限（「max_tokens 范围」类文案）时，记入进程级 `maxTokensCaps`、
+ *   以上限重发一次；之后同一模型的请求直接用上限。Anthropic「输入 + max_tokens 超出上下文」只按这次
+ *   的输入算出可用值重发、不记上限；可用值不足 `MIN_OUTPUT_TOKENS` 判为溢出（overflow.ts 认得该文案）。
+ *   重发只发生在 `start` 之前，流契约不变（与 `postWithCacheFallback` 同模式，包在它外层）。
+ */
+import { HttpError, errorText } from "../http.js";
+import { postWithCacheFallback } from "./cache-params.js";
+/** 主动收紧的下限：再小就不如让请求原样发出、由被动修正或溢出处理接手。 */
+export const MIN_OUTPUT_TOKENS = 1024;
+/** 窗口里给估算误差留的余量。 */
+export const OUTPUT_HEADROOM_TOKENS = 2048;
+/** `${provider}/${model}` → 已知上限（被动修正时记入，之后的请求直接用）。 */
+export const maxTokensCaps = new Map();
+/** 主动收紧后的 max_tokens；`window` 未知或 `fixed`（预算型思考）时返回 requested。 */
+export function clampMaxTokens(requested, window, estimatedInput, fixed) {
+    if (fixed || window === undefined || !Number.isFinite(window) || window <= 0)
+        return requested;
+    const room = Math.floor(window - estimatedInput - OUTPUT_HEADROOM_TOKENS);
+    return Math.min(requested, Math.max(MIN_OUTPUT_TOKENS, room));
+}
+/** 请求体的输入 token 估算：JSON 字符数 / 4（CJK 偏低，由被动修正兜底）。 */
+export function estimateInputTokens(body) {
+    try {
+        return Math.ceil(JSON.stringify(body).length / 4);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 就地收紧 `holder[field]`（缺省 holder = body；Google 的 `generationConfig.maxOutputTokens`
+ * 传 holder）。字段不是数字时不动。
+ */
+export function clampRequestMaxTokens(body, field, window, fixed = false, holder = body) {
+    const requested = holder[field];
+    if (typeof requested !== "number" || fixed || window === undefined)
+        return;
+    holder[field] = clampMaxTokens(requested, window, estimateInputTokens(body), false);
+}
+/** Google `generationConfig.maxOutputTokens`；带正的思考预算时不收紧（预算按回答上限留白算出）。 */
+export function clampGoogleMaxTokens(body, window) {
+    const config = body["generationConfig"];
+    if (typeof config !== "object" || config === null)
+        return;
+    const thinking = config["thinkingConfig"];
+    const budget = typeof thinking === "object" && thinking !== null
+        ? thinking["thinkingBudget"]
+        : undefined;
+    const fixed = typeof budget === "number" && budget > 0;
+    clampRequestMaxTokens(body, "maxOutputTokens", window, fixed, config);
+}
+const NUM = "`?(\\d[\\d,_]*)`?";
+const toInt = (text) => Number((text ?? "").replace(/[,_]/g, ""));
+const RANGE = new RegExp(`range of \`?max_\\w*tokens\`?\\s*(?:should be|is|must be)?\\s*[[(]\\s*\\d+\\s*,\\s*${NUM}\\s*[\\])]`, "i");
+const LIMIT = new RegExp(`max_\\w*tokens\`?[^\\n]{0,200}?(?:must be|should be|less than or equal to|at most|<=)\\s*${NUM}`, "i");
+const CONTEXT_LIMIT = /input length and `?max_tokens`? exceed context limit:?\s*(\d+)\s*\+\s*(\d+)\s*>\s*(\d+)/i;
+function classify(error) {
+    if (error instanceof HttpError && error.status !== 400 && error.status !== 422)
+        return undefined;
+    const text = errorText(error);
+    const context = CONTEXT_LIMIT.exec(text);
+    if (context) {
+        const cap = toInt(context[3]) - toInt(context[1]);
+        return cap < MIN_OUTPUT_TOKENS ? { overflow: true } : { cap, transient: true };
+    }
+    const match = RANGE.exec(text) ?? LIMIT.exec(text);
+    if (!match)
+        return undefined;
+    const cap = toInt(match[1]);
+    return Number.isFinite(cap) && cap >= 1 ? { cap, transient: false } : undefined;
+}
+/** 400 文案里的上限；`{ cap }` 可重发，`{ overflow: true }` 判溢出，undefined 不是本类错误。 */
+export function parseMaxTokensRejection(error) {
+    const rejection = classify(error);
+    return rejection === undefined || "overflow" in rejection ? rejection : { cap: rejection.cap };
+}
+/** body[field] 超过 cap 时返回改小后的浅拷贝，否则原样返回。 */
+function withCap(body, field, cap) {
+    if (cap === undefined || typeof body !== "object" || body === null)
+        return body;
+    const value = body[field];
+    return typeof value === "number" && value > cap ? { ...body, [field]: cap } : body;
+}
+/** Anthropic 预算型思考：budget_tokens 必须小于 max_tokens，上限压不下时不重发。 */
+function budgetFits(body, cap) {
+    const thinking = body["thinking"];
+    if (typeof thinking !== "object" || thinking === null)
+        return true;
+    const budget = thinking["budget_tokens"];
+    return typeof budget !== "number" || budget < cap;
+}
+/** `postWithCacheFallback` 之外再包一层：max_tokens 超上限的 400 以收紧值重发一次（只在 `start` 之前）。 */
+export async function postWithMaxTokensFallback(model, url, options, field) {
+    const key = `${model.provider}/${model.id}`;
+    const body = withCap(options.body, field, maxTokensCaps.get(key));
+    try {
+        return await postWithCacheFallback(model, url, { ...options, body });
+    }
+    catch (error) {
+        if (options.signal.aborted || typeof body !== "object" || body === null)
+            throw error;
+        const rejection = classify(error);
+        const sent = body[field];
+        if (rejection === undefined || !("cap" in rejection) || typeof sent !== "number")
+            throw error;
+        if (rejection.cap >= sent || !budgetFits(body, rejection.cap))
+            throw error;
+        if (!rejection.transient)
+            maxTokensCaps.set(key, rejection.cap);
+        return postWithCacheFallback(model, url, {
+            ...options,
+            body: withCap(body, field, rejection.cap),
+        });
+    }
+}

package/dist/ai/apis/openai-completions.js

@@ -14,9 +14,10 @@
  *   内容推断。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, streamIdleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
-import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
+import { affinityHeaders, resolveCacheRetention } from "./cache-params.js";
+import { clampRequestMaxTokens, postWithMaxTokensFallback } from "./max-tokens.js";
 import { detectCompat } from "./openai-compat.js";
 import { REASONING_FIELDS, buildOpenAIRequest } from "./openai-request.js";
 import { BlockTracker, STREAM_ENDED_MESSAGE, ProviderStopError, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
@@ -183,16 +184,20 @@ async function run(stream, model, context, options) {
         if (request.providerThinkingLevel !== undefined) {
             tracker.output.providerThinkingLevel = request.providerThinkingLevel;
         }
+        const field = request.compat.maxTokensField;
+        clampRequestMaxTokens(request.body, field, model.contextWindow);
         const replaced = options.onPayload?.(request.body);
         const baseUrl = model.baseUrl ?? "https://api.openai.com/v1";
-        const response = await postWithCacheFallback(model, joinUrl(baseUrl, "/chat/completions"), {
+        const url = joinUrl(baseUrl, "/chat/completions");
+        const post = {
             headers: buildHeaders(model, options),
             body: replaced === undefined ? request.body : replaced,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
             idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
-        });
+        };
+        const response = await postWithMaxTokensFallback(model, url, post, field);
         stream.push({ type: "start", partial: tracker.output });
         const state = {
             text: undefined,
@@ -204,7 +209,7 @@ async function run(stream, model, context, options) {
             sawDone: false,
         };
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
+        for await (const sse of readSseEvents(body, options.signal, streamIdleTimeoutOf(options))) {
             const data = sse.data.trim();
             if (data === "")
                 continue;

package/dist/ai/apis/openai-request.js

@@ -19,12 +19,14 @@ import { contentText, normalizeContext, normalizeContextInline, sanitizeText, }
 import { DEFAULT_THINKING_BUDGETS, clampBudgetToAnswerRoom, clampThinkingLevel, mappedThinkingValue, } from "../thinking.js";
 import { cacheControlFor } from "./anthropic-request.js";
 import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
+import { largeString } from "../json-body.js";
 import { detectCompat } from "./openai-compat.js";
 /** 思考文本回放用的字段名；thinkingSignature 记录来源字段，回放时原样放回。 */
 export const REASONING_FIELDS = ["reasoning_content", "reasoning", "reasoning_text"];
 export const ASSISTANT_BRIDGE_TEXT = "Tool results received.";
 function imagePart(block) {
-    return { type: "image_url", image_url: { url: `data:${block.mimeType};base64,${block.data}` } };
+    const url = largeString(`data:${block.mimeType};base64,`, block, block.data);
+    return { type: "image_url", image_url: { url } };
 }
 function convertUser(message) {
     if (typeof message.content === "string") {
@@ -67,7 +69,7 @@ function convertAssistant(model, message, compat) {
         out["tool_calls"] = calls.map((call) => ({
             id: normalizeCallId(model, call.id),
             type: "function",
-            function: { name: call.name, arguments: JSON.stringify(call.arguments) },
+            function: { name: call.name, arguments: call.rawArguments ?? JSON.stringify(call.arguments) },
         }));
     }
     if (out["content"] === null && calls.length === 0)

package/dist/ai/apis/openai-responses-request.js

@@ -21,6 +21,7 @@
  * - [W6-O] compat `chatgptBackend`（ChatGPT 订阅后端）：最后经 chatgpt-backend.ts 按后端白名单改写。
  */
 import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { largeString } from "../json-body.js";
 import { clampThinkingLevel, mappedThinkingValue } from "../thinking.js";
 import { resolveCacheRetention, resolvePromptCacheCompat } from "./cache-params.js";
 import { transformChatGptBody } from "./chatgpt-backend.js";
@@ -110,7 +111,7 @@ function imagePart(block) {
     return {
         type: "input_image",
         detail: "auto",
-        image_url: `data:${block.mimeType};base64,${block.data}`,
+        image_url: largeString(`data:${block.mimeType};base64,`, block, block.data),
     };
 }
 function convertUser(message) {
@@ -162,7 +163,7 @@ function convertAssistant(model, message) {
                 ...(sameModel && itemId?.startsWith("fc") ? { id: itemId } : {}),
                 call_id: block.id,
                 name: block.name,
-                arguments: JSON.stringify(block.arguments),
+                arguments: block.rawArguments ?? JSON.stringify(block.arguments),
             });
         }
     }

package/dist/ai/apis/openai-responses.js

@@ -17,9 +17,10 @@
  *   错误映射与订阅用量见 chatgpt-backend.ts。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { HttpError, authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
+import { HttpError, authHeaders, describeErrorJson, idleTimeoutOf, streamIdleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
-import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
+import { affinityHeaders, resolveCacheRetention } from "./cache-params.js";
+import { clampRequestMaxTokens, postWithMaxTokensFallback } from "./max-tokens.js";
 import { chatgptHeaders, chatgptPrecheck, handleChatGptEvent, subscriptionModel, quotaOnResponse, recoverChatGptError, } from "./chatgpt-backend.js";
 import { buildResponsesRequest, detectResponsesCompat, encodeMessageSignature, } from "./openai-responses-request.js";
 import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
@@ -251,17 +252,20 @@ async function post(model, context, initial, tracker) {
         const chatgpt = compat.chatgptBackend !== undefined;
         if (chatgpt)
             chatgptPrecheck(model, compat, options.apiKey);
+        clampRequestMaxTokens(request.body, "max_output_tokens", model.contextWindow);
         const replaced = options.onPayload?.(request.body);
         const baseUrl = model.baseUrl ?? "https://api.openai.com/v1";
         try {
-            const response = await postWithCacheFallback(model, joinUrl(baseUrl, "/responses"), {
+            const url = joinUrl(baseUrl, "/responses");
+            const post = {
                 headers: buildHeaders(model, options, compat),
                 body: replaced === undefined ? request.body : replaced,
                 signal: options.signal,
                 timeoutMs: options.timeoutMs,
                 idleTimeoutMs: idleTimeoutOf(options),
                 onResponse: chatgpt ? quotaOnResponse(compat, options) : options.onResponse,
-            });
+            };
+            const response = await postWithMaxTokensFallback(model, url, post, "max_output_tokens");
             return { response, options, compat };
         }
         catch (error) {
@@ -292,7 +296,7 @@ async function run(stream, model, context, options) {
         };
         let finished = false;
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
+        for await (const sse of readSseEvents(body, options.signal, streamIdleTimeoutOf(options))) {
             const raw = sse.data.trim();
             if (raw === "" || raw === "[DONE]")
                 continue;

package/dist/ai/apis/shared.d.ts

@@ -5,7 +5,9 @@
  * - 每个 `*_start` 恰好对应一个 `*_end`；终止事件之前所有打开的块都会被关闭（出错 / 中止时也
  *   先关块再发 error，消费者不必处理悬空块）；
  * - `toolcall_end` 时 `toolCall.arguments` 一定是对象（容错解析，坏 JSON 退化为 `{}`）；
- * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象。
+ * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象；
+ * - [ME-C] 拼接出的参数串能严格 `JSON.parse` 成对象时原样记进 `rawArguments`，同协议回放时逐字节发回；
+ * - [ME-C] 失败响应带 `Retry-After` 时写 `retryAfterMs`（会话层退避取两者较大值）。
  */
 import type { AssistantEventStreamImpl } from "../event-stream.js";
 import type { AssistantMessage, Model, StopReason, StreamOptions, TextBlock, ThinkingBlock, ToolCallBlock } from "../types.js";

package/dist/ai/apis/shared.js

@@ -5,11 +5,13 @@
  * - 每个 `*_start` 恰好对应一个 `*_end`；终止事件之前所有打开的块都会被关闭（出错 / 中止时也
  *   先关块再发 error，消费者不必处理悬空块）；
  * - `toolcall_end` 时 `toolCall.arguments` 一定是对象（容错解析，坏 JSON 退化为 `{}`）；
- * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象。
+ * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象；
+ * - [ME-C] 拼接出的参数串能严格 `JSON.parse` 成对象时原样记进 `rawArguments`，同协议回放时逐字节发回；
+ * - [ME-C] 失败响应带 `Retry-After` 时写 `retryAfterMs`（会话层退避取两者较大值）。
  */
 import { AmaError } from "../../errors.js";
 import { finalizeUsage, emptyUsage } from "../cost.js";
-import { errorText, hasAuthHeader } from "../http.js";
+import { HttpError, errorText, hasAuthHeader } from "../http.js";
 import { parseToolArguments } from "../json-partial.js";
 export function createOutput(model) {
     return {
@@ -128,8 +130,11 @@ export class BlockTracker {
             this.stream.push({ type: "thinking_end", contentIndex: index, partial: this.output });
         }
         else {
-            if (entry.json.length > 0)
+            if (entry.json.length > 0) {
                 entry.block.arguments = parseToolArguments(entry.json);
+                if (isStrictObject(entry.json))
+                    entry.block.rawArguments = entry.json;
+            }
             this.stream.push({
                 type: "toolcall_end",
                 contentIndex: index,
@@ -150,6 +155,16 @@ export class BlockTracker {
         return this.output.content.length - 1;
     }
 }
+/** 严格 JSON 且是对象（数组 / 标量容错解析后是 `{}`，回放原串会与执行的参数不一致）。 */
+function isStrictObject(json) {
+    try {
+        const value = JSON.parse(json);
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    catch {
+        return false;
+    }
+}
 export const ABORTED_MESSAGE = "Request was aborted";
 export const STREAM_ENDED_MESSAGE = "Stream ended before completion";
 /** 正常结束：关块、算 usage / cost、发 done。 */
@@ -167,6 +182,9 @@ export function finishError(stream, tracker, model, error, signal) {
     const aborted = signal.aborted;
     output.stopReason = aborted ? "aborted" : "error";
     output.errorMessage = aborted ? ABORTED_MESSAGE : errorText(error);
+    if (!aborted && error instanceof HttpError && error.retryAfterMs !== undefined) {
+        output.retryAfterMs = error.retryAfterMs;
+    }
     finalizeUsage(model, output.usage);
     stream.push({ type: "error", reason: aborted ? "aborted" : "error", message: output });
 }

package/dist/ai/cache/fingerprint.d.ts

@@ -3,7 +3,8 @@
  *
  * - `system` = sha256(normalizeContext().systemPrompt) 前 64 bit；
  * - `tools` = sha256(JSON.stringify(工具表按名排序)) 前 64 bit；
- * - `model` = `${provider}/${id}` 原文。
+ * - `model` = `${provider}/${id}` 原文；
+ * - `sections` = 折叠后每个非空节的 hash16（[ME-B] D15：归因时说出哪一节变了）。
  * 纯函数、零请求；每次真实请求算一次（system + tools 通常 < 20 KB）。未命中归因时与上一条
  * 记录比对，说出「变了什么」。
  */
@@ -13,5 +14,7 @@ import type { PrefixFingerprint } from "./types.js";
 export declare function hash16(text: string): string;
 export declare function modelKey(model: Pick<Model, "provider" | "id" | "channel"> | ModelRef): string;
 export declare function fingerprintContext(context: TranscriptContext, model: Pick<Model, "provider" | "id">): PrefixFingerprint;
+/** 变化的节名：先按 `cur` 的节顺序列新增 / 改动的，再列 `prev` 里消失的；任一方没有按节指纹 → []。 */
+export declare function changedSections(prev: PrefixFingerprint, cur: PrefixFingerprint): string[];
 /** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
 export declare function fingerprintChange(prev: PrefixFingerprint, cur: PrefixFingerprint): "system" | "tools" | "model" | undefined;

package/dist/ai/cache/fingerprint.js

@@ -3,7 +3,8 @@
  *
  * - `system` = sha256(normalizeContext().systemPrompt) 前 64 bit；
  * - `tools` = sha256(JSON.stringify(工具表按名排序)) 前 64 bit；
- * - `model` = `${provider}/${id}` 原文。
+ * - `model` = `${provider}/${id}` 原文；
+ * - `sections` = 折叠后每个非空节的 hash16（[ME-B] D15：归因时说出哪一节变了）。
  * 纯函数、零请求；每次真实请求算一次（system + tools 通常 < 20 KB）。未命中归因时与上一条
  * 记录比对，说出「变了什么」。
  */
@@ -21,12 +22,28 @@ function sortedTools(tools) {
 }
 export function fingerprintContext(context, model) {
     const normalized = normalizeContext(context);
+    const sections = {};
+    for (const section of normalized.systemSections)
+        sections[section.name] = hash16(section.text);
     return {
         system: hash16(normalized.systemPrompt),
         tools: hash16(JSON.stringify(sortedTools(normalized.tools))),
         model: modelKey(model),
+        sections,
     };
 }
+/** 变化的节名：先按 `cur` 的节顺序列新增 / 改动的，再列 `prev` 里消失的；任一方没有按节指纹 → []。 */
+export function changedSections(prev, cur) {
+    if (prev.sections === undefined || cur.sections === undefined)
+        return [];
+    const before = prev.sections;
+    const after = cur.sections;
+    const changed = Object.keys(after).filter((name) => before[name] !== after[name]);
+    for (const name of Object.keys(before))
+        if (!(name in after))
+            changed.push(name);
+    return changed;
+}
 /** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
 export function fingerprintChange(prev, cur) {
     if (prev.system !== cur.system)

package/dist/ai/cache/miss.d.ts

@@ -10,7 +10,8 @@
  * 4. 成本：用本条实付反推——`(cost.input + cost.cacheWrite) / (input + cacheWrite)` 减去读价
  *    （本条有读用实付，否则用目录价）；无价格 → `missedCost` 缺省。
  * 5. 重置点（压缩 / 分支摘要 / 档一裁剪之后的首个请求）由调用方清空 prev；模型切换不豁免。
- * 6. 归因：指纹 system / tools 变 → `prefix_changed`；模型变 → `model_changed`；
+ * 6. 归因：指纹 system / tools 变 → `prefix_changed`（system 变时 `detail` 带变化的节名，如
+ *    `system:hooks,memory`，[ME-B] D15）；模型变 → `model_changed`；
  *    `idleMs > ttl`（无承诺 TTL 的隐式缓存按 600 s）→ `idle`；task 运行占间隔 ≥ 80% →
  *    `subtask`；其余 → `evicted`。
  */

package/dist/ai/cache/miss.js

@@ -10,11 +10,12 @@
  * 4. 成本：用本条实付反推——`(cost.input + cost.cacheWrite) / (input + cacheWrite)` 减去读价
  *    （本条有读用实付，否则用目录价）；无价格 → `missedCost` 缺省。
  * 5. 重置点（压缩 / 分支摘要 / 档一裁剪之后的首个请求）由调用方清空 prev；模型切换不豁免。
- * 6. 归因：指纹 system / tools 变 → `prefix_changed`；模型变 → `model_changed`；
+ * 6. 归因：指纹 system / tools 变 → `prefix_changed`（system 变时 `detail` 带变化的节名，如
+ *    `system:hooks,memory`，[ME-B] D15）；模型变 → `model_changed`；
  *    `idleMs > ttl`（无承诺 TTL 的隐式缓存按 600 s）→ `idle`；task 运行占间隔 ≥ 80% →
  *    `subtask`；其余 → `evicted`。
  */
-import { fingerprintChange } from "./fingerprint.js";
+import { changedSections, fingerprintChange } from "./fingerprint.js";
 /** 无承诺 TTL 的端点（隐式缓存）按 10 分钟估。 */
 export const IMPLICIT_CACHE_TTL_MS = 600_000;
 /** 没有目录 `minTokens` 时的最小可缓存长度与噪声下限。 */
@@ -76,10 +77,15 @@ export function detectMiss(prev, cur, ttlMs, options = {}) {
     if (cost !== undefined)
         miss.missedCost = cost;
     const change = fingerprintChange(prev.fingerprint, cur.fingerprint);
-    if (change === "system" || change === "tools") {
+    if (change === "tools") {
         miss.reason = "prefix_changed";
         miss.detail = change;
     }
+    else if (change === "system") {
+        miss.reason = "prefix_changed";
+        const names = changedSections(prev.fingerprint, cur.fingerprint);
+        miss.detail = names.length > 0 ? `system:${names.join(",")}` : "system";
+    }
     else if (change === "model")
         miss.reason = "model_changed";
     else if (idleMs > (ttlMs ?? IMPLICIT_CACHE_TTL_MS))

package/dist/ai/cache/reporting.js

@@ -64,7 +64,11 @@ export class CacheReportingTracker {
         };
         this.endpoints.set(key, entry);
         const last = entry.last;
-        entry.last = record;
+        entry.last = {
+            at: record.at,
+            promptTokens: record.promptTokens,
+            fingerprint: record.fingerprint,
+        };
         const { cacheRead, cacheWrite, cacheReported } = record.usage;
         if (cacheRead > 0 && Number.isInteger(cacheRead)) {
             entry.divisor = gcd(entry.divisor, cacheRead);

package/dist/ai/cache/types.d.ts

@@ -18,6 +18,8 @@ export interface PrefixFingerprint {
     tools: string;
     /** `${provider}/${id}`（原文，不哈希）。 */
     model: string;
+    /** 节名 → hash16，归因时说出哪一节变了。 */
+    sections?: Record<string, string>;
 }
 /** 每次真实请求在会话层记一条（内存，不落盘）。 */
 export interface RequestRecord {
@@ -36,6 +38,12 @@ export interface RequestRecord {
     contextRef: TranscriptContext;
     options: Omit<StreamOptions, "signal">;
 }
+/** [M-A] 端点上一条可比请求的摘要；只存比较需要的字段，不持有转录与回调。 */
+export interface LastRequest {
+    at: number;
+    promptTokens: number;
+    fingerprint: PrefixFingerprint;
+}
 /** 「供应商不报缓存」三态（§1.6）；按 `(provider, baseUrl 主机名, model)` 维护。 */
 export type CacheReporting = "unknown" | "reported" | "silent";
 /** 未命中原因（§1.5 第 6 步的归因顺序）。 */
@@ -47,8 +55,8 @@ export interface CacheMiss {
     /** 重计费金额（美元）；模型无价格时缺省（显示 `$?`）。 */
     missedCost?: number;
     reason: CacheMissReason;
-    /** `prefix_changed` 时哪一段变了。 */
-    detail?: "system" | "tools";
+    /** `prefix_changed` 时哪一段变了；[ME-B] system 变时带节名：`system:hooks,memory`。 */
+    detail?: "system" | "tools" | `system:${string}`;
     /** 与上一条可比请求的间隔。 */
     idleMs: number;
 }

package/dist/ai/cache/warmer.d.ts

@@ -14,7 +14,7 @@
  * - `pause()`：真实请求发出时静默挂起（新请求本身就刷新了缓存）；`cancel()` 同时丢弃记录。
  * 只有已排期之后的异常停止（截止、上限、零命中、过期、否决、失败）回调 `onStopped`。
  */
-import type { AssistantMessage, Model, StreamOptions } from "../types.js";
+import type { Api, AssistantMessage, Model, StreamOptions } from "../types.js";
 import type { CacheReporting, RequestRecord, WarmDecision, WarmerStatus, WarmingMode, WarmingPhase } from "./types.js";
 export declare const WARM_MIN_TTL_MS = 10000;
 export declare const WARM_STREAMING_CAP_MS: number;
@@ -42,6 +42,11 @@ export interface WarmerDeps {
     onScheduled?(nextWarmAt: number): void;
     onStopped(reason: string): void;
 }
+/**
+ * 保温重放的输出上限（[ME-B] D17）：Responses 的 `max_output_tokens` 下限是 16，其余协议 1。
+ * 官方下限无法实测，按文档取值；中转同样适用。
+ */
+export declare function warmReplayMaxTokens(api: Api): number;
 export declare function warmDelay(ttlMs: number): number;
 export interface ReplayCheck {
     model: Pick<Model, "api" | "reasoning" | "compat">;

package/dist/ai/cache/warmer.js

@@ -30,6 +30,13 @@ export const REAL_TIMERS = {
         clearTimeout(handle);
     },
 };
+/**
+ * 保温重放的输出上限（[ME-B] D17）：Responses 的 `max_output_tokens` 下限是 16，其余协议 1。
+ * 官方下限无法实测，按文档取值；中转同样适用。
+ */
+export function warmReplayMaxTokens(api) {
+    return api === "openai-responses" ? 16 : 1;
+}
 export function warmDelay(ttlMs) {
     return Math.max(1000, Math.floor(Math.min(0.9 * ttlMs, ttlMs - 10_000)));
 }

package/dist/ai/context.d.ts

@@ -6,8 +6,9 @@
  *   得到 `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
  * - 中途节补丁（设计 §9.1「会话中途变化的上下文只追加」）：对话开始之后的 system 补丁不改写开头，
  *   渲染成 `<system-reminder>` 包裹的 user 消息按位置插回，开头与之前的消息逐字节不变；
- *   例外是补丁移除了工具——工具表本身已变、前缀必然失效，这时全部补丁照旧折回开头；
- * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ * - 工具表（[ME-B] D5）：对话开始前按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ *   开始之后声明冻结——移除不删声明、只在尾部提醒（执行层拒绝调用），已有名字不覆盖（加回只提醒
+ *   「available again」），新名字追加在末尾。开头与工具表在会话内只写一次；
  * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
  *
  * 支持「中途 system 消息」的协议（compat.supportsMidConvoSystemMessages）用
@@ -20,11 +21,18 @@ export interface NormalizeOptions {
     model?: Pick<Model, "input"> | undefined;
 }
 export declare const IMAGE_OMITTED_TEXT = "[image omitted: the model does not accept image input]";
+/** 对话开始后移除工具：声明保留，尾部提醒（固定英文；执行层拒绝文案见 agent/tool-availability.ts）。 */
+export declare const toolRemovedReminder: (name: string) => string;
+/** 移除后又加回（声明沿用首次版本）。 */
+export declare const toolRestoredReminder: (name: string) => string;
 export declare function normalizeContext(context: TranscriptContext, options?: NormalizeOptions): NormalizedContext;
 /** 中途节补丁作为尾部上下文消息送达时的文本（固定英文，与界面语言无关）。 */
 export declare function systemReminderText(updates: readonly string[]): string;
-/** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
-export declare function renderSystemUpdate(message: SystemMessage): string;
+/**
+ * 渲染一条中途 system 补丁的文本：节变更全文；移除的工具各一句提醒；`removed` 里的名字被加回时
+ * 一句「available again」（新工具的声明由请求工具表末尾体现，不另写）。`removed` 随之更新。
+ */
+export declare function renderSystemUpdate(message: SystemMessage, removed: Set<string>): string;
 export interface InlineSystemUpdate {
     /** 插在 `messages[beforeIndex]` 之前；等于 messages.length 表示放在末尾。 */
     beforeIndex: number;