@armadra/agent 0.7.2 → 0.7.4

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

@@ -67,7 +67,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

@@ -162,7 +162,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;

package/dist/ai/context.js

@@ -6,8 +6,9 @@
  *   得到 `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
  * - 中途节补丁（设计 §9.1「会话中途变化的上下文只追加」）：对话开始之后的 system 补丁不改写开头，
  *   渲染成 `<system-reminder>` 包裹的 user 消息按位置插回，开头与之前的消息逐字节不变；
- *   例外是补丁移除了工具——工具表本身已变、前缀必然失效，这时全部补丁照旧折回开头；
- * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ * - 工具表（[ME-B] D5）：对话开始前按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ *   开始之后声明冻结——移除不删声明、只在尾部提醒（执行层拒绝调用），已有名字不覆盖（加回只提醒
+ *   「available again」），新名字追加在末尾。开头与工具表在会话内只写一次；
  * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
  *
  * 支持「中途 system 消息」的协议（compat.supportsMidConvoSystemMessages）用
@@ -15,16 +16,27 @@
  * 渲染为文本、按位置插回对话。
  */
 export const IMAGE_OMITTED_TEXT = "[image omitted: the model does not accept image input]";
+/** 对话开始后移除工具：声明保留，尾部提醒（固定英文；执行层拒绝文案见 agent/tool-availability.ts）。 */
+export const toolRemovedReminder = (name) => `Tool "${name}" is no longer available in this session; calls to it are rejected.`;
+/** 移除后又加回（声明沿用首次版本）。 */
+export const toolRestoredReminder = (name) => `Tool "${name}" is available again.`;
 class SystemState {
     sections = new Map();
     tools = new Map();
-    apply(message) {
+    /** `started`：对话已开始——工具声明冻结（移除不删、已有名字不覆盖、新名字追加）。 */
+    apply(message, started = false) {
         for (const [name, value] of Object.entries(message.sections)) {
             if (value === null)
                 this.sections.delete(name);
             else
                 this.sections.set(name, value);
         }
+        if (started) {
+            for (const tool of message.toolsAdded ?? [])
+                if (!this.tools.has(tool.name))
+                    this.tools.set(tool.name, tool);
+            return;
+        }
         for (const name of message.toolsRemoved ?? [])
             this.tools.delete(name);
         for (const tool of message.toolsAdded ?? [])
@@ -62,7 +74,7 @@ export function normalizeContext(context, options) {
     const tools = new SystemState();
     const messages = [];
     const allowImages = allowsImages(options);
-    const fold = removesToolsMidway(context.messages);
+    const removed = new Set();
     let pending = [];
     const flush = () => {
         if (pending.length === 0)
@@ -76,42 +88,47 @@ export function normalizeContext(context, options) {
             messages.push(filterMessage(message, allowImages));
             continue;
         }
-        tools.apply(message);
-        if (fold || messages.length === 0) {
+        const started = messages.length > 0;
+        tools.apply(message, started);
+        if (!started) {
             head.apply(message);
             continue;
         }
-        const text = renderSystemUpdate(message);
+        const text = renderSystemUpdate(message, removed);
         if (text.length > 0)
             pending.push(text);
     }
     flush();
     return { ...head.snapshot(), tools: tools.snapshot().tools, messages };
 }
-/** 对话开始之后有补丁移除了工具（这时整段前缀必然失效，补丁全部折回开头）。 */
-function removesToolsMidway(transcript) {
-    let started = false;
-    for (const message of transcript) {
-        if (message.role !== "system")
-            started = true;
-        else if (started && (message.toolsRemoved?.length ?? 0) > 0)
-            return true;
-    }
-    return false;
-}
 /** 中途节补丁作为尾部上下文消息送达时的文本（固定英文，与界面语言无关）。 */
 export function systemReminderText(updates) {
     return (`<system-reminder>\n${updates.join("\n\n")}\n\n` +
-        "These updates replace the earlier versions of those system prompt sections.\n</system-reminder>");
+        "These updates replace the earlier versions of those system prompt sections; " +
+        "tool availability notes above are current.\n</system-reminder>");
 }
-/** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
-export function renderSystemUpdate(message) {
+/**
+ * 渲染一条中途 system 补丁的文本：节变更全文；移除的工具各一句提醒；`removed` 里的名字被加回时
+ * 一句「available again」（新工具的声明由请求工具表末尾体现，不另写）。`removed` 随之更新。
+ */
+export function renderSystemUpdate(message, removed) {
     const parts = [];
     for (const [name, value] of Object.entries(message.sections)) {
         parts.push(value === null
             ? `System prompt section "${name}" was removed.`
             : `System prompt section "${name}" was updated:\n\n${value}`);
     }
+    for (const tool of message.toolsAdded ?? []) {
+        if (!removed.delete(tool.name))
+            continue;
+        parts.push(toolRestoredReminder(tool.name));
+    }
+    for (const name of message.toolsRemoved ?? []) {
+        if (removed.has(name))
+            continue;
+        removed.add(name);
+        parts.push(toolRemovedReminder(name));
+    }
     return parts.join("\n\n");
 }
 export function normalizeContextInline(context, options) {
@@ -120,17 +137,19 @@ export function normalizeContextInline(context, options) {
     const messages = [];
     const systemUpdates = [];
     const allowImages = allowsImages(options);
+    const removed = new Set();
     for (const message of context.messages) {
         if (message.role !== "system") {
             messages.push(filterMessage(message, allowImages));
             continue;
         }
-        tools.apply(message);
-        if (messages.length === 0) {
+        const started = messages.length > 0;
+        tools.apply(message, started);
+        if (!started) {
             head.apply(message);
             continue;
         }
-        const text = renderSystemUpdate(message);
+        const text = renderSystemUpdate(message, removed);
         if (text.length > 0)
             systemUpdates.push({ beforeIndex: messages.length, text });
     }

package/dist/ai/fake/fake-provider.d.ts

@@ -4,11 +4,14 @@
  * `responses[n]` 产出文本 / 思考 / 工具调用 / 429 / 溢出 / 断流 / 延迟。
  *
  * 事件形状与真实协议完全一致（同一个 BlockTracker），契约测试对两条协议与 fake 跑同一套断言。
+ * [ME-C] 工具参数按 JSON 串分块喂给 BlockTracker，所以消息同样带 `rawArguments`；start 之前的错误
+ * 以 `HttpError` 抛出（状态 ≥ 400 时），脚本的 `error.retryAfterMs` 进失败消息的 `retryAfterMs`。
  *
  * 用法：
  * - 测试：`const fake = new FakeProvider([...])`，把 `fake.api` 注册进 ApiRegistry（或直接
  *   `fake.api.stream(...)`），`fake.calls` 记录每次调用的上下文与选项；
- * - CLI：`--provider fake`；`AMA_FAKE_SCRIPT=<path.json>` 指定脚本（首次调用时读取）。
+ * - CLI：`--provider fake`；`AMA_FAKE_SCRIPT=<path.json>` 指定脚本（首次调用时读取）。缺省实例
+ *   `keepCalls: false`：只计数、不留 `calls`（否则整个进程的转录都被它引用，内存测量多出几十 MB）。
  * - 录制（第三波 §2.4，bundle 级缓存测试）：`AMA_FAKE_RECORD=<file>` 时每次请求向文件追加一行
  *   JSON `{ index, purpose, model, system, tools, messagesCount }`——`system` 是折叠后的系统提示
  *   原文，`tools` 是发给供应商的工具表（按注册顺序），与真实协议请求体的前缀同口径。
@@ -31,6 +34,8 @@ export interface FakeRecordLine {
 export interface FakeProviderOptions {
     /** 录制文件路径（每次请求取一次；undefined = 不录）。 */
     recordFile?: string | (() => string | undefined);
+    /** false：只计数，不往 `calls` 里留上下文与选项（CLI 缺省实例）；缺省 true。 */
+    keepCalls?: boolean;
 }
 export declare const FAKE_MODELS: readonly Model[];
 export declare function fakeProviderData(): ProviderData;
@@ -47,6 +52,8 @@ export declare class FakeProvider {
     private readonly scriptLoader;
     private loaded;
     private readonly recordFile;
+    private readonly keepCalls;
+    private count;
     constructor(script?: FakeScript | FakeResponse[] | (() => FakeScript | undefined), options?: FakeProviderOptions);
     readonly api: ApiImplementation;
     get callCount(): number;