@armadra/agent 0.7.2 → 0.7.4

package/dist/agent/subagent-fork.js

@@ -0,0 +1,87 @@
+/**
+ * fork 式子 Agent（docs/model-efficiency-plan.md §2.1，D1–D3）。[ME-A]
+ *
+ * - fork 点 = 发出本次 `task` 调用的那条 assistant **之前一条**条目（= 父会话上一次真实请求的转录）；
+ *   同一条 assistant 里并行的多个 fork 任务共享同一个 fork 点。
+ * - `forkPlan`：满足条件时用 `SessionManager.fork(entryId, { head })` 复制分支，`head` 是
+ *   `custom{ama.task, context:"fork", forkedFrom}`（子会话首条仍是 `ama.task`）；否则给出回落原因：
+ *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `FORK_MAX_CONTEXT_RATIO` ×
+ *  （窗口 − reserveTokens）、找不到发起调用的 assistant。续聊与 resume 不经过这里（照原文件重开）。
+ * - `forkBrief`：角色说明 + 任务合成一条 user 消息（固定英文），追加在继承的历史之后；子会话不写
+ *   `role` 节，工具表与父逐字节相同，类型限制的工具在执行层拒绝（`unavailableTools`）。
+ */
+import { DEFAULT_COMPACTION_SETTINGS } from "./session-compaction.js";
+/** 父上一次请求的输入 token 超过（子模型窗口 − reserveTokens）的这个比例时回落 fresh。 */
+export const FORK_MAX_CONTEXT_RATIO = 0.5;
+const TASK_CUSTOM_TYPE = "ama.task";
+/** 请求的上下文模式：调用参数 > 类型 frontmatter > `fresh`。 */
+export function requestedContext(request, agent) {
+    return request.context ?? agent.context ?? "fresh";
+}
+/** 父分支里发出 `parentToolCallId` 的 assistant 之前一条条目的 id；找不到（或它是首条）返回 undefined。 */
+export function forkPoint(branch, parentToolCallId) {
+    const index = branch.findIndex((entry) => entry.type === "message" &&
+        entry.message.role === "assistant" &&
+        entry.message.content.some((block) => block.type === "toolCall" && block.id === parentToolCallId));
+    return index > 0 ? branch[index - 1]?.id : undefined;
+}
+/**
+ * D3 的回落条件依次检查，全部通过才复制分支（复制即落盘：父有文件时子会话文件立即写出）。
+ * `model` / `thinking` 是子会话按类型与参数解析出的值。
+ */
+export function forkPlan(parent, spec, model, thinking) {
+    const base = parent.childBase();
+    if (model.provider !== base.model.provider || model.id !== base.model.id)
+        return { fallback: `model ${model.provider}/${model.id} differs from the parent` };
+    if (thinking !== (base.thinkingLevel ?? "off"))
+        return { fallback: `thinking level ${thinking} differs from the parent` };
+    const last = parent.cache?.lastTurn;
+    if (last === undefined)
+        return { fallback: "the parent has not sent a request yet" };
+    const reserve = parent.options.compaction?.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens;
+    const window = model.contextWindow;
+    const limit = window === undefined ? Infinity : FORK_MAX_CONTEXT_RATIO * Math.max(0, window - reserve);
+    if (last.promptTokens > limit)
+        return { fallback: `parent context ${last.promptTokens} tokens exceeds ${Math.floor(limit)}` };
+    const forkedFrom = forkPoint(parent.manager.branch(), spec.request.parentToolCallId);
+    if (forkedFrom === undefined)
+        return { fallback: "the task call was not found in the parent transcript" };
+    const parentSession = parent.manager.file();
+    const manager = parent.manager.fork(forkedFrom, {
+        cwd: spec.cwd,
+        head: {
+            type: "custom",
+            customType: TASK_CUSTOM_TYPE,
+            data: {
+                taskId: spec.taskId,
+                agent: spec.agent.name,
+                parentToolCallId: spec.request.parentToolCallId,
+                description: spec.request.description,
+                parentSession,
+                context: "fork",
+                forkedFrom,
+            },
+        },
+    });
+    return { manager, forkedFrom };
+}
+/** fork 子会话的首条 user 消息（固定英文，发给模型）。 */
+export function forkBrief(input) {
+    const lines = [
+        "<task>",
+        "You are a sub-agent forked from the conversation above at this point. The main agent cannot " +
+            "see your work, only your final reply; do not delegate further. Requests above were for the " +
+            "main agent: do only this task. Instructions in this block take precedence over earlier " +
+            "plans or reminders above.",
+    ];
+    if (input.worktree !== undefined)
+        lines.push(`Working directory for this task: ${input.worktree.cwd}. Relative paths in the ` +
+            `conversation above refer to ${input.worktree.parentCwd}.`);
+    if (input.unavailable.length > 0)
+        lines.push(`Tools not available to you: ${input.unavailable.join(", ")}. Calls to them are rejected.`);
+    const role = input.role.trim();
+    if (role !== "")
+        lines.push(`<role>\n${role}\n</role>`);
+    lines.push(`<instructions>\n${input.prompt}\n</instructions>`, "Complete the task, then end with a concise report: what you did, key findings, files changed (if any).", "</task>");
+    return lines.join("\n");
+}

package/dist/agent/subagent-registry.d.ts

@@ -7,7 +7,7 @@
  *   宿主，经 `env.runners`）；同一 `task(agent=…)` 入口；
  * - 并发池（`subagents.maxConcurrent`，缺省 4）+ 排队上限（`maxPending`，缺省 16，超出报错不要重试）；
  * - 前台（等结果）/ 后台（立即返回 taskId，完成后 `<task-notification>` 走父会话 followUp 队列）；
- * - `taskId` 续聊：句柄保留 16 个（LRU，释放的只是内存，JSONL 永在），被释放或 resume 后按会话
+ * - `taskId` 续聊：句柄保留 4 个（`subagents.retainSessions`，LRU，释放的只是内存，JSONL 永在），被释放或 resume 后按会话
  *   文件 / 外部会话 id 重新接上；
  * - 结果 > 50 KB 保留头尾并全文落 `outputs/`；轮数耗尽加说明；worktree 隔离；
  * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
@@ -26,7 +26,7 @@ import { type DirectReply } from "./subagent-direct.js";
 import { type BackgroundReason } from "./subagent-background.js";
 export declare const DEFAULT_SUBAGENT_CONCURRENCY = 4;
 export declare const DEFAULT_MAX_PENDING = 16;
-export declare const DEFAULT_RETAINED = 16;
+export declare const DEFAULT_RETAINED = 4;
 export { SubagentPool, TASK_CUSTOM_TYPE, type AmaRunnerSpec, type TaskHandle };
 export type { BackgroundReason };
 export type AmaRunnerFactory = (spec: AmaRunnerSpec) => SubagentRunner;

package/dist/agent/subagent-registry.js

@@ -7,7 +7,7 @@
  *   宿主，经 `env.runners`）；同一 `task(agent=…)` 入口；
  * - 并发池（`subagents.maxConcurrent`，缺省 4）+ 排队上限（`maxPending`，缺省 16，超出报错不要重试）；
  * - 前台（等结果）/ 后台（立即返回 taskId，完成后 `<task-notification>` 走父会话 followUp 队列）；
- * - `taskId` 续聊：句柄保留 16 个（LRU，释放的只是内存，JSONL 永在），被释放或 resume 后按会话
+ * - `taskId` 续聊：句柄保留 4 个（`subagents.retainSessions`，LRU，释放的只是内存，JSONL 永在），被释放或 resume 后按会话
  *   文件 / 外部会话 id 重新接上；
  * - 结果 > 50 KB 保留头尾并全文落 `outputs/`；轮数耗尽加说明；worktree 隔离；
  * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
@@ -30,7 +30,7 @@ import { directMessage, drainDirect, liveOf } from "./subagent-direct.js";
 import { TaskNotifier, WaitDetach, backgroundRecords, blockingTasks, foregroundWaiter, settleTasks, startedResult, waitForTask, } from "./subagent-background.js";
 export const DEFAULT_SUBAGENT_CONCURRENCY = 4;
 export const DEFAULT_MAX_PENDING = 16;
-export const DEFAULT_RETAINED = 16;
+export const DEFAULT_RETAINED = 4;
 export { SubagentPool, TASK_CUSTOM_TYPE };
 const registries = new Map();
 /** RPC `get_tasks` / `/tasks`：会话 id → 注册表视图（没有任务时 undefined）。 */

package/dist/agent/tool-availability.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 工具可用性的固定英文文案（docs/model-efficiency-plan.md §1.4、D5）：执行层拒绝与尾部提醒共用，
+ * 发给模型，两种界面语言下逐字节相同。[ME-C0]
+ * [ME-B] 两条提醒由 `ai/context.ts` 渲染（ai 不 import agent），定义移到那里、这里再导出。
+ */
+export { toolRemovedReminder, toolRestoredReminder } from "../ai/context.js";
+/** 执行层拒绝：工具不在本会话可用（未注册，或在 `unavailableTools` 里）。 */
+export declare const toolUnavailableText: (name: string) => string;

package/dist/agent/tool-availability.js

@@ -0,0 +1,8 @@
+/**
+ * 工具可用性的固定英文文案（docs/model-efficiency-plan.md §1.4、D5）：执行层拒绝与尾部提醒共用，
+ * 发给模型，两种界面语言下逐字节相同。[ME-C0]
+ * [ME-B] 两条提醒由 `ai/context.ts` 渲染（ai 不 import agent），定义移到那里、这里再导出。
+ */
+export { toolRemovedReminder, toolRestoredReminder } from "../ai/context.js";
+/** 执行层拒绝：工具不在本会话可用（未注册，或在 `unavailableTools` 里）。 */
+export const toolUnavailableText = (name) => `Tool "${name}" is not available in this session.`;

package/dist/agent/tool-runner.js

@@ -27,6 +27,7 @@ import { formatSchemaErrors, validateSchema } from "./schema.js";
 import { CODEMODE_TOOL } from "../tools/presets.js";
 import { executionModeOf } from "../tools/registry.js";
 import { truncateMiddle } from "../tools/truncate.js";
+import { toolUnavailableText } from "./tool-availability.js";
 export const ABORTED_TOOL_TEXT = "aborted by user";
 export const DEFAULT_MAX_TOOL_RESULT_CHARS = 30_000;
 export const DEFAULT_ABORT_GRACE_MS = 3000;
@@ -63,7 +64,7 @@ function notFoundText(name, options) {
     if (options.getNestedTool?.(name) !== undefined && options.getTool(CODEMODE_TOOL) !== undefined) {
         return `Tool ${name} is only callable inside a codemode script: tools.${name}({...})`;
     }
-    return `Tool ${name} not found`;
+    return toolUnavailableText(name);
 }
 async function prepare(call, assistant, options, signal, parent) {
     if (signal.aborted)
@@ -124,10 +125,14 @@ function resultText(content) {
         return content;
     return content.map((block) => (block.type === "text" ? block.text : "")).join("");
 }
-function truncateResult(call, result, options, nested = false) {
-    const limit = nested
+/** 结果字符上限：嵌套调用 1 MB，否则会话的 `maxToolResultChars`。 */
+function resultLimit(options, nested) {
+    return nested
         ? NESTED_MAX_RESULT_CHARS
         : (options.maxToolResultChars ?? DEFAULT_MAX_TOOL_RESULT_CHARS);
+}
+function truncateResult(call, result, options, nested = false) {
+    const limit = resultLimit(options, nested);
     const text = resultText(result.content);
     if (text.length <= limit)
         return result;
@@ -174,7 +179,11 @@ async function execute(prepared, options, signal, emit, parent) {
     });
     let result;
     try {
-        const ctx = options.createToolContext(call, signal, onUpdate);
+        const created = options.createToolContext(call, signal, onUpdate);
+        // [ME-D] 工具按会话结果上限一次截到位（D11）；宿主自己给了就不覆盖
+        const ctx = created.maxResultChars !== undefined
+            ? created
+            : { ...created, maxResultChars: resultLimit(options, parent !== undefined) };
         const run = tool.execute(input, ctx).then((value) => value, (error) => errorResult(signal.aborted
             ? ABORTED_TOOL_TEXT
             : error instanceof Error

package/dist/agent/worktree.d.ts

@@ -8,6 +8,9 @@
  * - 非 git 目录直接报错，不回落到共享目录；`.ama/worktrees/.gitignore` 写 `*`，父会话的 git 与
  *   grep / glob（读嵌套 .gitignore）都看不到这些目录；
  * - worktree 不保证可运行：依赖（node_modules 等）不共享。
+ * - 并发：同一仓库的 `worktree add / remove` 与删分支会扫描、改写 `.git/worktrees/*`，并行的两个隔离
+ *   任务曾互相读到对方建了一半的管理目录（`无法读取 .git/worktrees/<id>/commondir`）。同进程内按仓库的
+ *   公共 git 目录串行；跨进程（两个 ama 同时开隔离任务）的同类瞬时错误短暂重试。
  */
 export interface Worktree {
     /** worktree 根目录。 */
@@ -29,6 +32,11 @@ export interface WorktreeOutcome {
 }
 export type GitRunner = (args: readonly string[], cwd: string) => Promise<string>;
 export declare const runGit: GitRunner;
+export declare function serialized<T>(key: string, run: () => Promise<T>): Promise<T>;
+export declare function retryTransient<T>(run: () => Promise<T>, options?: {
+    attempts?: number;
+    delayMs?: number;
+}): Promise<T>;
 export declare function worktreeBranch(taskId: string): string;
 /** 在父 cwd 所在仓库里为任务建 worktree；非 git 目录抛错。 */
 export declare function createWorktree(cwd: string, taskId: string, git?: GitRunner): Promise<Worktree>;

package/dist/agent/worktree.js

@@ -8,10 +8,13 @@
  * - 非 git 目录直接报错，不回落到共享目录；`.ama/worktrees/.gitignore` 写 `*`，父会话的 git 与
  *   grep / glob（读嵌套 .gitignore）都看不到这些目录；
  * - worktree 不保证可运行：依赖（node_modules 等）不共享。
+ * - 并发：同一仓库的 `worktree add / remove` 与删分支会扫描、改写 `.git/worktrees/*`，并行的两个隔离
+ *   任务曾互相读到对方建了一半的管理目录（`无法读取 .git/worktrees/<id>/commondir`）。同进程内按仓库的
+ *   公共 git 目录串行；跨进程（两个 ama 同时开隔离任务）的同类瞬时错误短暂重试。
  */
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 const TIMEOUT_MS = 30_000;
 export const runGit = (args, cwd) => new Promise((resolve, reject) => {
     execFile("git", [...args], { cwd, timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
@@ -33,6 +36,48 @@ function realPath(path) {
         return path;
     }
 }
+/** 每个仓库（按公共 git 目录）一条队列：worktree 的增删与删分支串行执行。 */
+const queues = new Map();
+export function serialized(key, run) {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const current = previous.then(run, run);
+    const tail = current.then(() => undefined, () => undefined);
+    queues.set(key, tail);
+    void tail.then(() => {
+        if (queues.get(key) === tail)
+            queues.delete(key);
+    });
+    return current;
+}
+/** 另一个进程正在增删 worktree 时 git 报的瞬时错误（读到半建的管理目录、锁文件已存在）。 */
+const TRANSIENT = /commondir|gitdir|could not read|unable to read|无法读取|\.lock'?: File exists|Unable to create '.*\.lock'|无法创建 '.*\.lock'/i;
+export async function retryTransient(run, options = {}) {
+    const attempts = options.attempts ?? 5;
+    const delayMs = options.delayMs ?? 50;
+    for (let n = 1;; n++) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (n >= attempts || !TRANSIENT.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+            await new Promise((r) => setTimeout(r, delayMs * n));
+        }
+    }
+}
+/** 仓库的公共 git 目录（所有 worktree 共享），作为串行队列的键。 */
+async function commonDir(repo, git) {
+    try {
+        return realPath(resolve(repo, (await git(["rev-parse", "--git-common-dir"], repo)).trim()));
+    }
+    catch {
+        return repo;
+    }
+}
+/** 串行 + 瞬时错误重试地跑一条会改动 `.git/worktrees` 的 git 命令。 */
+function mutate(key, git, args, cwd) {
+    return serialized(key, () => retryTransient(() => git(args, cwd)));
+}
 export function worktreeBranch(taskId) {
     return `ama/task-${taskId}`;
 }
@@ -53,8 +98,9 @@ export async function createWorktree(cwd, taskId, git = runGit) {
         writeFileSync(ignore, "*\n");
     const path = join(root, taskId);
     const branch = worktreeBranch(taskId);
+    const key = await commonDir(repo, git);
     if (!existsSync(path))
-        await git(["worktree", "add", "-b", branch, path, base], repo);
+        await mutate(key, git, ["worktree", "add", "-b", branch, path, base], repo);
     const sub = relative(repo, realPath(cwd));
     const childCwd = sub === "" || sub.startsWith("..") ? path : join(path, sub);
     mkdirSync(childCwd, { recursive: true });
@@ -65,8 +111,9 @@ export async function finishWorktree(tree, git = runGit) {
     const status = (await git(["status", "--porcelain"], tree.path)).trim();
     const head = (await git(["rev-parse", "HEAD"], tree.path)).trim();
     if (status === "" && head === tree.base) {
-        await git(["worktree", "remove", "--force", tree.path], tree.repo);
-        await git(["branch", "-D", tree.branch], tree.repo).catch(() => "");
+        const key = await commonDir(tree.repo, git);
+        await mutate(key, git, ["worktree", "remove", "--force", tree.path], tree.repo);
+        await mutate(key, git, ["branch", "-D", tree.branch], tree.repo).catch(() => "");
         return { branch: tree.branch, changed: false };
     }
     const stat = (await git(["diff", "--stat", tree.base], tree.path).catch(() => "")).trim();

package/dist/agents/parse.js

@@ -88,8 +88,11 @@ export function parseAgentDefinition(text, filePath, source) {
     const background = data["background"];
     if (background !== undefined && typeof background !== "boolean")
         return fail("background must be true or false");
+    const context = data["context"];
+    if (context !== undefined && context !== null && context !== "fork" && context !== "fresh")
+        return fail("context must be fork or fresh");
     if (runner !== "ama") {
-        const ignored = ["tools", "disallowed-tools", "permission-mode"].filter((key) => data[key] !== undefined);
+        const ignored = ["tools", "disallowed-tools", "permission-mode", "context"].filter((key) => data[key] !== undefined);
         if (ignored.length > 0)
             warnings.push(`${filePath}: ${ignored.join(", ")} ignored for external runner ${runner} (it keeps its own policy)`);
     }
@@ -113,5 +116,7 @@ export function parseAgentDefinition(text, filePath, source) {
         agent.disallowedTools = disallowedTools;
     if (typeof thinking === "string")
         agent.thinking = thinking;
+    if (context === "fork" || context === "fresh")
+        agent.context = context;
     return { agent, warnings };
 }

package/dist/agents/task-record.js

@@ -171,6 +171,9 @@ export function applyRunnerEvent(record, event, sink) {
         case "notice":
             sink.log(event.level, `[task ${taskId}] ${event.text}`);
             return;
+        case "context":
+            record.info.context = event.mode;
+            return;
         case "turn_trace":
             sink.appendTrace?.({
                 kind: "external_turn",

package/dist/agents/types.d.ts

@@ -31,6 +31,8 @@ export interface AgentDefinition {
      */
     background?: boolean;
     runner: AgentRunnerSpec;
+    /** [ME-C0] frontmatter `context:`：`fork` 继承父会话已完成的回合；缺省 `fresh`。 */
+    context?: "fork" | "fresh";
     /** 正文：追加到子会话系统提示末尾的角色说明。 */
     prompt: string;
     source: AgentSource;

package/dist/ai/apis/anthropic-messages.js

@@ -12,9 +12,9 @@
  * 任一出现过（含 0）即 `cacheReported: true`，之后的事件不会把它改回 false。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { authHeaders, describeErrorJson, idleTimeoutOf, mergeHeaders, USER_AGENT, } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, streamIdleTimeoutOf, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
-import { postWithCacheFallback } from "./cache-params.js";
+import { clampRequestMaxTokens, postWithMaxTokensFallback } from "./max-tokens.js";
 import { ANTHROPIC_VERSION, anthropicMessagesUrl, buildAnthropicRequest, detectAnthropicCompat, } from "./anthropic-request.js";
 import { BlockTracker, STREAM_ENDED_MESSAGE, ProviderStopError, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
 function num(value) {
@@ -160,20 +160,25 @@ async function run(stream, model, context, options) {
         if (request.providerThinkingLevel !== undefined) {
             tracker.output.providerThinkingLevel = request.providerThinkingLevel;
         }
+        // 预算型思考的预算由 max_tokens 推导，收紧会让消息缓存失效：不主动收紧（D9）
+        const budgeted = obj(request.body["thinking"])?.["type"] === "enabled";
+        clampRequestMaxTokens(request.body, "max_tokens", model.contextWindow, budgeted);
         const replaced = options.onPayload?.(request.body);
         const body = replaced === undefined ? request.body : replaced;
         const baseUrl = model.baseUrl ?? "https://api.anthropic.com";
-        const response = await postWithCacheFallback(model, anthropicMessagesUrl(baseUrl), {
+        const url = anthropicMessagesUrl(baseUrl);
+        const post = {
             headers: buildHeaders(model, options, request.betas),
             body,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
             idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
-        });
+        };
+        const response = await postWithMaxTokensFallback(model, url, post, "max_tokens");
         stream.push({ type: "start", partial: tracker.output });
         const state = { blocks: new Map(), stop: undefined, sawMessageStop: false };
-        for await (const sse of readSseEvents(response.body, options.signal, idleTimeoutOf(options))) {
+        for await (const sse of readSseEvents(response.body, options.signal, streamIdleTimeoutOf(options))) {
             if (sse.event === "ping" || sse.data === "")
                 continue;
             let data;

package/dist/ai/apis/anthropic-request.d.ts

@@ -7,7 +7,8 @@
  * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
  * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
  * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
- * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
+ * ③ 倒数第二条 user 消息的末块（= 上一次请求的写入点；并行工具结果多时最后一条离上次写入点可能超出
+ * 回看窗口）④ 最后一个工具定义（`supportsCacheControlOnTools`）。[ME-C] D7
  *
  * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
  * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，

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

@@ -7,7 +7,8 @@
  * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
  * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
  * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
- * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
+ * ③ 倒数第二条 user 消息的末块（= 上一次请求的写入点；并行工具结果多时最后一条离上次写入点可能超出
+ * 回看窗口）④ 最后一个工具定义（`supportsCacheControlOnTools`）。[ME-C] D7
  *
  * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
  * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，
@@ -161,12 +162,15 @@ function convertTools(tools) {
         input_schema: { ...tool.parameters, type: "object" },
     }));
 }
-/** 在最后一条 user 消息的最后一个块上打断点；返回是否打上。 */
-function markLastUser(messages, cacheControl) {
+/** 在从后数第 `skip + 1` 条 user 消息的最后一个块上打断点；返回是否打上。 */
+function markLastUser(messages, cacheControl, skip = 0) {
+    let remaining = skip;
     for (let i = messages.length - 1; i >= 0; i--) {
         const message = messages[i];
         if (!message || message["role"] !== "user")
             continue;
+        if (remaining-- > 0)
+            continue;
         const content = message["content"];
         if (typeof content === "string") {
             message["content"] = [{ type: "text", text: content, cache_control: cacheControl }];
@@ -240,6 +244,8 @@ export function buildAnthropicRequest(model, context, options) {
         lastSystem["cache_control"] = cacheControl;
         budget--;
     }
+    if (cacheControl && budget > 0 && markLastUser(messages, cacheControl, 1))
+        budget--;
     const lastTool = tools[tools.length - 1];
     if (cacheControl && budget > 0 && lastTool && compat.supportsCacheControlOnTools) {
         lastTool["cache_control"] = cacheControl;

package/dist/ai/apis/google-generative-ai.js

@@ -16,9 +16,10 @@
  * - 错误体 `{error:{code,status,message}}` 重排为 `429 RESOURCE_EXHAUSTED: …`。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { authHeaders, HttpError, idleTimeoutOf, joinUrl, mergeHeaders, postJson, USER_AGENT, } from "../http.js";
+import { authHeaders, HttpError, idleTimeoutOf, streamIdleTimeoutOf, joinUrl, mergeHeaders, postJson, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { GOOGLE_BASE_URL, buildGoogleRequest, detectGoogleCompat } from "./google-request.js";
+import { clampGoogleMaxTokens } from "./max-tokens.js";
 import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
 function num(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
@@ -188,6 +189,7 @@ async function run(stream, model, context, options) {
         if (request.providerThinkingLevel !== undefined) {
             tracker.output.providerThinkingLevel = request.providerThinkingLevel;
         }
+        clampGoogleMaxTokens(request.body, model.contextWindow);
         const replaced = options.onPayload?.(request.body);
         let response;
         try {
@@ -210,7 +212,7 @@ async function run(stream, model, context, options) {
             idSeed: Date.now().toString(36),
         };
         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 === "" || data === "[DONE]")
                 continue;

package/dist/ai/apis/max-tokens.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `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 { type PostOptions } from "../http.js";
+import type { Model } from "../types.js";
+/** 主动收紧的下限：再小就不如让请求原样发出、由被动修正或溢出处理接手。 */
+export declare const MIN_OUTPUT_TOKENS = 1024;
+/** 窗口里给估算误差留的余量。 */
+export declare const OUTPUT_HEADROOM_TOKENS = 2048;
+/** 请求体里放 max_tokens 的字段名（三条协议各不相同）。 */
+export type MaxTokensField = "max_tokens" | "max_completion_tokens" | "max_output_tokens";
+/** `${provider}/${model}` → 已知上限（被动修正时记入，之后的请求直接用）。 */
+export declare const maxTokensCaps: Map<string, number>;
+type Json = Record<string, unknown>;
+/** 主动收紧后的 max_tokens；`window` 未知或 `fixed`（预算型思考）时返回 requested。 */
+export declare function clampMaxTokens(requested: number, window: number | undefined, estimatedInput: number, fixed: boolean): number;
+/** 请求体的输入 token 估算：JSON 字符数 / 4（CJK 偏低，由被动修正兜底）。 */
+export declare function estimateInputTokens(body: unknown): number;
+/**
+ * 就地收紧 `holder[field]`（缺省 holder = body；Google 的 `generationConfig.maxOutputTokens`
+ * 传 holder）。字段不是数字时不动。
+ */
+export declare function clampRequestMaxTokens(body: Json, field: string, window: number | undefined, fixed?: boolean, holder?: Json): void;
+/** Google `generationConfig.maxOutputTokens`；带正的思考预算时不收紧（预算按回答上限留白算出）。 */
+export declare function clampGoogleMaxTokens(body: Json, window: number | undefined): void;
+/** 400 文案里的上限；`{ cap }` 可重发，`{ overflow: true }` 判溢出，undefined 不是本类错误。 */
+export declare function parseMaxTokensRejection(error: unknown): {
+    cap: number;
+} | {
+    overflow: true;
+} | undefined;
+/** `postWithCacheFallback` 之外再包一层：max_tokens 超上限的 400 以收紧值重发一次（只在 `start` 之前）。 */
+export declare function postWithMaxTokensFallback(model: Pick<Model, "provider" | "id">, url: string, options: PostOptions, field: MaxTokensField): Promise<Response>;
+export {};

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),
+        });
+    }
+}