@armadra/agent 0.7.3 → 0.7.5

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;

package/dist/ai/fake/fake-provider.js

@@ -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` 是发给供应商的工具表（按注册顺序），与真实协议请求体的前缀同口径。
@@ -17,6 +20,7 @@ import { appendFileSync } from "node:fs";
 import { AssistantEventStreamImpl } from "../event-stream.js";
 import { BlockTracker, ProviderStopError, createOutput, finishDone, finishError, } from "../apis/shared.js";
 import { contentText, normalizeContext } from "../context.js";
+import { HttpError } from "../http.js";
 import { describeFakeError, loadFakeScript, parseFakeScript, } from "./fake-script.js";
 export const FAKE_PROVIDER_ID = "fake";
 export const FAKE_API_ID = "fake";
@@ -100,6 +104,8 @@ export class FakeProvider {
     scriptLoader;
     loaded = false;
     recordFile;
+    keepCalls;
+    count = 0;
     constructor(script, options = {}) {
         if (typeof script === "function")
             this.scriptLoader = script;
@@ -107,13 +113,14 @@ export class FakeProvider {
             this.setScript(script);
         const record = options.recordFile;
         this.recordFile = typeof record === "function" ? record : () => record;
+        this.keepCalls = options.keepCalls !== false;
     }
     api = {
         id: FAKE_API_ID,
         stream: (model, context, options) => this.stream(model, context, options),
     };
     get callCount() {
-        return this.calls.length;
+        return this.count;
     }
     setScript(script) {
         this.script = parseFakeScript(script);
@@ -126,6 +133,7 @@ export class FakeProvider {
     }
     reset() {
         this.calls.length = 0;
+        this.count = 0;
     }
     ensureLoaded() {
         if (this.loaded)
@@ -151,9 +159,11 @@ export class FakeProvider {
         return undefined;
     }
     stream(model, context, options) {
-        const index = this.calls.length;
-        const { signal: _s, onPayload: _p, onResponse: _r, ...rest } = options;
-        this.calls.push({ index, model, context, options: rest });
+        const index = this.count++;
+        if (this.keepCalls) {
+            const { signal: _s, onPayload: _p, onResponse: _r, ...rest } = options;
+            this.calls.push({ index, model, context, options: rest });
+        }
         this.record(index, model, context, options);
         const response = this.responseFor(index) ?? {
             text: lastUserText(context) || "(no input)",
@@ -198,7 +208,9 @@ export class FakeProvider {
             const error = response.error ? describeFakeError(response.error) : undefined;
             if (error && response.error?.kind !== "disconnect") {
                 options.onResponse?.(error.status, new Headers());
-                throw new Error(error.message);
+                if (error.status < 400)
+                    throw new Error(error.message);
+                throw new HttpError(error.status, error.message, "", response.error?.retryAfterMs);
             }
             options.onResponse?.(200, new Headers({ "content-type": "text/event-stream" }));
             if (options.thinkingLevel)
@@ -278,5 +290,5 @@ export class FakeProvider {
 export const defaultFakeProvider = new FakeProvider(() => {
     const path = process.env[FAKE_SCRIPT_ENV];
     return path ? loadFakeScript(path) : undefined;
-}, { recordFile: () => process.env[FAKE_RECORD_ENV] || undefined });
+}, { recordFile: () => process.env[FAKE_RECORD_ENV] || undefined, keepCalls: false });
 export const fakeApi = defaultFakeProvider.api;

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

@@ -41,6 +41,8 @@ export interface FakeError {
     kind: FakeErrorKind;
     message?: string;
     status?: number;
+    /** [ME-C] 模拟 `Retry-After`（毫秒）：写进失败消息的 `retryAfterMs`。 */
+    retryAfterMs?: number;
 }
 export interface FakeResponse {
     /** 依次产出的块；与 `text` 简写二选一（都给时 text 在后）。 */

package/dist/ai/http.d.ts

@@ -5,9 +5,10 @@
  * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
  * 本模块不自行实现代理。
  *
- * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
- * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
- * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）管等响应头；
+ * `streamIdleTimeoutMs`（缺省 180 s，0 关闭）管流式读取期间两次收到数据之间的间隔（每收到一块字节
+ * 即重新计时，见 sse.ts）。[ME-C] D18 空闲超时抛 `IdleTimeoutError`，文案含 `idle timeout`，会话层按
+ * 可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
@@ -33,15 +34,22 @@ export declare class HttpError extends Error {
 export declare class RequestTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
-/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+/** 等响应头的空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
 export declare const DEFAULT_IDLE_TIMEOUT_MS = 300000;
-/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+/** 流中两块数据之间的空闲超时缺省值：与 `request.streamIdleTimeoutMs` 的缺省一致。 */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 180000;
+/** 请求选项里等响应头的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
 export declare function idleTimeoutOf(options: {
     idleTimeoutMs?: number | undefined;
 }): number | undefined;
+/** 请求选项里流中的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export declare function streamIdleTimeoutOf(options: {
+    streamIdleTimeoutMs?: number | undefined;
+}): number | undefined;
 /**
- * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
- * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ * 服务端在空闲上限内没有任何字节：`response` = 发出请求后迟迟没有响应头（`idleTimeoutMs`），
+ * `stream` = 流读到一半停住（`streamIdleTimeoutMs`）。文案含 `idle timeout`（重试分类据此判为可重试），
+ * 并点名对应的配置键与环境变量。
  */
 export declare class IdleTimeoutError extends Error {
     readonly idleTimeoutMs: number;
@@ -60,7 +68,7 @@ export interface PostOptions {
     body: unknown;
     signal: AbortSignal;
     timeoutMs?: number | undefined;
-    /** 等响应头的空闲上限（`timeoutMs` 未给时生效）；undefined 不限。 */
+    /** 等响应头的空闲上限（`timeoutMs` 未给时生效）；undefined 不限。流中的空闲见 `readSseEvents`。 */
     idleTimeoutMs?: number | undefined;
     onResponse?: ((status: number, headers: Headers) => void) | undefined;
 }
@@ -68,7 +76,7 @@ export interface PostOptions {
  * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
  * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
  * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
- * `readSseEvents` 的 `idleTimeoutMs` 控制。
+ * `readSseEvents` 的空闲上限（`streamIdleTimeoutOf`）控制。
  */
 export declare function postJson(url: string, options: PostOptions): Promise<Response>;
 /** undici 的 `fetch failed` 把真正原因藏在 cause 里；拼出来便于重试分类与排错。 */

package/dist/ai/http.js

@@ -5,13 +5,15 @@
  * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
  * 本模块不自行实现代理。
  *
- * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
- * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
- * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）管等响应头；
+ * `streamIdleTimeoutMs`（缺省 180 s，0 关闭）管流式读取期间两次收到数据之间的间隔（每收到一块字节
+ * 即重新计时，见 sse.ts）。[ME-C] D18 空闲超时抛 `IdleTimeoutError`，文案含 `idle timeout`，会话层按
+ * 可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
 import { AMA_VERSION } from "../version.js";
+import { jsonFetchBody } from "./json-body.js";
 /** 大小写不敏感地合并头；后者覆盖前者；值为 null 表示删除该头。键保留最后一次出现的写法。 */
 export function mergeHeaders(...sources) {
     const merged = new Map();
@@ -80,19 +82,26 @@ export class RequestTimeoutError extends Error {
         this.name = "RequestTimeoutError";
     }
 }
-/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+/** 等响应头的空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
 export const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
-/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+/** 流中两块数据之间的空闲超时缺省值：与 `request.streamIdleTimeoutMs` 的缺省一致。 */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 180_000;
+const positive = (value) => Number.isFinite(value) && value > 0 ? value : undefined;
+/** 请求选项里等响应头的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
 export function idleTimeoutOf(options) {
-    const value = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    return Number.isFinite(value) && value > 0 ? value : undefined;
+    return positive(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS);
+}
+/** 请求选项里流中的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export function streamIdleTimeoutOf(options) {
+    return positive(options.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS);
 }
 function formatDuration(ms) {
     return ms >= 1000 && ms % 1000 === 0 ? `${ms / 1000} s` : `${ms} ms`;
 }
 /**
- * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
- * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ * 服务端在空闲上限内没有任何字节：`response` = 发出请求后迟迟没有响应头（`idleTimeoutMs`），
+ * `stream` = 流读到一半停住（`streamIdleTimeoutMs`）。文案含 `idle timeout`（重试分类据此判为可重试），
+ * 并点名对应的配置键与环境变量。
  */
 export class IdleTimeoutError extends Error {
     idleTimeoutMs;
@@ -101,7 +110,10 @@ export class IdleTimeoutError extends Error {
         const what = phase === "response"
             ? `No response from the server within ${formatDuration(idleTimeoutMs)}`
             : `Stream stalled: no data from the server for ${formatDuration(idleTimeoutMs)}`;
-        super(`${what} (idle timeout; adjust with request.idleTimeoutMs or AMA_IDLE_TIMEOUT_MS)`);
+        const knob = phase === "response"
+            ? "request.idleTimeoutMs or AMA_IDLE_TIMEOUT_MS"
+            : "request.streamIdleTimeoutMs or AMA_STREAM_IDLE_TIMEOUT_MS";
+        super(`${what} (idle timeout; adjust with ${knob})`);
         this.name = "IdleTimeoutError";
         this.idleTimeoutMs = idleTimeoutMs;
         this.phase = phase;
@@ -171,11 +183,17 @@ function parseRetryAfter(headers) {
     const date = Date.parse(value);
     return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
+/** 流式请求体须带 `content-length`（不走 chunked，部分中转不收）；已有同名头时以算出的字节数为准。 */
+function withContentLength(headers, length) {
+    return length === undefined
+        ? headers
+        : mergeHeaders(headers, { "content-length": String(length) });
+}
 /**
  * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
  * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
  * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
- * `readSseEvents` 的 `idleTimeoutMs` 控制。
+ * `readSseEvents` 的空闲上限（`streamIdleTimeoutOf`）控制。
  */
 export async function postJson(url, options) {
     const explicit = options.timeoutMs !== undefined && options.timeoutMs > 0;
@@ -185,10 +203,12 @@ export async function postJson(url, options) {
     const signal = AbortSignal.any([options.signal, timer.signal]);
     let response;
     try {
+        const payload = jsonFetchBody(options.body);
         response = await fetch(url, {
             method: "POST",
-            headers: options.headers,
-            body: JSON.stringify(options.body),
+            headers: withContentLength(options.headers, payload.contentLength),
+            body: payload.body,
+            ...(payload.contentLength === undefined ? {} : { duplex: "half" }),
             signal,
         });
     }

package/dist/ai/image-intern.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 图片 base64 按内容哈希驻留（docs/memory-plan.md D5、§2.5）。
+ *
+ * `WeakRef` 的目标不能是字符串，所以驻留单元是 `ImageBlock`：表为 `Map<键, WeakRef<ImageBlock>>`，
+ * 键 = `mimeType` + base64 字符串的 sha256；`FinalizationRegistry` 在 block 被回收后清键。命中时返回
+ * 已驻留的 block，调用方把它放进内容数组，其中的 base64 字符串随之共享；未命中登记并返回入参。
+ * 驻留 block 只在仍被某条消息引用时存活，表本身不增加常驻。block 当作不可变值：没有任何代码就地改它。
+ *
+ * 哈希一律对 base64 字符串计算（base64 与原始字节一一对应），`read` / 附图与会话恢复的图片才能互相命中。
+ */
+import type { ImageBlock } from "./types.js";
+/**
+ * 会话条目的最小形状：ai 不 import session（docs/design.md §1.1），`SessionEntry[]` 可直接传入。
+ * 只有 `type === "message"` 且 `message.content` 为数组的条目里的 `image` 块参与驻留。
+ */
+export interface ImageCarrier {
+    readonly type: string;
+    readonly message?: object;
+}
+/** 内容哈希（小写 hex）；字符串按 UTF-8 计算。 */
+export declare function sha256Hex(data: Buffer | string): string;
+/**
+ * 返回与 `block` 内容相同的驻留 block；`hash` 是 `block.data`（base64 字符串）的 sha256，缺省时现算。
+ */
+export declare function internImage(block: ImageBlock, hash?: string): ImageBlock;
+/** 就地把会话条目里的图片 block 换成驻留 block，返回替换数（已是驻留对象的不计）。 */
+export declare function internSessionImages(entries: readonly ImageCarrier[]): number;
+/** 驻留表当前的键数（测试与诊断用；包括目标已回收、清理回调尚未运行的键）。 */
+export declare function internedImageCount(): number;

package/dist/ai/image-intern.js

@@ -0,0 +1,58 @@
+/**
+ * 图片 base64 按内容哈希驻留（docs/memory-plan.md D5、§2.5）。
+ *
+ * `WeakRef` 的目标不能是字符串，所以驻留单元是 `ImageBlock`：表为 `Map<键, WeakRef<ImageBlock>>`，
+ * 键 = `mimeType` + base64 字符串的 sha256；`FinalizationRegistry` 在 block 被回收后清键。命中时返回
+ * 已驻留的 block，调用方把它放进内容数组，其中的 base64 字符串随之共享；未命中登记并返回入参。
+ * 驻留 block 只在仍被某条消息引用时存活，表本身不增加常驻。block 当作不可变值：没有任何代码就地改它。
+ *
+ * 哈希一律对 base64 字符串计算（base64 与原始字节一一对应），`read` / 附图与会话恢复的图片才能互相命中。
+ */
+import { createHash } from "node:crypto";
+/** 内容哈希（小写 hex）；字符串按 UTF-8 计算。 */
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+const table = new Map();
+const registry = new FinalizationRegistry((key) => {
+    // 同一键可能已换成新 block：只在旧引用确已失效时删
+    if (table.get(key)?.deref() === undefined)
+        table.delete(key);
+});
+/**
+ * 返回与 `block` 内容相同的驻留 block；`hash` 是 `block.data`（base64 字符串）的 sha256，缺省时现算。
+ */
+export function internImage(block, hash) {
+    const key = `${block.mimeType}:${hash ?? sha256Hex(block.data)}`;
+    const existing = table.get(key)?.deref();
+    if (existing !== undefined && existing.data.length === block.data.length)
+        return existing;
+    table.set(key, new WeakRef(block));
+    registry.register(block, key);
+    return block;
+}
+/** 就地把会话条目里的图片 block 换成驻留 block，返回替换数（已是驻留对象的不计）。 */
+export function internSessionImages(entries) {
+    let replaced = 0;
+    for (const entry of entries) {
+        const message = entry.type === "message" ? entry.message : undefined;
+        const content = message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (let i = 0; i < content.length; i++) {
+            const block = content[i];
+            if (block?.type !== "image" || typeof block.data !== "string")
+                continue;
+            const interned = internImage(block);
+            if (interned !== block) {
+                content[i] = interned;
+                replaced++;
+            }
+        }
+    }
+    return replaced;
+}
+/** 驻留表当前的键数（测试与诊断用；包括目标已回收、清理回调尚未运行的键）。 */
+export function internedImageCount() {
+    return table.size;
+}

package/dist/ai/json-body.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 请求体序列化（docs/memory-plan.md D3、§2.3）。
+ *
+ * 带图请求体里 base64 占绝大部分字节；`JSON.stringify(body)` 会先拼出整份中间字符串，再由 fetch
+ * 编码成 UTF-8。这里先廉价扫一遍：没有 ≥ {@link LARGE_STRING_BYTES} 的字符串就照旧走原生；有就只沿
+ * 「普通对象 / 数组」结构拼片段——小子树仍交给原生 `JSON.stringify`，大字符串经检查无需转义时原样
+ * 作为一个片段。片段两种用法：`serializeJsonBody` 一次分配结果 Buffer 依次写入；`jsonFetchBody`
+ * （`postJson` 用）逐片段编码成流、声明总字节数，不在内存里留整份请求体。
+ *
+ * 结果与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同：自写部分只有结构（`{`、`,`、
+ * 键、`[`）与已验证无需转义的大字符串（需要转义的大字符串整个交给原生）；`toJSON`、`undefined` /
+ * 函数 / symbol 的跳过与 `null`、数字格式、转义全部由原生处理（带 `toJSON` 的值经单键容器序列化，
+ * 保证 `toJSON(key)` 收到与原生相同的键）。
+ *
+ * 图片由转换器包成 {@link LargeString}（`prefix + text`）：片段路径直接写转录里的原字符串，不经模板串
+ * 拼接后的扁平化；无需转义的结论与字节数按 ImageBlock 缓存，同一张图每进程只扫一次。流式发送时大片段
+ * 按 {@link STREAM_CHUNK_CHARS} 切块编码。
+ */
+/** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
+export declare const LARGE_STRING_BYTES: number;
+/** `isPlain` 的调用次数（测试用：同一块图片第二次序列化不应再扫）。 */
+export declare const plainScans: {
+    count: number;
+};
+/**
+ * 请求体里的大字符串叶子 `prefix + text`（data URL 或裸 base64），用来代替模板串拼接：拼接得到的
+ * cons string 在每次序列化时都会被扁平化成一份新的整图字符串。片段路径直接写 `prefix` 与 `text`
+ * （`text` 是转录里的原字符串，不拷贝）；`text` 无需转义的结论按 `key`（转录里身份稳定的 ImageBlock）
+ * 缓存，同一块每进程只扫一次。约定：同一 `key` 的 `text` 不变。其它遍历者看到的是一个带 `toJSON`
+ * 的对象，原生 `JSON.stringify` 得到相同字符串。由 {@link largeString} 构造。
+ */
+export declare class LargeString {
+    readonly prefix: string;
+    readonly key: object;
+    readonly text: string;
+    constructor(prefix: string, key: object, text: string);
+    toJSON(): string;
+}
+/**
+ * `prefix + text` 作为请求体的值：`text` 够大且 `prefix` 自身无需转义时给 {@link LargeString}，
+ * 否则就是拼好的字符串（小图与以前完全相同）。
+ */
+export declare function largeString(prefix: string, key: object, text: string): string | LargeString;
+/** 与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同；大字符串不经中间字符串。 */
+export declare function serializeJsonBody(body: unknown): Buffer;
+/** `postJson` 交给 fetch 的请求体。 */
+export interface JsonFetchBody {
+    body: string | ReadableStream<Uint8Array>;
+    /** 流式请求体的字节数：调用方须作为 `content-length` 头发出（不走 chunked）。 */
+    contentLength?: number;
+}
+/**
+ * 流式请求体每块最多编码的码元数：大片段（一整张图）按游标切片（V8 切片串不拷贝）逐块编码，
+ * 发送期间只多出一块的 UTF-8 字节，而不是一整张图。
+ */
+export declare const STREAM_CHUNK_CHARS: number;
+/**
+ * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
+ * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
+ * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
+ * 同一时刻只多出一块（≤ {@link STREAM_CHUNK_CHARS} 码元）的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ */
+export declare function jsonFetchBody(body: unknown): JsonFetchBody;