@armadra/agent 0.7.2 → 0.7.4

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,31 @@
+/**
+ * 请求体序列化（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)` 收到与原生相同的键）。
+ */
+/** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
+export declare const LARGE_STRING_BYTES: number;
+/** 与 `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;
+}
+/**
+ * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
+ * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
+ * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
+ * 同一时刻只多出一个片段的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ */
+export declare function jsonFetchBody(body: unknown): JsonFetchBody;

package/dist/ai/json-body.js

@@ -0,0 +1,208 @@
+/**
+ * 请求体序列化（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)` 收到与原生相同的键）。
+ */
+/** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
+export const LARGE_STRING_BYTES = 64 * 1024;
+/** 检查是否需要转义时每次交给原生的长度：结果是新生代里的小字符串，随即可回收。 */
+const CHECK_CHUNK = 16 * 1024;
+/**
+ * 大字符串无需转义、可原样写入：逐段让原生 `JSON.stringify` 判断（长度恰好多出两个引号即没有
+ * 任何转义）。引号、反斜杠、控制字符、孤立代理项都会让长度变化；成对代理项若恰被切在段界上
+ * 也会被判为需要转义——只会多走原生，不会错。实测比同义的正则快一倍多（原生的转义扫描是向量化的）。
+ * 每个大字符串每次序列化只查这一次。
+ */
+function isPlain(value) {
+    for (let i = 0; i < value.length; i += CHECK_CHUNK) {
+        const chunk = value.slice(i, i + CHECK_CHUNK);
+        if (JSON.stringify(chunk).length !== chunk.length + 2)
+            return false;
+    }
+    return true;
+}
+/** 结构遍历的深度上限：更深（或有环）时整棵子树交给原生，环由原生照常抛 TypeError。 */
+const MAX_DEPTH = 64;
+const isLargeString = (value) => typeof value === "string" && value.length >= LARGE_STRING_BYTES;
+/** 只遍历原型为 Object.prototype / null 的普通对象和数组，且自身与原型链上都没有 `toJSON`。 */
+function isContainer(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (typeof value.toJSON === "function")
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** 收集含大字符串的容器（片段路径只深入这些容器）；返回 `value` 本身是否含大字符串。 */
+function collectLarge(value, marked, depth) {
+    if (isLargeString(value))
+        return true;
+    if (depth >= MAX_DEPTH || !isContainer(value))
+        return false;
+    let found = false;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            if (collectLarge(value[i], marked, depth + 1))
+                found = true;
+        }
+    }
+    else {
+        for (const key of Object.keys(value)) {
+            if (collectLarge(value[key], marked, depth + 1))
+                found = true;
+        }
+    }
+    if (found)
+        marked.add(value);
+    return found;
+}
+/** 原生序列化 `holder[key] = value` 这一项的值；被原生跳过（undefined / 函数 / symbol）时 undefined。 */
+function nativeValue(key, value) {
+    if (typeof value !== "object" && typeof value !== "function" && typeof value !== "bigint") {
+        return JSON.stringify(value);
+    }
+    // 对象、函数与 bigint 可能有 toJSON(key)：放进单键容器，让原生以同一个键调用
+    const wrapped = JSON.stringify({ [key]: value });
+    if (wrapped === "{}")
+        return undefined;
+    return wrapped.slice(JSON.stringify(key).length + 2, -1);
+}
+/** 片段：已拼好的 JSON 文本与大字符串交替；连续的小文本先在字符串里累积。 */
+class Pieces {
+    parts = [];
+    pending = "";
+    text(chunk) {
+        this.pending += chunk;
+    }
+    /** 大字符串原样写入（引号进相邻的小片段）。 */
+    large(value) {
+        this.parts.push(`${this.pending}"`, value);
+        this.pending = '"';
+    }
+    finish() {
+        if (this.pending.length > 0)
+            this.parts.push(this.pending);
+        this.pending = "";
+        return this.parts;
+    }
+}
+/** 写一项的值；返回是否写了（对象里被原生跳过的属性不写）。数组里跳过的值写 `null`。 */
+function writeEntry(key, value, marked, out, prefix, depth) {
+    if (isLargeString(value)) {
+        if (isPlain(value)) {
+            out.text(prefix);
+            out.large(value);
+        }
+        else {
+            out.text(prefix + JSON.stringify(value)); // 需要转义：只有这一个字符串交给原生
+        }
+        return true;
+    }
+    // 深度与 collectLarge 一致；有环时越过上限交给原生，由它抛 TypeError
+    if (depth < MAX_DEPTH && isContainer(value) && marked.has(value)) {
+        out.text(prefix);
+        writeContainer(value, marked, out, depth);
+        return true;
+    }
+    const text = nativeValue(key, value);
+    if (text === undefined)
+        return false;
+    out.text(prefix + text);
+    return true;
+}
+function writeContainer(value, marked, out, depth) {
+    if (Array.isArray(value)) {
+        out.text("[");
+        for (let i = 0; i < value.length; i++) {
+            const prefix = i > 0 ? "," : "";
+            if (!writeEntry(String(i), value[i], marked, out, prefix, depth + 1))
+                out.text(`${prefix}null`);
+        }
+        out.text("]");
+        return;
+    }
+    out.text("{");
+    let first = true;
+    for (const key of Object.keys(value)) {
+        const prefix = `${first ? "" : ","}${JSON.stringify(key)}:`;
+        if (writeEntry(key, value[key], marked, out, prefix, depth + 1))
+            first = false;
+    }
+    out.text("}");
+}
+/**
+ * 含大字符串时按顺序给出各片段（拼起来就是 `JSON.stringify(body)`）与 UTF-8 总字节数；
+ * 不含时返回 undefined（调用方照旧走原生）。
+ */
+function jsonParts(body) {
+    const marked = new Set();
+    if (!collectLarge(body, marked, 0))
+        return undefined;
+    const out = new Pieces();
+    if (isLargeString(body)) {
+        if (!isPlain(body))
+            return undefined;
+        out.large(body);
+    }
+    else
+        writeContainer(body, marked, out, 0);
+    const parts = out.finish();
+    let length = 0;
+    for (const part of parts)
+        length += Buffer.byteLength(part, "utf8");
+    return { parts, length };
+}
+/** 与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同；大字符串不经中间字符串。 */
+export function serializeJsonBody(body) {
+    const split = jsonParts(body);
+    if (split === undefined)
+        return Buffer.from(JSON.stringify(body), "utf8");
+    // 一次分配、依次写入：不再有整份中间字符串，也不需要 Buffer.concat 的第二份拷贝
+    const buf = Buffer.allocUnsafe(split.length);
+    let offset = 0;
+    for (const part of split.parts)
+        offset += buf.write(part, offset, "utf8");
+    if (offset !== split.length) {
+        throw new Error(`serializeJsonBody: wrote ${offset} of ${split.length} bytes`);
+    }
+    return buf;
+}
+/**
+ * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
+ * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
+ * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
+ * 同一时刻只多出一个片段的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ */
+export function jsonFetchBody(body) {
+    const split = jsonParts(body);
+    if (split === undefined)
+        return { body: JSON.stringify(body) };
+    const { parts } = split;
+    let next = 0;
+    const stream = new ReadableStream({
+        pull(controller) {
+            const part = parts[next];
+            if (part === undefined) {
+                controller.close();
+                return;
+            }
+            parts[next++] = ""; // 发出即放手，片段（拼出来的小文本）可尽早回收
+            controller.enqueue(Buffer.from(part, "utf8"));
+        },
+        cancel() {
+            parts.length = 0;
+        },
+    });
+    return { body: stream, contentLength: split.length };
+}

package/dist/ai/overflow.js

@@ -13,6 +13,11 @@
 export const OVERFLOW_PATTERNS = [
     [/prompt is too long/i, "Anthropic: prompt is too long: N tokens > M maximum"],
     [/request_too_large/i, "Anthropic: 413 request_too_large"],
+    // [ME-C] 只有 max-tokens.ts 判定「可用输出 < 1024、不能收紧重发」时这条错误才会冒到会话层
+    [
+        /input length and `?max_tokens`? exceed context limit/i,
+        "Anthropic: input length and max_tokens exceed context limit: X + Y > Z",
+    ],
     [/exceeds the context window/i, "OpenAI: Your input exceeds the context window of this model"],
     [/maximum context length is \d+ tokens/i, "OpenAI / OpenRouter / DeepSeek"],
     [