@armadra/agent 0.7.0 → 0.7.2

package/dist/checkpoints/shadow-git.js

@@ -204,8 +204,9 @@ export class ShadowRepo {
     /** 新回合快照：返回提交 id 与是否该降级。 */
     snapshot(parent, message) {
         return exclusive(this.dir, async () => {
-            const started = this.now();
             await this.init();
+            // 计时不含一次性的建仓与本地配置（十来个 git 子进程，Windows 上可达数秒），只量快照本身
+            const started = this.now();
             await this.writeExcludes();
             if (!this.counted) {
                 const out = await this.run([

package/dist/compaction/breakdown.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 上下文分类明细（`/context`）：把投影消息按类别拆开估算。纯函数，只读，不改请求体。
+ *
+ * 口径与 `estimateMessagesTokens` 一致：每条消息先按 `estimateMessageTokens` 求总量，再把这个总量
+ * 分到消息内各部分（文本部分取 `wide + floor(narrow / 4)`，余下的 0–3 个 token 按最大余数补给
+ * 字符余数最大的部分；图片每张 `IMAGE_TOKENS`），所以各类别之和恰好等于整组消息的估算。
+ *
+ * 系统提示与工具声明来自活动分支上的 `system` 消息（首条全量、之后是补丁，补丁也计入——与估算口径
+ * 相同）：按节名、按工具名汇总；工具表数组的括号与逗号计入工具声明但不归到具体工具。首次请求前
+ * 分支上还没有 `system` 消息，这两类为 0（`hasSystem: false`）。
+ *
+ * 只产出数字与名字（节名、工具名、custom 类型），不带任何正文。
+ */
+import type { AgentMessage } from "../session/types.js";
+export declare const BREAKDOWN_CATEGORIES: readonly ["system", "tools", "user", "assistant", "reasoning", "toolCalls", "toolResults", "images", "summaries", "custom"];
+export type BreakdownCategory = (typeof BREAKDOWN_CATEGORIES)[number];
+export interface BreakdownPart {
+    /** 节名 / 工具名 / `compaction`·`branch` / custom 类型 / 图片来源角色。 */
+    name: string;
+    tokens: number;
+}
+export interface BreakdownEntry {
+    category: BreakdownCategory;
+    tokens: number;
+    /** 计入本类的块数（消息、块、节、图片）。 */
+    count: number;
+    /** 按名字汇总，从大到小；没有名字的部分（如工具表的括号）只进 `tokens`。 */
+    parts: BreakdownPart[];
+}
+export interface ToolResultSize {
+    /** 在投影里第几个工具结果（从 1 开始）。 */
+    ordinal: number;
+    toolName: string;
+    tokens: number;
+}
+export interface ContextBreakdown {
+    /** 固定顺序（`BREAKDOWN_CATEGORIES`）。 */
+    entries: BreakdownEntry[];
+    /** = `estimateMessagesTokens(messages)`。 */
+    total: number;
+    /** 系统提示 + 工具声明。 */
+    prefixTokens: number;
+    /** 分支上已有 `system` 消息（首次请求后）。 */
+    hasSystem: boolean;
+    /** 每个工具结果的大小，按出现顺序。 */
+    toolResults: ToolResultSize[];
+}
+/** 消息 → 分类明细（各类别之和 = `estimateMessagesTokens(messages)`）。 */
+export declare function breakdownMessages(messages: readonly AgentMessage[]): ContextBreakdown;
+/** 最大的 n 个工具结果（大小相同按出现顺序）。 */
+export declare function largestToolResults(breakdown: ContextBreakdown, n: number): ToolResultSize[];

package/dist/compaction/breakdown.js

@@ -0,0 +1,159 @@
+/**
+ * 上下文分类明细（`/context`）：把投影消息按类别拆开估算。纯函数，只读，不改请求体。
+ *
+ * 口径与 `estimateMessagesTokens` 一致：每条消息先按 `estimateMessageTokens` 求总量，再把这个总量
+ * 分到消息内各部分（文本部分取 `wide + floor(narrow / 4)`，余下的 0–3 个 token 按最大余数补给
+ * 字符余数最大的部分；图片每张 `IMAGE_TOKENS`），所以各类别之和恰好等于整组消息的估算。
+ *
+ * 系统提示与工具声明来自活动分支上的 `system` 消息（首条全量、之后是补丁，补丁也计入——与估算口径
+ * 相同）：按节名、按工具名汇总；工具表数组的括号与逗号计入工具声明但不归到具体工具。首次请求前
+ * 分支上还没有 `system` 消息，这两类为 0（`hasSystem: false`）。
+ *
+ * 只产出数字与名字（节名、工具名、custom 类型），不带任何正文。
+ */
+import { countText, estimateMessageTokens, IMAGE_TOKENS } from "./estimate.js";
+/** 与 estimate.ts 的字符口径相同（非宽字符每 4 个 1 token）。 */
+const CHARS_PER_TOKEN = 4;
+export const BREAKDOWN_CATEGORIES = [
+    "system",
+    "tools",
+    "user",
+    "assistant",
+    "reasoning",
+    "toolCalls",
+    "toolResults",
+    "images",
+    "summaries",
+    "custom",
+];
+function textPiece(category, name, text) {
+    const count = countText(text, { wide: 0, narrow: 0 });
+    return { category, name, wide: count.wide, narrow: count.narrow, fixed: 0 };
+}
+function imagePiece(name) {
+    return { category: "images", name, wide: 0, narrow: 0, fixed: IMAGE_TOKENS };
+}
+function contentPieces(content, category, name, imageSource) {
+    if (typeof content === "string")
+        return [textPiece(category, name, content)];
+    return content.map((block) => block.type === "text" ? textPiece(category, name, block.text) : imagePiece(imageSource));
+}
+/** 一条消息拆成的部分（字符合计与 `estimateMessageTokens` 的计数完全相同）。 */
+function messagePieces(message) {
+    switch (message.role) {
+        case "system": {
+            const pieces = Object.entries(message.sections).map(([name, text]) => textPiece("system", name, text ?? ""));
+            const tools = message.toolsAdded;
+            if (tools !== undefined) {
+                for (const tool of tools)
+                    pieces.push(textPiece("tools", tool.name, JSON.stringify(tool)));
+                // JSON.stringify(数组) 比各元素多出 `[`、`]` 与元素间的逗号
+                pieces.push({
+                    category: "tools",
+                    name: undefined,
+                    wide: 0,
+                    narrow: 2 + Math.max(0, tools.length - 1),
+                    fixed: 0,
+                });
+            }
+            return pieces;
+        }
+        case "user":
+            return contentPieces(message.content, "user", undefined, "user");
+        case "toolResult":
+            return contentPieces(message.content, "toolResults", message.toolName, "toolResult");
+        case "custom":
+            return contentPieces(message.content, "custom", message.customType, "custom");
+        case "assistant":
+            return message.content.map((block) => block.type === "text"
+                ? textPiece("assistant", undefined, block.text)
+                : block.type === "thinking"
+                    ? textPiece("reasoning", undefined, block.thinking)
+                    : textPiece("toolCalls", block.name, block.name + JSON.stringify(block.arguments)));
+        case "compactionSummary":
+            return [textPiece("summaries", "compaction", message.summary)];
+        case "branchSummary":
+            return [textPiece("summaries", "branch", message.summary)];
+    }
+}
+/** 把消息总量分到各部分（最大余数法），返回与 pieces 对齐的 token 数。 */
+function allocate(pieces, total) {
+    const tokens = pieces.map((p) => p.fixed + p.wide + Math.floor(p.narrow / CHARS_PER_TOKEN));
+    let left = total - tokens.reduce((sum, n) => sum + n, 0);
+    const order = pieces
+        .map((p, i) => ({ i, rest: p.narrow % CHARS_PER_TOKEN }))
+        .filter((x) => x.rest > 0)
+        .sort((a, b) => b.rest - a.rest || a.i - b.i);
+    for (const { i } of order) {
+        if (left <= 0)
+            break;
+        tokens[i] = (tokens[i] ?? 0) + 1;
+        left--;
+    }
+    // 理论上不会剩；保险起见补到最大的部分，保证合计与估算一致
+    if (left !== 0 && tokens.length > 0) {
+        let max = 0;
+        for (let i = 1; i < tokens.length; i++)
+            if ((tokens[i] ?? 0) > (tokens[max] ?? 0))
+                max = i;
+        tokens[max] = (tokens[max] ?? 0) + left;
+    }
+    return tokens;
+}
+/** 消息 → 分类明细（各类别之和 = `estimateMessagesTokens(messages)`）。 */
+export function breakdownMessages(messages) {
+    const totals = new Map();
+    const parts = new Map();
+    for (const category of BREAKDOWN_CATEGORIES) {
+        totals.set(category, { tokens: 0, count: 0 });
+        parts.set(category, new Map());
+    }
+    const toolResults = [];
+    let total = 0;
+    let hasSystem = false;
+    for (const message of messages) {
+        const messageTokens = estimateMessageTokens(message);
+        total += messageTokens;
+        if (message.role === "system")
+            hasSystem = true;
+        if (message.role === "toolResult") {
+            toolResults.push({
+                ordinal: toolResults.length + 1,
+                toolName: message.toolName,
+                tokens: messageTokens,
+            });
+        }
+        const pieces = messagePieces(message);
+        const allocated = allocate(pieces, messageTokens);
+        pieces.forEach((piece, i) => {
+            const tokens = allocated[i] ?? 0;
+            const entry = totals.get(piece.category);
+            if (entry === undefined)
+                return;
+            entry.tokens += tokens;
+            if (piece.name !== undefined || piece.category !== "tools")
+                entry.count++;
+            if (piece.name !== undefined) {
+                const named = parts.get(piece.category);
+                named?.set(piece.name, (named.get(piece.name) ?? 0) + tokens);
+            }
+        });
+    }
+    const entries = BREAKDOWN_CATEGORIES.map((category) => {
+        const entry = totals.get(category) ?? { tokens: 0, count: 0 };
+        const named = [...(parts.get(category) ?? new Map())]
+            .map(([name, tokens]) => ({ name, tokens }))
+            .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+        return { category, tokens: entry.tokens, count: entry.count, parts: named };
+    });
+    const prefixTokens = entries
+        .filter((e) => e.category === "system" || e.category === "tools")
+        .reduce((sum, e) => sum + e.tokens, 0);
+    return { entries, total, prefixTokens, hasSystem, toolResults };
+}
+/** 最大的 n 个工具结果（大小相同按出现顺序）。 */
+export function largestToolResults(breakdown, n) {
+    return [...breakdown.toolResults]
+        .sort((a, b) => b.tokens - a.tokens || a.ordinal - b.ordinal)
+        .slice(0, Math.max(0, n));
+}

package/dist/compaction/estimate.d.ts

@@ -15,6 +15,11 @@ import type { AgentMessage, SessionEntry } from "../session/types.js";
 export declare const IMAGE_TOKENS = 1600;
 /** 文本的 token 估算：CJK / 假名 / 谚文每字 1，其余字符 / 4（向上取整）。 */
 export declare function estimateTextTokens(text: string): number;
+interface CharCount {
+    wide: number;
+    narrow: number;
+}
+export declare function countText(text: string, into: CharCount): CharCount;
 export declare function calculateContextTokens(usage: Usage): number;
 /** 内容的估算（文本按脚本，图片每张 1 600）。 */
 export declare function estimateContentTokens(content: string | readonly ContentBlock[]): number;
@@ -36,3 +41,4 @@ export declare function estimateContextTokens(messages: readonly AgentMessage[])
  * `items` 是 buildProjection(branch).items，`branch` 是同一活动分支。
  */
 export declare function estimateProjectedTokens(items: readonly ContextItem[], branch: readonly SessionEntry[]): ContextEstimate;
+export {};

package/dist/compaction/estimate.js

@@ -29,7 +29,7 @@ function isWideCode(code) {
 export function estimateTextTokens(text) {
     return tokensOf(countText(text, { wide: 0, narrow: 0 }));
 }
-function countText(text, into) {
+export function countText(text, into) {
     let wide = 0;
     let narrow = 0;
     for (let i = 0; i < text.length; i++) {

package/dist/compaction/prefix-estimate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 启动基线：系统消息落盘之前（第一次请求前）的上下文估算。
+ *
+ * 系统提示与工具表在第一次请求前才作为首条 `system` 消息写进分支，在此之前投影里没有它们，
+ * 状态栏会一直显示 0。这里按「将要发送的那一份」估算：命名节文本 + 工具声明 JSON，与
+ * `estimateMessageTokens` 对 `system` 消息的口径一致（CJK 每字 1，其余字符 / 4）。
+ *
+ * 只用于统计：不写分支、不改请求体，前缀缓存不受影响；压缩阈值也不看它（摘要压不掉这部分）。
+ */
+import type { ToolDecl } from "../ai/types.js";
+import type { ContextEstimate } from "./estimate.js";
+/** 系统提示（已装配的命名节）+ 工具声明的估算。 */
+export declare function estimatePrefixTokens(sections: Readonly<Record<string, string>>, tools: readonly ToolDecl[]): number;
+/** 上下文估算的来源（`SessionStats.context.source`）。 */
+export type ContextSource = "usage" | "estimate" | "prefix";
+export interface SourcedEstimate extends ContextEstimate {
+    source: ContextSource;
+}
+/**
+ * 给投影估算标来源；投影里还没有系统消息时把前缀基线加进去（`prefix` 懒算，只在需要时调用）。
+ * 有 usage 时照旧（usage 已经包含系统提示与工具表）。
+ */
+export declare function withPrefixBaseline(estimate: ContextEstimate, hasSystemMessage: boolean, prefix: () => number): SourcedEstimate;

package/dist/compaction/prefix-estimate.js

@@ -0,0 +1,34 @@
+/**
+ * 启动基线：系统消息落盘之前（第一次请求前）的上下文估算。
+ *
+ * 系统提示与工具表在第一次请求前才作为首条 `system` 消息写进分支，在此之前投影里没有它们，
+ * 状态栏会一直显示 0。这里按「将要发送的那一份」估算：命名节文本 + 工具声明 JSON，与
+ * `estimateMessageTokens` 对 `system` 消息的口径一致（CJK 每字 1，其余字符 / 4）。
+ *
+ * 只用于统计：不写分支、不改请求体，前缀缓存不受影响；压缩阈值也不看它（摘要压不掉这部分）。
+ */
+import { estimateMessageTokens } from "./estimate.js";
+/** 系统提示（已装配的命名节）+ 工具声明的估算。 */
+export function estimatePrefixTokens(sections, tools) {
+    const message = { role: "system", sections: { ...sections }, timestamp: 0 };
+    if (tools.length > 0)
+        message.toolsAdded = [...tools];
+    return estimateMessageTokens(message);
+}
+/**
+ * 给投影估算标来源；投影里还没有系统消息时把前缀基线加进去（`prefix` 懒算，只在需要时调用）。
+ * 有 usage 时照旧（usage 已经包含系统提示与工具表）。
+ */
+export function withPrefixBaseline(estimate, hasSystemMessage, prefix) {
+    if (estimate.usageTokens > 0)
+        return { ...estimate, source: "usage" };
+    if (hasSystemMessage)
+        return { ...estimate, source: "estimate" };
+    const base = prefix();
+    return {
+        ...estimate,
+        tokens: estimate.tokens + base,
+        trailingTokens: estimate.trailingTokens + base,
+        source: "prefix",
+    };
+}

package/dist/config/auth-file.js

@@ -6,7 +6,8 @@
  * - 本模块只搬运字符串，不解析 `!command` / `$ENV`（那是 ai/providers/auth.ts 的事），
  *   也不把 key 写进任何日志或返回给展示层（`describeAuthFile` 只给来源与形态）。
  */
-import { chmodSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { retryTransientFs } from "./fs-retry.js";
 import { dirname, join } from "node:path";
 import { loadConfigFile } from "./load.js";
 import { AUTH_FILE } from "./paths.js";
@@ -54,7 +55,14 @@ export function writeAuthFile(path, file) {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
     writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
-    renameSync(tmp, path);
+    try {
+        // Windows：别的 ama 进程正读着 auth.json 时覆盖它会暂时失败
+        retryTransientFs(() => renameSync(tmp, path));
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
     if (process.platform !== "win32")
         chmodSync(path, 0o600);
 }

package/dist/config/fs-retry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Windows 上的暂时性文件错误（多个 ama 进程同时读写 auth.json 时）。
+ *
+ * NTFS 上文件被删除后、最后一个句柄关闭前处于「删除挂起」：此时 `open(wx)` 报 EPERM 而不是 EEXIST；
+ * 目标文件正被别的进程读时 `rename` 覆盖它会报 EPERM / EACCES / EBUSY。这些都是瞬时的，稍等重试即可。
+ * 其它平台上同样的错误码是真的权限问题，原样抛出。
+ */
+/** 这个错误码在当前平台上是不是「别的进程正占着，稍后再试」。 */
+export declare function isTransientFsError(code: unknown, platform?: string): boolean;
+export interface FsRetryOptions {
+    platform?: string;
+    attempts?: number;
+    /** 第 n 次重试前等 `delayMs * n`。 */
+    delayMs?: number;
+    sleep?: (ms: number) => void;
+}
+/** 执行 `fn`；Windows 的暂时性错误按递增间隔重试（缺省 8 次，共约 0.7 s），其它错误立即抛出。 */
+export declare function retryTransientFs<T>(fn: () => T, options?: FsRetryOptions): T;

package/dist/config/fs-retry.js

@@ -0,0 +1,33 @@
+/**
+ * Windows 上的暂时性文件错误（多个 ama 进程同时读写 auth.json 时）。
+ *
+ * NTFS 上文件被删除后、最后一个句柄关闭前处于「删除挂起」：此时 `open(wx)` 报 EPERM 而不是 EEXIST；
+ * 目标文件正被别的进程读时 `rename` 覆盖它会报 EPERM / EACCES / EBUSY。这些都是瞬时的，稍等重试即可。
+ * 其它平台上同样的错误码是真的权限问题，原样抛出。
+ */
+const TRANSIENT_WIN32 = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** 这个错误码在当前平台上是不是「别的进程正占着，稍后再试」。 */
+export function isTransientFsError(code, platform = process.platform) {
+    return platform === "win32" && typeof code === "string" && TRANSIENT_WIN32.has(code);
+}
+/** 同步睡眠（只用在重试之间，最长几十毫秒）。 */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** 执行 `fn`；Windows 的暂时性错误按递增间隔重试（缺省 8 次，共约 0.7 s），其它错误立即抛出。 */
+export function retryTransientFs(fn, options = {}) {
+    const attempts = options.attempts ?? 8;
+    const delayMs = options.delayMs ?? 20;
+    const sleep = options.sleep ?? sleepSync;
+    for (let n = 1;; n++) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            const code = error.code;
+            if (n >= attempts || !isTransientFsError(code, options.platform))
+                throw error;
+            sleep(delayMs * n);
+        }
+    }
+}

package/dist/config/json-schema.js

@@ -281,6 +281,7 @@ function buildBaseSchema() {
                 animation: bool(),
                 restoreOnCancel: bool(),
                 enterWhileRunning: oneOf(["queue", "interrupt"]),
+                programStatus: oneOf(["auto", "on", "off"]),
                 statusLine: oneOf(STATUS_LINE_MODES),
                 language: oneOf(LANGUAGE_SETTINGS),
                 replyLanguage: str(),

package/dist/config/key-docs.js

@@ -29,6 +29,7 @@ const IMPLICIT_DEFAULTS = {
         animation: true,
         restoreOnCancel: true,
         enterWhileRunning: "queue",
+        programStatus: "auto",
         language: "auto",
     },
     // [W6-C0] 第六波键的缺省（行为由各批次实现）

package/dist/config/schema.js

@@ -261,6 +261,7 @@ export function validateConfig(value) {
         "animation",
         "restoreOnCancel",
         "enterWhileRunning",
+        "programStatus",
         ...W5_UI_KEYS,
         ...W6_UI_KEYS,
     ], (s, p) => {
@@ -275,6 +276,7 @@ export function validateConfig(value) {
         c.boolean(s, "animation", p);
         c.boolean(s, "restoreOnCancel", p);
         c.oneOf(s, "enterWhileRunning", p, ["queue", "interrupt"]);
+        c.oneOf(s, "programStatus", p, ["auto", "on", "off"]);
         checkUiW5(c, s, p);
         checkUiW6(c, s, p);
     });

package/dist/config/settings-registry.js

@@ -35,6 +35,7 @@ const ROWS = [
     row("ui.statusLine", "ui", "now", "any"),
     row("ui.restoreOnCancel", "ui", "nextSession", "any"),
     row("ui.enterWhileRunning", "ui", "now", "any"),
+    row("ui.programStatus", "ui", "restart", "any"),
     row("ui.quietStartup", "ui", "restart", "any"),
     row("ui.ascii", "ui", "restart", "any", { envOverride: "AMA_ASCII" }),
     row("ui.language", "ui", "restart", "any", { envOverride: "AMA_LANG" }),

package/dist/config/types.d.ts

@@ -153,6 +153,8 @@ export interface UiConfig extends UiConfigW6 {
     restoreOnCancel?: boolean;
     /** 运行中按 Enter：queue（缺省）排队插话，interrupt 打断并立即发送（与 `app.message.interrupt` 互换）。 */
     enterWhileRunning?: "queue" | "interrupt";
+    /** 终端程序状态 OSC 7501：auto（缺省）检测通过才发，on 不检测直接发，off 不发。 */
+    programStatus?: "auto" | "on" | "off";
     /** [W5-C0] 底部信息行（W5-A）：缺省独立终端 full、嵌入宿主（有 profile）compact。 */
     statusLine?: StatusLineMode;
 }

package/dist/drivers/native/codex-app-server.js

@@ -83,6 +83,8 @@ class CodexSession {
     tokensTotal;
     tokensAtStart;
     contextWindow;
+    /** 最近一次请求的总量（`tokenUsage.last.totalTokens`）= 线程当前的上下文占用。 */
+    contextTokens;
     closed = false;
     interruptRequested = false;
     constructor(agentId, transport, deps) {
@@ -234,6 +236,7 @@ class CodexSession {
                 input: end.inputTokens - (start?.inputTokens ?? 0),
                 output: end.outputTokens - (start?.outputTokens ?? 0),
                 cacheRead: end.cachedInputTokens - (start?.cachedInputTokens ?? 0),
+                ...(this.contextTokens !== undefined ? { contextTokens: this.contextTokens } : {}),
                 ...(this.contextWindow !== undefined ? { contextWindow: this.contextWindow } : {}),
             });
         }
@@ -257,6 +260,9 @@ class CodexSession {
                 const total = readTokens(usage["total"]);
                 if (total !== undefined)
                     this.tokensTotal = total;
+                const last = readTokens(usage["last"]);
+                if (last !== undefined && last.totalTokens > 0)
+                    this.contextTokens = last.totalTokens;
                 if (typeof usage["modelContextWindow"] === "number")
                     this.contextWindow = usage["modelContextWindow"];
                 return;

package/dist/drivers/runner.js

@@ -161,6 +161,8 @@ class ProcessHandle {
     agent;
     /** [W6-C0] 本回合工具的骨架（id → 种类 / 状态 / 起止），回合结束写 `turn_trace`。 */
     turnTools = new Map();
+    /** 外部 Agent 最近报告的上下文占用与窗口（只记数字，跨回合保留）。 */
+    context = {};
     constructor(runner, chosen, request, deps) {
         this.runner = runner;
         this.chosen = chosen;
@@ -299,6 +301,7 @@ class ProcessHandle {
                 this.emit({ type: "notice", level: event.level, text: event.text });
                 return;
             case "usage":
+                this.noteContext(event.contextTokens, event.contextWindow);
                 if (event.costUsd !== undefined) {
                     turnCost.usd = event.costUsd;
                     const budget = this.request.budgetUsd;
@@ -319,6 +322,19 @@ class ProcessHandle {
                 return;
         }
     }
+    /** 上下文占用或窗口变了：记下并单独发一条只带它们的 usage（任务记录 / Agent 栏即时更新）。 */
+    noteContext(tokens, window) {
+        const next = { ...this.context };
+        if (tokens !== undefined)
+            next.contextTokens = tokens;
+        if (window !== undefined)
+            next.contextWindow = window;
+        if (next.contextTokens === this.context.contextTokens &&
+            next.contextWindow === this.context.contextWindow)
+            return;
+        this.context = next;
+        this.emit({ type: "usage", ...next });
+    }
     now() {
         return (this.deps.now ?? Date.now)();
     }
@@ -412,6 +428,7 @@ class ProcessHandle {
                     unit,
                     amount,
                     ...(usage.totalTokens > 0 ? { tokens: usage.totalTokens } : {}),
+                    ...this.context,
                 });
                 this.emit({ type: "usage", usage, unit, amount });
             }

package/dist/drivers/store.d.ts

@@ -27,6 +27,9 @@ export interface AgentUsageRecord {
     unit: ExternalUsageUnit;
     amount: number;
     tokens?: number;
+    /** 回合结束时该 Agent 报告的上下文占用与窗口（只记数字）。 */
+    contextTokens?: number;
+    contextWindow?: number;
 }
 /** 会话一侧的最小接口（`ToolContext.session` 或 SessionCore 都能提供）。 */
 export interface AgentStoreBackend {

package/dist/drivers/store.js

@@ -75,6 +75,10 @@ export function aggregateExternal(entries) {
         row.amount += u.amount;
         if (typeof u.tokens === "number")
             row.tokens = (row.tokens ?? 0) + u.tokens;
+        if (typeof u.contextTokens === "number")
+            row.contextTokens = u.contextTokens;
+        if (typeof u.contextWindow === "number")
+            row.contextWindow = u.contextWindow;
     }
     return { byAgent };
 }

package/dist/i18n/catalog.d.ts

@@ -541,6 +541,8 @@ declare const en: {
             cacheSilent: string;
             sandbox: string;
             cycleHint: string;
+            autoCompact: string;
+            noWindow: (model: string) => string;
             quota: {
                 session: string;
                 reset: string;
@@ -998,6 +1000,7 @@ declare const en: {
                 interrupted: string;
             };
             turns: (n: number) => string;
+            context: (percent: string) => string;
             agentRunner: (agent: string, runner: string) => string;
             background: string;
             none: string;
@@ -1084,6 +1087,7 @@ declare const en: {
             tools: string;
             hooks: string;
             session: string;
+            context: string;
             cache: string;
             statusline: string;
             planArgs: string;
@@ -1139,6 +1143,50 @@ declare const en: {
             cwdAnswer: string;
             notDirectory: (path: string) => string;
         };
+        contextReport: {
+            title: string;
+            keyUsed: string;
+            used: (tokens: string, window: string, percent: string | undefined) => string;
+            keyLeft: string;
+            left: (tokens: string) => string;
+            keySource: string;
+            sourceUsage: (usage: string, estimate: string) => string;
+            sourceEstimate: string;
+            keyAutoCompact: string;
+            autoCompact: (at: string, distance: string) => string;
+            autoCompactReached: (at: string) => string;
+            autoCompactOff: string;
+            windowUnknown: string;
+            keyPrune: string;
+            prune: (at: string) => string;
+            breakdown: (total: string) => string;
+            prefixCounted: string;
+            prefixPending: string;
+            categories: {
+                system: string;
+                tools: string;
+                user: string;
+                assistant: string;
+                reasoning: string;
+                toolCalls: string;
+                toolResults: string;
+                images: string;
+                summaries: string;
+                custom: string;
+            };
+            partNames: {
+                compaction: string;
+                branch: string;
+                user: string;
+                toolResult: string;
+                custom: string;
+            };
+            images: (count: number) => string;
+            more: (count: number) => string;
+            largest: (count: number) => string;
+            noToolResults: string;
+            empty: string;
+        };
         cache: {
             unreported: string;
             unknown: string;
@@ -1196,6 +1244,8 @@ declare const en: {
             usage: (input: number, output: number, cacheRead: number, cacheWrite: number, cost: string) => string;
             keyContext: string;
             context: (tokens: string, window: string, percent: string) => string;
+            toAutoCompact: (tokens: string) => string;
+            autoCompactOff: string;
             keyAgents: string;
             externalTitle: string;
             noFingerprint: string;
@@ -1333,6 +1383,7 @@ declare const en: {
             "ui.animation": string;
             "ui.restoreOnCancel": string;
             "ui.enterWhileRunning": string;
+            "ui.programStatus": string;
             "ui.statusLine": string;
             "ui.language": string;
             "ui.replyLanguage": string;
@@ -1742,6 +1793,7 @@ declare const en: {
             interrupted: string;
         };
         turns: (n: number) => string;
+        context: (percent: string) => string;
         bar: {
             more: (n: number) => string;
             keys: (up: string, down: string) => string;
@@ -2089,6 +2141,7 @@ declare const en: {
             "ui.statusLine": string;
             "ui.restoreOnCancel": string;
             "ui.enterWhileRunning": string;
+            "ui.programStatus": string;
             "ui.quietStartup": string;
             "ui.ascii": string;
             "ui.language": string;