@armadra/agent 0.7.5 → 0.8.0

package/dist/checkpoints/shadow-git.d.ts

@@ -16,8 +16,10 @@
 export declare const SHADOW_DIR = "shadow";
 /** cwd 下（不含忽略的）文件数上限，超出本会话降级为 tools。 */
 export declare const SHADOW_MAX_FILES = 20000;
-/** 单次快照耗时上限（毫秒），超出本会话降级为 tools。 */
+/** 单次快照耗时上限（毫秒），连续 `SHADOW_SLOW_STREAK` 次超出本会话降级为 tools。 */
 export declare const SHADOW_MAX_SNAPSHOT_MS = 3000;
+/** 连续这么多次快照超时才降级（首次快照不计）。 */
+export declare const SHADOW_SLOW_STREAK = 2;
 export declare function shadowRoot(dataDir: string): string;
 /** cwd 对应的影子仓库目录。 */
 export declare function shadowRepoDir(dataDir: string, cwd: string): string;
@@ -73,6 +75,8 @@ export declare class ShadowRepo {
     private readonly indexFile;
     private initialized;
     private counted;
+    /** 连续超时的快照数（首次快照不计），到 `SHADOW_SLOW_STREAK` 才降级。 */
+    private slowStreak;
     constructor(dataDir: string, cwd: string, options?: ShadowGitOptions);
     private now;
     private env;

package/dist/checkpoints/shadow-git.js

@@ -23,8 +23,10 @@ import { msg } from "../i18n/index.js";
 export const SHADOW_DIR = "shadow";
 /** cwd 下（不含忽略的）文件数上限，超出本会话降级为 tools。 */
 export const SHADOW_MAX_FILES = 20_000;
-/** 单次快照耗时上限（毫秒），超出本会话降级为 tools。 */
+/** 单次快照耗时上限（毫秒），连续 `SHADOW_SLOW_STREAK` 次超出本会话降级为 tools。 */
 export const SHADOW_MAX_SNAPSHOT_MS = 3_000;
+/** 连续这么多次快照超时才降级（首次快照不计）。 */
+export const SHADOW_SLOW_STREAK = 2;
 /** 单个 git 进程的硬上限，防止卡死。 */
 const GIT_TIMEOUT_MS = 60_000;
 /** 本地配置的版本；改了配置项就加一，旧仓库会补写。 */
@@ -85,6 +87,8 @@ export class ShadowRepo {
     indexFile;
     initialized;
     counted = false;
+    /** 连续超时的快照数（首次快照不计），到 `SHADOW_SLOW_STREAK` 才降级。 */
+    slowStreak = 0;
     constructor(dataDir, cwd, options = {}) {
         this.cwd = resolve(cwd);
         this.dir = shadowRepoDir(dataDir, this.cwd);
@@ -207,6 +211,8 @@ export class ShadowRepo {
             await this.init();
             // 计时不含一次性的建仓与本地配置（十来个 git 子进程，Windows 上可达数秒），只量快照本身
             const started = this.now();
+            // 首次快照要把整个工作区读进索引，天然偏慢，不计入超时
+            const first = !this.counted;
             await this.writeExcludes();
             if (!this.counted) {
                 const out = await this.run([
@@ -233,7 +239,10 @@ export class ShadowRepo {
                 args.push("-p", parent);
             const commit = await this.text(args);
             const elapsed = this.now() - started;
-            if (elapsed > this.maxSnapshotMs) {
+            if (first)
+                return { commit };
+            this.slowStreak = elapsed > this.maxSnapshotMs ? this.slowStreak + 1 : 0;
+            if (this.slowStreak >= SHADOW_SLOW_STREAK) {
                 return {
                     commit,
                     degrade: {

package/dist/cli/compose-providers.d.ts

@@ -14,6 +14,7 @@
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；
  *   chatgpt 的缓存 flavor 与当前登录不符时视为过期、不并入。
+ * - max_tokens 上限缓存（`<dataDir>/models/max-tokens-caps.json`，30 天）载回进程内的表并订阅写回（#152）。
  */
 import type { ApiRegistry } from "../ai/apis/api.js";
 import { ProviderRegistry } from "../ai/providers/registry.js";

package/dist/cli/compose-providers.js

@@ -14,10 +14,12 @@
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；
  *   chatgpt 的缓存 flavor 与当前登录不符时视为过期、不并入。
+ * - max_tokens 上限缓存（`<dataDir>/models/max-tokens-caps.json`，30 天）载回进程内的表并订阅写回（#152）。
  */
 import { loadModelsDevIndex } from "../ai/providers/models-dev-cache.js";
 import { ProviderRegistry, discoverLocalModels } from "../ai/providers/registry.js";
 import { mergeDiscoveredModels } from "../ai/providers/discovered-cache.js";
+import { attachMaxTokensCache } from "../ai/providers/max-tokens-cache.js";
 import { lazyIndex } from "../ai/providers/enrich.js";
 import { readOAuthEntry } from "../auth/oauth/token-store.js";
 import { CHATGPT_BASE_URLS, CHATGPT_PROVIDER_ID } from "../auth/chatgpt/presets.js";
@@ -110,6 +112,7 @@ export async function buildProviderRegistry(input, options = {}) {
     }
     // 发现缓存（`ama auth login chatgpt` / `ama models discover chatgpt`）并入模型表为空的供应商
     if (dataDir !== undefined) {
+        attachMaxTokensCache(dataDir);
         const flavor = readOAuthEntry(input.authFile, CHATGPT_PROVIDER_ID)?.flavor;
         mergeDiscoveredModels(registry, dataDir, lazyIndex(() => loadModelsDevIndex(dataDir)), (id) => (id === CHATGPT_PROVIDER_ID ? flavor : undefined));
     }

package/dist/cli/compose-store.d.ts

@@ -6,16 +6,19 @@
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；
- * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）；源会话不属于任何 AgentSession，
+ *   它的告警（图片读不回，#183）显式交给 `context.log`。
  */
 import { SessionManager } from "../session/manager.js";
 import type { SessionListItem } from "../session/types.js";
+import type { LogFn } from "./compose-session.js";
 import type { RuntimeDeps, SessionRequest } from "./deps.js";
 /** 按 id / 唯一前缀找会话文件；本 cwd 目录优先。 */
 export declare function findSessionFile(root: string, id: string, cwd?: string): string | undefined;
 export declare function openSession(request: SessionRequest, context: {
     sessionDir: string;
     cwd: string;
+    log?: LogFn | undefined;
 }): SessionManager;
 /** 列会话（最新在前）；子 Agent 会话缺省跳过，`includeSubagents` 时保留（带 `subagent` 标记）。 */
 export declare function listSessions(context: {
@@ -23,4 +26,5 @@ export declare function listSessions(context: {
     cwd?: string;
     includeSubagents?: boolean;
 }): SessionListItem[];
-export declare function createSessionStore(): RuntimeDeps["sessions"];
+/** `log`：`--fork` 源会话的告警出口（通常是会话的 `options.log`）。 */
+export declare function createSessionStore(log?: LogFn): RuntimeDeps["sessions"];

package/dist/cli/compose-store.js

@@ -6,7 +6,8 @@
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；
- * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）；源会话不属于任何 AgentSession，
+ *   它的告警（图片读不回，#183）显式交给 `context.log`。
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -81,7 +82,9 @@ export function openSession(request, context) {
                 : SessionManager.open(file);
         }
         case "fork": {
-            const source = SessionManager.open(requireFile(root, request.id, cwd));
+            const source = SessionManager.open(requireFile(root, request.id, cwd), {
+                warn: (message) => context.log?.("warn", message),
+            });
             try {
                 const leaf = source.leafId();
                 if (leaf === null)
@@ -104,9 +107,10 @@ export function listSessions(context) {
         .filter((item) => context.includeSubagents === true || item.subagent !== true)
         .sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
 }
-export function createSessionStore() {
+/** `log`：`--fork` 源会话的告警出口（通常是会话的 `options.log`）。 */
+export function createSessionStore(log) {
     return {
-        open: (request, context) => openSession(request, context),
+        open: (request, context) => openSession(request, { ...context, log }),
         list: async (context) => listSessions(context),
         show: async (id, context) => {
             const file = requireFile(context.sessionDir, id);

package/dist/cli/compose.js

@@ -40,7 +40,7 @@ import { builtinTools } from "../tools/registry.js";
 import { MEMORY_TOOL, createMemoryTool } from "../memory/tool.js";
 import { takeCodemodeNotice } from "./codemode-notice.js";
 import { buildProviderRegistry } from "./compose-providers.js";
-import { composeSession, emptyComposeState, } from "./compose-session.js";
+import { composeSession, emptyComposeState, stderrLog, } from "./compose-session.js";
 import { createSessionStore } from "./compose-store.js";
 import { defaultSendUser } from "./startup-steps.js";
 import { imageFitOptionsFor } from "../modes/image-input.js";
@@ -211,7 +211,7 @@ export function createRuntimeDeps(options = {}) {
                 return registry;
             },
         },
-        sessions: createSessionStore(),
+        sessions: createSessionStore(options.log ?? stderrLog()),
         tools: { create: (input) => createTools(input, options, state) },
         permissions: {
             create: (input) => new PermissionPipeline({

package/dist/config/json-schema.js

@@ -161,6 +161,7 @@ function w5Sections() {
             background: oneOf(SUBAGENT_BACKGROUND_MODES),
             autoBackgroundAfterMs: num(0),
             retainSessions: num(0),
+            forkMaxContextRatio: num(0.05, 0.95),
         }),
         models: object({ aliases: object({ fast: str(), strong: str() }), enabled: strings }),
         fallbackModel: str(),

package/dist/config/key-docs.js

@@ -65,6 +65,7 @@ const IMPLICIT_DEFAULTS = {
         background: "auto",
         autoBackgroundAfterMs: 0,
         retainSessions: 4,
+        forkMaxContextRatio: 0.5,
     },
     reminders: { todo: true, fileChanges: true, contextPressure: true, budget: true },
     todo: { reminder: 10 },

package/dist/config/schema-w5.js

@@ -90,6 +90,7 @@ export function validateConfigW5(c, config) {
         "background",
         "autoBackgroundAfterMs",
         "retainSessions",
+        "forkMaxContextRatio",
     ], (s, p) => {
         c.number(s, "maxConcurrent", p, 1, 64);
         c.number(s, "maxPending", p, 0, 1024);
@@ -97,6 +98,7 @@ export function validateConfigW5(c, config) {
         c.oneOf(s, "background", p, SUBAGENT_BACKGROUND_MODES);
         c.number(s, "autoBackgroundAfterMs", p, 0);
         c.number(s, "retainSessions", p, 0);
+        c.number(s, "forkMaxContextRatio", p, 0.05, 0.95);
     });
     checkSection(c, config, "models", ["aliases", "enabled"], (s, p) => {
         c.stringArray(s, "enabled", p);

package/dist/config/settings-registry.js

@@ -101,6 +101,7 @@ const ROWS = [
     row("subagents.maxConcurrent", "agents", "nextSession", "deny"),
     row("subagents.maxPending", "agents", "nextSession", "deny"),
     row("subagents.retainSessions", "agents", "nextSession", "deny"),
+    row("subagents.forkMaxContextRatio", "agents", "nextSession", "deny"),
     // [W7-B2] 改 task 工具描述（缺省后台 / 前台两种文案），故 prefix
     row("subagents.background", "agents", "restart", "any", { prefix: true }),
     row("subagents.autoBackgroundAfterMs", "agents", "restart", "any"),

package/dist/config/types-w5.d.ts

@@ -79,6 +79,11 @@ export interface SubagentsConfig {
     autoBackgroundAfterMs?: number;
     /** [M-F] 已结束子会话保留在内存的句柄数（LRU），缺省 4；超出的续聊时从会话文件重开。只认用户级。 */
     retainSessions?: number;
+    /**
+     * [#149] fork 回落比例：父上一次请求的输入 token 超过（窗口 − compaction.reserveTokens）× 本值时
+     * fork 回落为 fresh；0.05–0.95，缺省 0.5。只认用户级。
+     */
+    forkMaxContextRatio?: number;
 }
 /** `models.enabled` 的一项：`provider/model[@channel]` 或 `provider/*`。 */
 export declare const MODELS_ENABLED_REF: RegExp;

package/dist/drivers/acp/driver.d.ts

@@ -19,16 +19,36 @@ import { type DriverDeps } from "../base.js";
 import type { CatalogCandidate } from "../catalog.js";
 import { TurnCollector } from "../turn.js";
 import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
-import { type AcpAuthMethod, type AcpContentBlock, type AcpSessionConfigOption, type AcpSessionModeState, type AcpSessionUpdate } from "./types.js";
+import { type AcpAuthMethod, type AcpContentBlock, type AcpPromptUsage, type AcpSessionConfigOption, type AcpSessionModeState, type AcpSessionUpdate } from "./types.js";
 export declare function toAcpContent(blocks: readonly ContentBlock[], images: boolean): AcpContentBlock[];
 /** session/update → DriverEvent（用户消息回放、命令表等忽略）。 */
 export declare function pushAcpUpdate(update: AcpSessionUpdate, turn: TurnCollector): void;
+type TurnUsage = {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+};
+/**
+ * `session/prompt` 答复的 usage → 本回合用量（ama 口径：input 不含缓存命中）。
+ * - `previous`：Agent 报的是会话累计（如 Copilot）时，上一回合的原始累计值，相减得本回合；
+ * - 有 `totalTokens` 且它等于 input + output 时，input 含缓存命中部分，减去 cachedRead。
+ */
+export declare function acpTurnUsage(usage: AcpPromptUsage, previous?: AcpPromptUsage): TurnUsage;
 /** ama 模式 → 该 Agent 的模式 id（显式映射 > 同名）。 */
 export declare function pickModeId(mode: PermissionMode, candidate: CatalogCandidate, state: AcpSessionModeState | null | undefined): string | undefined;
 /** `configOptions` 里 category `mode` 的选择项（没有 `modes` 的 Agent 用它表达模式）。 */
 export declare function modeConfigOption(options: readonly AcpSessionConfigOption[] | null | undefined): AcpSessionConfigOption | undefined;
 /** 与 {@link pickModeId} 同一映射，在 mode 类配置项的可选值里找（分组的展开）。 */
 export declare function pickConfigModeValue(mode: PermissionMode, candidate: CatalogCandidate, option: AcpSessionConfigOption | undefined): string | undefined;
+/**
+ * `agents.<id>.model` / task 的 `model` → configOptions 里 category `model` 的可选值：先精确匹配值，
+ * 再不分大小写匹配值或名称，最后匹配 `provider/model` 的模型部分。没有就返回 undefined（用 Agent 的缺省）。
+ */
+export declare function pickModelValue(model: string, options: readonly AcpSessionConfigOption[] | null | undefined): {
+    configId: string;
+    value: string;
+    current: boolean;
+} | undefined;
 /** 开会话回 -32000 → `agent_auth_required`，列出 `initialize` 给的认证方法。 */
 export declare function authRequiredError(agentId: string, methods: readonly AcpAuthMethod[], command: readonly string[], cause: unknown): AmaError;
 export declare class AcpDriver implements AgentDriver {
@@ -40,3 +60,4 @@ export declare class AcpDriver implements AgentDriver {
     probe(): Promise<DriverProbe>;
     open(options: DriverOpenOptions): Promise<DriverSession>;
 }
+export {};

package/dist/drivers/acp/driver.js

@@ -90,6 +90,34 @@ export function pushAcpUpdate(update, turn) {
             return;
     }
 }
+/**
+ * `session/prompt` 答复的 usage → 本回合用量（ama 口径：input 不含缓存命中）。
+ * - `previous`：Agent 报的是会话累计（如 Copilot）时，上一回合的原始累计值，相减得本回合；
+ * - 有 `totalTokens` 且它等于 input + output 时，input 含缓存命中部分，减去 cachedRead。
+ */
+export function acpTurnUsage(usage, previous) {
+    const diff = (key) => {
+        const now = usage[key];
+        if (now === undefined)
+            return undefined;
+        return previous === undefined ? now : Math.max(0, now - (previous[key] ?? 0));
+    };
+    const input = diff("inputTokens");
+    const output = diff("outputTokens");
+    const cacheRead = diff("cachedReadTokens");
+    const { totalTokens: total, inputTokens: rawIn = 0, outputTokens: rawOut = 0 } = usage;
+    const cached = usage.cachedReadTokens ?? 0;
+    const includesCache = total !== undefined &&
+        cached > 0 &&
+        Math.abs(total - (rawIn + rawOut)) < Math.abs(total - (rawIn + rawOut + cached));
+    return {
+        ...(input !== undefined
+            ? { input: includesCache ? Math.max(0, input - (cacheRead ?? 0)) : input }
+            : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(cacheRead !== undefined ? { cacheRead } : {}),
+    };
+}
 /** ama 模式在 Agent 那边想要的模式 id，按优先级（显式映射 > 同名）。 */
 function wantedModeIds(mode, candidate) {
     const wanted = [candidate.modes?.[mode] ?? mode];
@@ -113,6 +141,23 @@ export function pickConfigModeValue(mode, candidate, option) {
     const values = option.options.flatMap((o) => "options" in o ? o.options.map((x) => x.value) : [o.value]);
     return wantedModeIds(mode, candidate).find((id) => values.includes(id));
 }
+/**
+ * `agents.<id>.model` / task 的 `model` → configOptions 里 category `model` 的可选值：先精确匹配值，
+ * 再不分大小写匹配值或名称，最后匹配 `provider/model` 的模型部分。没有就返回 undefined（用 Agent 的缺省）。
+ */
+export function pickModelValue(model, options) {
+    const option = options?.find((o) => o.category === "model" && o.type === "select");
+    if (option === undefined)
+        return undefined;
+    const values = option.options.flatMap((o) => ("options" in o ? o.options : [o]));
+    const lower = model.toLowerCase();
+    const hit = values.find((v) => v.value === model) ??
+        values.find((v) => v.value.toLowerCase() === lower || v.name.toLowerCase() === lower) ??
+        values.find((v) => v.value.toLowerCase().split("/").at(-1) === lower);
+    return hit === undefined
+        ? undefined
+        : { configId: option.id, value: hit.value, current: option.currentValue === hit.value };
+}
 /** 一条认证方法给人看的样子：terminal 型附上要在终端里跑的命令。 */
 function authMethodText(method, command) {
     if (method.type !== "terminal")
@@ -181,6 +226,9 @@ class AcpDriverSession {
     notices = [];
     /** 本回合已发过 cancel。 */
     cancelling = false;
+    /** Agent 的 usage 是会话累计时，上一回合的原始值（{@link acpTurnUsage}）。 */
+    usageTotals;
+    cumulativeUsage = false;
     constructor(agentId, transport, deps) {
         this.agentId = agentId;
         this.transport = transport;
@@ -200,6 +248,7 @@ class AcpDriverSession {
             onProtocolError: (_line, reason) => this.deps.log?.("debug", `${this.agentId}: ${reason}`),
         });
         const signal = options.signal;
+        this.cumulativeUsage = candidate.acpUsage === "session";
         await this.client.initialize(signal);
         let opened;
         try {
@@ -228,6 +277,13 @@ class AcpDriverSession {
         else if (modes != null || modeOption !== undefined) {
             this.notices.push(msg().drivers.agent.noMatchingMode(this.agentId, options.mode));
         }
+        if (options.model !== undefined) {
+            const model = pickModelValue(options.model, opened.configOptions);
+            if (model === undefined)
+                this.notices.push(msg().drivers.agent.noMatchingModel(this.agentId, options.model));
+            else if (!model.current)
+                await this.client.setConfigOption(this.id, model.configId, model.value);
+        }
     }
     /** 续聊优先 resume（不回放），其次 load（回放丢弃），都不行就新开；设好 `this.id`。 */
     async openSession(options) {
@@ -291,11 +347,9 @@ class AcpDriverSession {
             });
             const usage = result.usage;
             if (usage != null) {
-                turn.mergeUsage({
-                    ...(usage.inputTokens !== undefined ? { input: usage.inputTokens } : {}),
-                    ...(usage.outputTokens !== undefined ? { output: usage.outputTokens } : {}),
-                    ...(usage.cachedReadTokens !== undefined ? { cacheRead: usage.cachedReadTokens } : {}),
-                });
+                turn.mergeUsage(acpTurnUsage(usage, this.cumulativeUsage ? (this.usageTotals ?? {}) : undefined));
+                if (this.cumulativeUsage)
+                    this.usageTotals = usage;
             }
             return turn.result(result.stopReason);
         }

package/dist/drivers/agents.js

@@ -17,6 +17,7 @@ import { HostRunnerRegistry } from "./host-runners.js";
 import { ClaudeStreamDriver } from "./native/claude-stream.js";
 import { CodexAppServerDriver } from "./native/codex-app-server.js";
 import { OneshotDriver } from "./native/oneshot.js";
+import { PiRpcDriver } from "./native/pi-rpc.js";
 import { PidRegistry, pidsFile } from "./pids.js";
 import { poolFromConfig } from "./pool.js";
 import { ProgramProbe } from "./probe.js";
@@ -33,6 +34,8 @@ export function createDriver(agentId, candidate, deps) {
             return new ClaudeStreamDriver(agentId, candidate, deps);
         case "codex-app-server":
             return new CodexAppServerDriver(agentId, candidate, deps);
+        case "pi-rpc":
+            return new PiRpcDriver(agentId, candidate, deps);
         case "oneshot":
             return new OneshotDriver(agentId, candidate, deps);
     }

package/dist/drivers/catalog.d.ts

@@ -24,6 +24,8 @@ export interface CatalogCandidate {
     modes?: Partial<Record<PermissionMode, string>>;
     permissions?: DriverCapabilities["permissions"];
     usage?: DriverCapabilities["usage"];
+    /** `session/prompt` 答复的 usage 是会话累计（缺省按本回合）。 */
+    acpUsage?: "session";
     /** 一次性打印模式的方言。 */
     oneshot?: "claude" | "codex" | "gemini";
 }

package/dist/drivers/catalog.js

@@ -17,12 +17,55 @@ const ALL_MODES = [
     "auto",
     "full-auto",
 ];
+/**
+ * 模式 id 与 ama 不同名的 ACP Agent 的映射（2026-10 实测）。没有映射时 ama 会留在 Agent 自己的当前模式，
+ * 而它可能比 ama 宽（如用户把 Claude 的缺省设成 bypassPermissions），所以已知的 Agent 一律写全。
+ * 从不映射到放开全部权限的模式（Claude `bypassPermissions`、Codex `agent-full-access`、Copilot autopilot）。
+ */
+const CLAUDE_ACP_MODES = {
+    plan: "plan",
+    default: "default",
+    "auto-edit": "acceptEdits",
+    auto: "auto",
+    "full-auto": "auto",
+};
+/** codex-acp：`read-only` 是只读沙箱、写操作要审批（等同 app-server 的 on-request / read-only）。 */
+const CODEX_ACP_MODES = {
+    plan: "read-only",
+    default: "read-only",
+    "auto-edit": "workspace-write",
+    auto: "agent",
+    "full-auto": "agent",
+};
+const COPILOT_MODE = "https://agentclientprotocol.com/protocol/session-modes#";
+const COPILOT_MODES = {
+    plan: `${COPILOT_MODE}plan`,
+    default: `${COPILOT_MODE}agent`,
+    "auto-edit": `${COPILOT_MODE}agent`,
+    auto: `${COPILOT_MODE}agent`,
+    "full-auto": `${COPILOT_MODE}agent`,
+};
+/** Cursor CLI（官方 ACP 文档）：`plan` 只读，`agent` 是完整工具权限（需要授权的仍发 request_permission）。 */
+const CURSOR_MODES = {
+    plan: "plan",
+    default: "agent",
+    "auto-edit": "agent",
+    auto: "agent",
+    "full-auto": "agent",
+};
 export const DRIVER_CATALOG = [
     {
         agentId: "claude",
         label: "Claude Code",
         candidates: [
-            { kind: "acp-adapter", program: "claude-agent-acp", args: [], usage: "usd" },
+            {
+                kind: "acp-adapter",
+                program: "claude-agent-acp",
+                args: [],
+                verified: ">=0.89.0 <1.0.0",
+                usage: "usd",
+                modes: CLAUDE_ACP_MODES,
+            },
             {
                 kind: "claude-stream",
                 program: "claude",
@@ -37,7 +80,14 @@ export const DRIVER_CATALOG = [
         agentId: "codex",
         label: "Codex",
         candidates: [
-            { kind: "acp-adapter", program: "codex-acp", args: [], usage: "tokens" },
+            {
+                kind: "acp-adapter",
+                program: "codex-acp",
+                args: [],
+                verified: ">=2.2.0 <3.0.0",
+                usage: "tokens",
+                modes: CODEX_ACP_MODES,
+            },
             {
                 kind: "codex-app-server",
                 program: "codex",
@@ -70,15 +120,44 @@ export const DRIVER_CATALOG = [
     {
         agentId: "opencode",
         label: "OpenCode",
-        candidates: [{ kind: "acp", program: "opencode", args: ["acp"] }],
+        candidates: [{ kind: "acp", program: "opencode", args: ["acp"], verified: ">=1.18.0 <2.0.0" }],
     },
     {
         agentId: "copilot",
         label: "GitHub Copilot CLI",
         candidates: [
-            { kind: "acp", program: "copilot", args: ["--acp", "--stdio"], usage: "requests" },
+            {
+                kind: "acp",
+                program: "copilot",
+                args: ["--acp", "--stdio"],
+                verified: ">=1.0.95 <2.0.0",
+                usage: "requests",
+                modes: COPILOT_MODES,
+                acpUsage: "session",
+            },
         ],
     },
+    {
+        agentId: "pi",
+        label: "Pi",
+        // 社区 ACP 适配器 pi-acp 不发 request_permission（pi 没有审批通道），会让工具不经人直接执行，不收录
+        candidates: [
+            {
+                kind: "pi-rpc",
+                program: "pi",
+                args: ["--mode", "rpc"],
+                verified: ">=1.1.0 <2.0.0",
+                usage: "usd",
+            },
+        ],
+    },
+    {
+        agentId: "cursor",
+        label: "Cursor CLI",
+        // 未实测（本机未装）：按官方文档 `cursor-agent acp`，模式 agent / plan / ask；`cursor/ask_question`
+        // 等阻塞式扩展方法 ama 不实现（回 method not found，不代答）
+        candidates: [{ kind: "acp", program: "cursor-agent", args: ["acp"], modes: CURSOR_MODES }],
+    },
     {
         agentId: "goose",
         label: "Goose",
@@ -142,6 +221,17 @@ export function candidateCapabilities(c) {
                 usage: "tokens",
                 images: false,
             };
+        case "pi-rpc":
+            // 审批经 ama 加载的审批闸扩展交给人（native/pi-gate.ts）
+            return {
+                resume: "resume",
+                list: false,
+                permissions: "interactive",
+                steer: true,
+                modes: ALL_MODES,
+                usage: "usd",
+                images: true,
+            };
         case "oneshot":
             return {
                 resume: c.oneshot === "gemini" ? "none" : "resume",

package/dist/drivers/native/claude-normalize.d.ts

@@ -39,7 +39,15 @@ export interface ClaudeResult {
         tool_name?: string;
     }[];
     errors?: string[];
+    /** 进程内累计，按模型分；`contextWindow` 是该模型的上下文窗口（2.1.x 起）。 */
+    modelUsage?: Record<string, {
+        contextWindow?: number;
+    }>;
 }
+/** 一条主线 assistant 消息的用量 = 这次请求后的上下文占用（输入 + 缓存读写 + 输出）。 */
+export declare function claudeContextTokens(usage: unknown): number | undefined;
+/** result.modelUsage 里某模型（缺省取最大）的上下文窗口。 */
+export declare function claudeContextWindow(result: ClaudeResult, model: string | undefined): number | undefined;
 /** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
 export declare function claudeStopReason(result: ClaudeResult, interrupted: boolean): "end_turn" | "max_turn_requests" | "cancelled" | undefined;
 /** 只保留会话范围的权限建议（`localSettings` 等会改用户 / 项目配置文件，不能替人写）。 */

package/dist/drivers/native/claude-normalize.js

@@ -81,6 +81,33 @@ export function claudePermissionMode(mode, manualName) {
 }
 /** 只能由人回答的提问类工具（ama 不代答）。 */
 export const CLAUDE_QUESTION_TOOLS = new Set(["AskUserQuestion"]);
+/** 一条主线 assistant 消息的用量 = 这次请求后的上下文占用（输入 + 缓存读写 + 输出）。 */
+export function claudeContextTokens(usage) {
+    if (typeof usage !== "object" || usage === null)
+        return undefined;
+    const u = usage;
+    let total = 0;
+    for (const key of [
+        "input_tokens",
+        "cache_read_input_tokens",
+        "cache_creation_input_tokens",
+        "output_tokens",
+    ])
+        if (typeof u[key] === "number")
+            total += u[key];
+    return total > 0 ? total : undefined;
+}
+/** result.modelUsage 里某模型（缺省取最大）的上下文窗口。 */
+export function claudeContextWindow(result, model) {
+    const entries = result.modelUsage ?? {};
+    const hit = model !== undefined ? entries[model]?.contextWindow : undefined;
+    if (typeof hit === "number" && hit > 0)
+        return hit;
+    const windows = Object.values(entries)
+        .map((e) => e.contextWindow)
+        .filter((w) => typeof w === "number" && w > 0);
+    return windows.length > 0 ? Math.max(...windows) : undefined;
+}
 /** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
 export function claudeStopReason(result, interrupted) {
     if (interrupted)

package/dist/drivers/native/claude-stream.js

@@ -20,7 +20,7 @@ import { createLineReader } from "../../modes/rpc/jsonl.js";
 import { armCancelWatchdog, probeCandidate, spawnOf } from "../base.js";
 import { stderrHint } from "../process.js";
 import { TurnCollector, oneLine } from "../turn.js";
-import { CLAUDE_QUESTION_TOOLS, claudePermissionMode, claudeStopReason, claudeTodos, claudeToolKind, claudeToolLocations, claudeToolTitle, sessionScopedSuggestions, } from "./claude-normalize.js";
+import { CLAUDE_QUESTION_TOOLS, claudeContextTokens, claudeContextWindow, claudePermissionMode, claudeStopReason, claudeTodos, claudeToolKind, claudeToolLocations, claudeToolTitle, sessionScopedSuggestions, } from "./claude-normalize.js";
 import { msg as messages } from "../../i18n/index.js";
 export function claudeArgs(options, sessionId, manualName = "manual") {
     const args = [
@@ -116,6 +116,8 @@ class ClaudeStreamSession {
     interrupted = false;
     sawPartialText = false;
     lastTotalCost = 0;
+    /** 最近一条主线 assistant 消息的上下文占用与模型（result 里查窗口用）。 */
+    context = {};
     closed = false;
     exited = false;
     constructor(agentId, id, transport, deps) {
@@ -218,6 +220,13 @@ class ClaudeStreamSession {
             ...(u.cache_read_input_tokens !== undefined ? { cacheRead: u.cache_read_input_tokens } : {}),
             ...(cost !== undefined ? { costUsd: cost } : {}),
         });
+        const window = claudeContextWindow(result, this.context.model);
+        if (this.context.tokens !== undefined || window !== undefined)
+            turn.push({
+                type: "usage",
+                ...(this.context.tokens !== undefined ? { contextTokens: this.context.tokens } : {}),
+                ...(window !== undefined ? { contextWindow: window } : {}),
+            });
         if (typeof result.result === "string" && result.result !== "")
             turn.setFinalText(result.result);
         const denials = result.permission_denials?.length ?? 0;
@@ -337,6 +346,12 @@ class ClaudeStreamSession {
             return;
         // 子 Agent（Task）内部的消息不进最终文本
         const nested = typeof parent === "string" && parent !== "";
+        const tokens = nested ? undefined : claudeContextTokens(message["usage"]);
+        if (tokens !== undefined)
+            this.context = {
+                tokens,
+                ...(typeof message["model"] === "string" ? { model: message["model"] } : {}),
+            };
         for (const block of message["content"]) {
             if (block["type"] === "text" &&
                 !nested &&