@armadra/agent 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -5,6 +5,63 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.7.2 (2026-10-09)
+
+- **Prompt cache survives mid-session context changes**: when AGENTS.md, Skills or SessionStart hook output changed on
+  resume, host instructions were refreshed or the memory section was re-rendered after compaction, the changed section
+  used to be folded back into the leading system prompt on endpoints without mid-conversation system messages, so the
+  whole context was billed at full price from token 0. It is now delivered as a `<system-reminder>` user message at the
+  end, and the previous request stays a byte-for-byte prefix; only a patch that removes tools still rewrites the head.
+  DeepSeek accepts a mid-conversation system message but measurably keeps answering from the leading one, so it stays off
+  there (docs/benchmarks/cache-midconvo-2026-10-09.md).
+- **No early pruning on a guessed cache lifetime**: tier-one pruning no longer treats the cache as cold after an implicit
+  10 minutes when the catalog promises no TTL (implicit caches may live for hours); the 10 minutes remain for miss
+  attribution only.
+- **DeepSeek catalog cache data**: `promptCache: { short: 3600, minTokens: 2048 }` (the vendor says unused cache is
+  cleared after a few hours to a few days; reads were measured in 2048-token blocks).
+- **`ama models cache-probe` advice**: without a catalog lifetime it no longer suggests filling in `short: 300`; it
+  explains that ama then neither warms nor prunes early and to fill in only a documented lifetime.
+- **Terminal program status (OSC 7501)**: the interactive interface reports idle / working / blocked (permission,
+  question, auth) / done / error to the terminal with the
+  [Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status), sub-agent tasks as child records
+  `task/<id>`, and clears its records on exit. `ui.programStatus`: `auto` (default, only after the terminal answers the
+  detection query; off inside tmux), `on` (no detection; tmux passthrough), `off`. Detection replies never reach the input
+  box. Print / RPC / ACP modes send nothing.
+- **ACP context usage right away**: `ama --mode acp` now sends `usage_update` after the `session/new`, `session/load`
+  (after the replay) and `session/resume` responses, after a model change and at the end of every assistant message (so
+  multi-tool turns update too), instead of only at the end of a turn; unchanged values are not resent. With an unknown
+  context window there is still no `usage_update` (`size` is required by the schema).
+- **`-p --output-format json` context**: the result object carries `context: { tokens, window, percent }`; unknown items
+  are omitted.
+- **External agents' context**: when an external agent reports its context usage and window (ACP `usage_update`, Codex
+  app-server `tokenUsage`), the numbers go into the task record and `ama.agent-usage`, `getStats().external.byAgent`
+  keeps the latest, and `/tasks` and the Agent bar show `ctx 34%`.
+- **`/context`**: a new command that breaks the context down by category — system prompt (per section), tool
+  declarations (per tool), user messages, assistant text, reasoning, tool-call arguments, tool results (per tool name),
+  images, summaries and custom messages — with estimated tokens, share and a bar each. The top shows used / window, tokens
+  left, the source ("reported usage X + estimated Y" or "estimated in full") and the auto-compact trigger; the bottom
+  lists the largest tool results by ordinal, tool name and size only, never their content. Panel in the TUI, plain text
+  in line mode. Read-only; the request body and cache prefix are unchanged.
+- **Context usage from the start**: before the first request, `contextTokens` is now a baseline estimated from the system
+  prompt and tool declarations that are about to be sent (stats only; nothing is written to the session and the request
+  body is unchanged), so a new session no longer shows `Ctx 0.0%`. `SessionStats.context` (`getStats()`, RPC
+  `get_session_stats`) tells where the number comes from (`usage` / `estimate` / `prefix`) and carries the
+  auto-compaction thresholds `autoCompactAt` / `pruneAt`; absent fields mean "unknown" (docs/sessions.md).
+- **Status bar**: `full` shows `Ctx 3.0% 8.2k/272k auto` (used / window, `auto` while auto-compaction is on; narrow
+  screens drop `auto`, then `/window`, then the used tokens); estimates get a leading `≈`; the warning color starts at
+  the tier-one pruning threshold; `compact` keeps one decimal below 1%. Ctx refreshes right after a message is submitted
+  and, while streaming, follows usage reported by the reply (at most twice a second). The rate line marks billed tokens
+  as the session total `Σ↑ ↓` with cache reads / writes as `R` / `W`. A model without a context window gets a one-time
+  hint on how to set one.
+- **`/session`**: the usage row is labeled as the session total; the context row adds the distance to auto-compaction
+  (or "auto-compaction off") and `≈` for estimates.
+- **Contributing**: the repository now has issue forms (bug report, feature request, provider / model compatibility,
+  documentation), a pull request template, `CONTRIBUTING.md`, `SECURITY.md` and an `AGENTS.md` with the hard constraints
+  and review rules. None of these ship in the npm package.
+- **Docs**: design notes, plans and research reports no longer name the third-party projects they were compared with;
+  those are described generically or by code names. Agents, providers and protocols that ama actually drives or supports
+  keep their names.
+
 ## 0.7.1 (2026-10-05)
 
 - **Windows: concurrent OAuth refresh**: while one ama process releases the `auth.json.lock`, another one opening it

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,40 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.7.2（2026-10-09）
+
+- **会话中途上下文变化不再打断提示缓存**：resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了、宿主 instructions 刷新、压缩后记忆节
+  重新渲染，在不支持对话中途 system 消息的端点上原先会把变化的节并回开头的 system，整段上下文从第 0 个 token 起按全价重读。现在改为在
+  尾部追加一条 `<system-reminder>` 包裹的 user 消息，上一次请求仍是逐字节前缀；只有移除工具的补丁仍改写开头。DeepSeek 接受对话中途的
+  system 消息，但实测模型仍按开头那条回答，所以不为它打开（docs/benchmarks/cache-midconvo-2026-10-09.md）。
+- **不按猜测的缓存寿命提前裁剪**：目录没有承诺 TTL 时，档一裁剪不再按隐式 10 分钟判冷（隐式缓存可能存活数小时）；10 分钟只用于未命中归因。
+- **DeepSeek 目录补缓存信息**：`promptCache: { short: 3600, minTokens: 2048 }`（官方说未使用的缓存「几小时到几天」后清除；缓存读实测按
+  2048 token 一块计）。
+- **`ama models cache-probe` 建议**：目录没有寿命时不再建议自填 `short: 300`，改为说明此时 ama 不保温、不提前裁剪，只有上游文档写明寿命时才填。
+- **终端程序状态（OSC 7501）**：交互界面用 [程序状态协议](https://www.superlogical.com/rex/docs/build/program-status) 把
+  idle / working / blocked（permission、question、auth）/ done / error 报告给终端，子 Agent 任务为子记录 `task/<id>`，退出时清掉记录。
+  `ui.programStatus`：`auto`（缺省，终端回应检测查询后才发；tmux 里不发）、`on`（不检测；tmux 里经 passthrough）、`off`。检测回复不会
+  进输入框。print / RPC / ACP 模式不发。
+- **ACP 立即有上下文用量**：`ama --mode acp` 在 `session/new`、`session/load`（回放之后）、`session/resume` 答复之后、换模型时与每条助手
+  消息结束时都发 `usage_update`（多工具回合中途也更新），不再只在回合结束时发；与上次同值不重发。窗口未知时仍不发（schema 里 `size` 必填）。
+- **`-p --output-format json` 带上下文**：结果对象加 `context: { tokens, window, percent }`，未知项省略。
+- **外部 Agent 的上下文**：外部 Agent 报告了上下文占用与窗口（ACP `usage_update`、Codex app-server `tokenUsage`）时，数字记进任务记录与
+  `ama.agent-usage`，`getStats().external.byAgent` 取最近一次，`/tasks` 与 Agent 栏显示 `ctx 34%`。
+- **`/context`**：新命令，把上下文按类别拆开——系统提示（按节）、工具声明（按工具）、用户消息、助手文本、推理、工具调用参数、
+  工具结果（按工具名汇总）、附件图片、摘要、自定义消息——每类给 token 估算、占比与条形；顶部是已用 / 窗口、剩余、来源（「usage
+  实测 X + 估算 Y」或「全量估算」）与自动压缩触发点，底部只按序号、工具名与大小列出最大的工具结果，不显示正文。交互模式是面板，
+  line 模式是纯文本。统计只读，不改请求体与缓存前缀。
+- **上下文一开始就有数**：第一次请求前，`contextTokens` 改为按即将发送的系统提示 + 工具声明估算的基线（只统计，不写会话、不改请求体），
+  新会话不再显示 `Ctx 0.0%`。`SessionStats.context`（`getStats()`、RPC `get_session_stats`）标明数字来源（`usage` / `estimate` /
+  `prefix`）并给出自动压缩阈值 `autoCompactAt` / `pruneAt`；字段缺省表示「不知道」（docs/sessions.md）。
+- **状态栏**：`full` 显示 `Ctx 3.0% 8.2k/272k auto`（已用量 / 窗口，自动压缩开着时有 `auto`；窄屏先丢 `auto`，再丢 `/窗口`，最后丢已用量）；
+  估算值前加 `≈`；黄色从档一裁剪阈值开始；`compact` 占用 < 1% 时保留一位小数。提交消息后立刻刷新 Ctx，流式中按回复带回的 usage 更新
+  （每秒至多 2 次）。速率行用 `Σ↑ ↓` 标明是会话累计计费量，缓存读写另列 `R` / `W`。模型没有上下文窗口时提示一次怎么补。
+- **`/session`**：用量行注明「累计」；上下文行加上距自动压缩的余量（或「自动压缩关闭」），估算值带 `≈`。
+- **参与贡献**：仓库新增 issue 表单（缺陷报告、功能建议、供应商 / 模型兼容问题、文档问题）、PR 模板、`CONTRIBUTING.md`、
+  `SECURITY.md`，以及写明硬约束与评审规则的 `AGENTS.md`；这些文件都不进 npm 包。
+- **文档**：设计、计划与调研文档不再点名作为参照的第三方项目，改为不具名表述或代号；ama 实际驱动或兼容的外部 Agent、供应商与协议照常写名字。
+
 ## 0.7.1（2026-10-05）
 
 - **Windows：并发刷新 OAuth**：一个 ama 进程刚释放 `auth.json.lock` 时，另一个进程打开它会报 EPERM（NTFS 上文件处于删除挂起），刷新

package/dist/agent/session-cache.d.ts

@@ -82,8 +82,10 @@ export declare class SessionCacheController {
         window?: number | undefined;
     }): SessionCacheStats;
     /**
-     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过 TTL（目录无承诺时按隐式
-     * 10 分钟）。只对 `reported` 端点判断；`silent` / `unknown` 返回 false，档一退化为只按阈值。
+     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过目录承诺的 TTL。
+     * 目录没有承诺 TTL 时返回 false：隐式缓存的寿命可能远长于 10 分钟，按猜测的寿命提前裁剪会改写
+     * 仍然有效的缓存（隐式 600 s 只用于未命中归因）。只对 `reported` 端点判断；`silent` / `unknown`
+     * 返回 false，档一退化为只按阈值。
      */
     isCold(): boolean;
     /**

package/dist/agent/session-cache.js

@@ -299,8 +299,10 @@ export class SessionCacheController {
         return stats;
     }
     /**
-     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过 TTL（目录无承诺时按隐式
-     * 10 分钟）。只对 `reported` 端点判断；`silent` / `unknown` 返回 false，档一退化为只按阈值。
+     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过目录承诺的 TTL。
+     * 目录没有承诺 TTL 时返回 false：隐式缓存的寿命可能远长于 10 分钟，按猜测的寿命提前裁剪会改写
+     * 仍然有效的缓存（隐式 600 s 只用于未命中归因）。只对 `reported` 端点判断；`silent` / `unknown`
+     * 返回 false，档一退化为只按阈值。
      */
     isCold() {
         const prev = this.prev;
@@ -311,7 +313,7 @@ export class SessionCacheController {
         if (this.tracker.get(endpoint, model.compat?.cacheReporting) !== "reported")
             return false;
         const ttl = cacheTtlMs(this.modelOf(prev), prev.options.cacheRetention);
-        return this.now() - prev.at > (ttl ?? IMPLICIT_CACHE_TTL_MS);
+        return ttl !== undefined && this.now() - prev.at > ttl;
     }
     /**
      * 摘要续写的前缀（第三波 §1.8）：当前转录按回合同样的方式转换，且上一次 turn 请求的消息

package/dist/agent/session-compaction.d.ts

@@ -14,6 +14,8 @@
  *   `overflow`，受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
  * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
  * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
+ * - 统计（`contextStats`，供 getStats）：投影估算标来源；系统消息落盘前加系统提示 + 工具声明的前缀基线
+ *   （只统计，不写分支、不改请求）；附档一 / 档二阈值。压缩调度本身仍只看 `estimate()`。
  * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
  * （前缀本身已超窗口）；续写失败回落独立请求并记 warning。
  */
@@ -22,7 +24,7 @@ import { type ContextEstimate } from "../compaction/estimate.js";
 import { type PrunePolicy } from "../compaction/prune-tier.js";
 import type { BranchSummaryEntry } from "../session/types.js";
 import type { SessionCore } from "./session-core.js";
-import type { CompactionResult, CompactionSettings } from "./types.js";
+import type { CompactionResult, CompactionSettings, SessionContextStats } from "./types.js";
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
 /** 保留区不超过 (窗口 − 预留) 的 40%，否则小窗口模型上摘要后仍然溢出。 */
 export declare const KEEP_RECENT_MAX_RATIO = 0.4;
@@ -40,6 +42,16 @@ export declare class CompactionController {
     refresh(): void;
     setAuto(enabled: boolean): void;
     estimate(): ContextEstimate;
+    /**
+     * 统计用的上下文量（`getStats`）：投影估算标上来源；系统消息还没落盘时加上前缀基线（系统提示 +
+     * 工具声明，只统计不写分支）。附自动压缩的两个阈值（自动压缩可用时）。压缩调度仍用 `estimate()`。
+     */
+    contextStats(): {
+        tokens: number;
+        detail: SessionContextStats;
+    };
+    /** 将要发送的系统提示 + 工具声明的估算（与首条 system 消息同样装配，不落盘）。 */
+    private prefixTokens;
     private budget;
     private keepRecent;
     /** 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料。 */

package/dist/agent/session-compaction.js

@@ -14,18 +14,22 @@
  *   `overflow`，受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
  * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
  * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
+ * - 统计（`contextStats`，供 getStats）：投影估算标来源；系统消息落盘前加系统提示 + 工具声明的前缀基线
+ *   （只统计，不写分支、不改请求）；附档一 / 档二阈值。压缩调度本身仍只看 `estimate()`。
  * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
  * （前缀本身已超窗口）；续写失败回落独立请求并记 warning。
  */
 import { AmaError } from "../errors.js";
 import { CompactionBreaker } from "../compaction/breaker.js";
 import { estimateMessageTokens, estimateProjectedTokens, } from "../compaction/estimate.js";
+import { estimatePrefixTokens, withPrefixBaseline } from "../compaction/prefix-estimate.js";
 import { planPrune, prunePolicy } from "../compaction/prune-tier.js";
 import { createProtection, skillLocations } from "../compaction/protect.js";
 import { buildPostCompactBlock } from "../compaction/post-compact.js";
 import { prepareCompaction, prepareCompactionAt, runCompaction, } from "../compaction/summarize-tier.js";
 import { prepareBranchSummary, runBranchSummary } from "../compaction/branch-summary.js";
 import { buildProjection } from "../session/projection.js";
+import { assembleSections, definedSections, toolDecls } from "./system-prompt.js";
 export const DEFAULT_COMPACTION_SETTINGS = {
     enabled: true,
     reserveTokens: 16_384,
@@ -69,6 +73,38 @@ export class CompactionController {
         const branch = this.core.manager.branch();
         return estimateProjectedTokens(buildProjection(branch).items, branch);
     }
+    /**
+     * 统计用的上下文量（`getStats`）：投影估算标上来源；系统消息还没落盘时加上前缀基线（系统提示 +
+     * 工具声明，只统计不写分支）。附自动压缩的两个阈值（自动压缩可用时）。压缩调度仍用 `estimate()`。
+     */
+    contextStats() {
+        const branch = this.core.manager.branch();
+        const items = buildProjection(branch).items;
+        const sourced = withPrefixBaseline(estimateProjectedTokens(items, branch), items.some((item) => item.message.role === "system"), () => this.prefixTokens());
+        const detail = {
+            source: sourced.source,
+            usageTokens: sourced.usageTokens,
+            trailingTokens: sourced.trailingTokens,
+        };
+        const budget = this.budget();
+        const policy = this.prunePolicy();
+        if (this.breaker.autoEnabled && budget !== undefined && policy !== undefined) {
+            detail.autoCompactAt = budget;
+            detail.pruneAt = Math.floor(policy.triggerTokens);
+        }
+        return { tokens: sourced.tokens, detail };
+    }
+    /** 将要发送的系统提示 + 工具声明的估算（与首条 system 消息同样装配，不落盘）。 */
+    prefixTokens() {
+        const core = this.core;
+        const tools = core
+            .activeToolNames()
+            .map((name) => core.activeTool(name))
+            .filter((tool) => tool !== undefined);
+        const system = core.childBase?.().system ?? core.options.system ?? {};
+        const sections = definedSections(assembleSections({ ...system, tools, cwd: core.cwd }));
+        return estimatePrefixTokens(sections, toolDecls(tools));
+    }
     budget() {
         const window = this.core.model().contextWindow;
         return window === undefined ? undefined : Math.max(0, window - this.settings.reserveTokens);

package/dist/agent/session-core.d.ts

@@ -130,6 +130,8 @@ export interface SessionCore {
     /** 任一已登记工具（不限于活动集；嵌套调用用）。 */
     tool(name: string): ToolDefinition | undefined;
     activeToolNames(): string[];
+    /** 当前的系统提示静态部分（`updateSystem` 之后的；统计启动基线用）。缺省时用 `options.system`。 */
+    childBase?(): Pick<AgentSessionOptions, "system">;
     runHook(event: HookEvent, payload: HookEventPayload, signal?: AbortSignal): Promise<HookOutcome | undefined>;
     /** Hook 返回 continue:false 时记下，finishTurn 据此结束 run。 */
     requestStop(reason: string | undefined): void;

package/dist/agent/session-state.d.ts

@@ -3,14 +3,15 @@
  *
  * 统计口径：活动分支上的全部条目（不是投影）——被压缩 / 剔除的消息仍计入用量与成本；
  * 压缩与分支摘要请求的 usage 也计入；`usage` 条目（缓存保温等不进上下文的请求，第三波 §1.7）
- * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）。
+ * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）；`context` 标明估算来源（usage / 全量估算 /
+ * 启动前缀基线）与自动压缩阈值。
  */
 import type { Model, ModelThinkingLevel } from "../ai/types.js";
 import type { PermissionMode } from "../permissions/types.js";
 import type { SessionManager } from "../session/manager.js";
 import type { SessionEntry } from "../session/types.js";
 import type { Agent } from "./agent.js";
-import type { SessionCacheStats, SessionState, SessionStats } from "./types.js";
+import type { SessionCacheStats, SessionContextStats, SessionState, SessionStats } from "./types.js";
 import type { QuotaUpdateEvent } from "./types-w6.js";
 export interface StateInput {
     agent: Agent;
@@ -28,7 +29,12 @@ export interface StatsInput {
     sessionId: string;
     sessionFile: string | undefined;
     branch: readonly SessionEntry[];
-    contextTokens: number | undefined;
+    contextTokens?: number | undefined;
+    /** 会话的上下文估算（CompactionController.contextStats，含来源与阈值）；给了以它的 tokens 为准。 */
+    context?: {
+        tokens: number;
+        detail: SessionContextStats;
+    };
     contextWindow: number | undefined;
     /** [W3-C1b] 会话层缓存控制器的统计（未接线时缺省）。 */
     cache?: SessionCacheStats;

package/dist/agent/session-state.js

@@ -3,7 +3,8 @@
  *
  * 统计口径：活动分支上的全部条目（不是投影）——被压缩 / 剔除的消息仍计入用量与成本；
  * 压缩与分支摘要请求的 usage 也计入；`usage` 条目（缓存保温等不进上下文的请求，第三波 §1.7）
- * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）。
+ * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）；`context` 标明估算来源（usage / 全量估算 /
+ * 启动前缀基线）与自动压缩阈值。
  */
 import { modelRefOf } from "../ai/providers/channels.js";
 export function buildSessionState(input) {
@@ -87,11 +88,10 @@ export function computeStats(input) {
             addCost(entry.usage);
         }
     }
-    const contextPercent = input.contextWindow === undefined ||
-        input.contextTokens === undefined ||
-        input.contextWindow <= 0
+    const contextTokens = input.context?.tokens ?? input.contextTokens;
+    const contextPercent = input.contextWindow === undefined || contextTokens === undefined || input.contextWindow <= 0
         ? undefined
-        : Math.min(100, Math.round((input.contextTokens / input.contextWindow) * 1000) / 10);
+        : Math.min(100, Math.round((contextTokens / input.contextWindow) * 1000) / 10);
     const stats = {
         sessionId: input.sessionId,
         sessionFile: input.sessionFile,
@@ -101,10 +101,12 @@ export function computeStats(input) {
         toolResults,
         tokens,
         cost,
-        contextTokens: input.contextTokens,
+        contextTokens,
         contextWindow: input.contextWindow,
         contextPercent,
     };
+    if (input.context !== undefined)
+        stats.context = { ...input.context.detail };
     const rate = cacheHitRate(tokens);
     if (rate !== undefined)
         stats.cacheHitRate = rate;

package/dist/agent/session.js

@@ -445,15 +445,15 @@ export class AgentSessionImpl {
         return lastAssistantText(this.manager.branch());
     }
     getStats() {
-        const contextTokens = this.compaction.estimate().tokens;
+        const context = this.compaction.contextStats();
         const contextWindow = this.settings.model.contextWindow;
         const stats = computeStats({
             sessionId: this.manager.id,
             sessionFile: this.manager.file(),
             branch: this.manager.branch(),
-            contextTokens,
+            context,
             contextWindow,
-            cache: this.cache.stats({ tokens: contextTokens, window: contextWindow }),
+            cache: this.cache.stats({ tokens: context.tokens, window: contextWindow }),
             quota: this.lastQuota,
         });
         return this.extensions.contributeStats(stats);

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

@@ -179,6 +179,9 @@ export interface ExternalAgentStats {
         unit: ExternalUsageUnit;
         amount: number;
         tokens?: number;
+        /** 最近一次报告的上下文占用与窗口（token）；驱动不报时缺省。 */
+        contextTokens?: number;
+        contextWindow?: number;
     }>;
 }
 /** 子 Agent 任务注册表的汇总（`/session` 与 `get_session_stats`）。 */

package/dist/agent/types.d.ts

@@ -356,6 +356,8 @@ export interface SessionStats extends SessionStatsW5, SessionStatsW6 {
     contextWindow: number | undefined;
     /** 0–100；无窗口时 undefined（显示 `ctx ?`）。 */
     contextPercent: number | undefined;
+    /** 上下文用量的来源与压缩阈值（`contextTokens` 怎么来的）；旧实现与测试替身可缺省。 */
+    context?: SessionContextStats;
     /**
      * 缓存命中率 0–1 = cacheRead /（input + cacheRead + cacheWrite）（设计 §9.1）；
      * 还没有任何输入用量时不给。
@@ -364,6 +366,22 @@ export interface SessionStats extends SessionStatsW5, SessionStatsW6 {
     /** [W3-C0] 缓存可观测性（第三波 §1.10）；会话层缓存控制器（C1b）未接线时缺省。 */
     cache?: SessionCacheStats;
 }
+/**
+ * `SessionStats.context`：`contextTokens` 的来源与自动压缩阈值（只统计，不改请求）。
+ * - `usage`：最后一条有效助手消息的 usage（`usageTokens`）+ 其后消息的估算（`trailingTokens`）；
+ * - `estimate`：没有可信的 usage（压缩 / 上下文编辑之后、新 usage 到来之前，或从未有 usage），按投影全量估算；
+ * - `prefix`：系统消息还没落盘（第一次请求前），用当前系统提示 + 工具声明估算的基线加上已有消息的估算。
+ * 后两种 `usageTokens` 为 0、`trailingTokens` 等于 `contextTokens`。
+ */
+export interface SessionContextStats {
+    source: "usage" | "estimate" | "prefix";
+    usageTokens: number;
+    trailingTokens: number;
+    /** 档二自动摘要的阈值（窗口 − reserveTokens）；自动压缩关闭、熔断或窗口未知时缺省。 */
+    autoCompactAt?: number;
+    /** 档一裁剪的阈值（0.7 ×（窗口 − reserveTokens））；缺省条件同上。 */
+    pruneAt?: number;
+}
 /** [W3-C0] `SessionStats.cache`（`get_session_stats` / `/session` / `-p --output-format json`）。 */
 export interface SessionCacheStats {
     /** 当前端点的三态。 */

package/dist/agents/task-record.d.ts

@@ -150,6 +150,10 @@ export interface ProgressSink {
 export declare function flushText(record: TaskRecord, sink: ProgressSink): void;
 /** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */
 export declare function applyRunnerEvent(record: TaskRecord, event: SubagentEvent, sink: ProgressSink): void;
+/** 任务的上下文占用（0–100，一位小数，封顶 100）；占用或窗口未知时 undefined。 */
+export declare function taskContextPercent(info: Pick<TaskInfo, "contextTokens" | "contextWindow">): number | undefined;
+/** 上下文占用的显示：≥ 10% 取整，以下保留一位小数（`34%`、`0.4%`）；未知时 undefined。 */
+export declare function formatTaskContext(info: Pick<TaskInfo, "contextTokens" | "contextWindow">): string | undefined;
 /** `subagent_start` 事件（新开或续聊都发）。 */
 export declare function startEvent(record: TaskRecord, handle: TaskHandle): SubagentStartEvent;
 /** `getStats().tasks`：没有任务时 undefined。 */

package/dist/agents/task-record.js

@@ -163,6 +163,10 @@ export function applyRunnerEvent(record, event, sink) {
                 record.info.usage = event.usage;
             if (event.unit === "usd" && event.amount !== undefined)
                 record.info.costUsd = event.amount;
+            if (event.contextTokens !== undefined)
+                record.info.contextTokens = event.contextTokens;
+            if (event.contextWindow !== undefined)
+                record.info.contextWindow = event.contextWindow;
             return;
         case "notice":
             sink.log(event.level, `[task ${taskId}] ${event.text}`);
@@ -209,6 +213,20 @@ function recordDisplay(record, event, now) {
             return;
     }
 }
+/** 任务的上下文占用（0–100，一位小数，封顶 100）；占用或窗口未知时 undefined。 */
+export function taskContextPercent(info) {
+    const { contextTokens: used, contextWindow: size } = info;
+    if (used === undefined || size === undefined || size <= 0)
+        return undefined;
+    return Math.min(100, Math.round((used / size) * 1000) / 10);
+}
+/** 上下文占用的显示：≥ 10% 取整，以下保留一位小数（`34%`、`0.4%`）；未知时 undefined。 */
+export function formatTaskContext(info) {
+    const percent = taskContextPercent(info);
+    if (percent === undefined)
+        return undefined;
+    return `${percent >= 10 ? Math.round(percent) : percent.toFixed(1)}%`;
+}
 /** `subagent_start` 事件（新开或续聊都发）。 */
 export function startEvent(record, handle) {
     const event = {

package/dist/ai/context.d.ts

@@ -2,8 +2,11 @@
  * normalizeContext（设计 §1.2 ai/context.ts）：把循环交来的转录（含 `system` 补丁消息）变成
  * 协议可直接拼请求体的形状。
  *
- * - system 折叠：按出现顺序重放全部 system 消息的 `sections`（节名级替换，null 删除），得到
- *   `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - system 折叠：首条非 system 消息之前的 system 消息按出现顺序重放（节名级替换，null 删除），
+ *   得到 `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - 中途节补丁（设计 §9.1「会话中途变化的上下文只追加」）：对话开始之后的 system 补丁不改写开头，
+ *   渲染成 `<system-reminder>` 包裹的 user 消息按位置插回，开头与之前的消息逐字节不变；
+ *   例外是补丁移除了工具——工具表本身已变、前缀必然失效，这时全部补丁照旧折回开头；
  * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
  * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
  *
@@ -18,6 +21,8 @@ export interface NormalizeOptions {
 }
 export declare const IMAGE_OMITTED_TEXT = "[image omitted: the model does not accept image input]";
 export declare function normalizeContext(context: TranscriptContext, options?: NormalizeOptions): NormalizedContext;
+/** 中途节补丁作为尾部上下文消息送达时的文本（固定英文，与界面语言无关）。 */
+export declare function systemReminderText(updates: readonly string[]): string;
 /** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
 export declare function renderSystemUpdate(message: SystemMessage): string;
 export interface InlineSystemUpdate {

package/dist/ai/context.js

@@ -2,8 +2,11 @@
  * normalizeContext（设计 §1.2 ai/context.ts）：把循环交来的转录（含 `system` 补丁消息）变成
  * 协议可直接拼请求体的形状。
  *
- * - system 折叠：按出现顺序重放全部 system 消息的 `sections`（节名级替换，null 删除），得到
- *   `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - system 折叠：首条非 system 消息之前的 system 消息按出现顺序重放（节名级替换，null 删除），
+ *   得到 `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - 中途节补丁（设计 §9.1「会话中途变化的上下文只追加」）：对话开始之后的 system 补丁不改写开头，
+ *   渲染成 `<system-reminder>` 包裹的 user 消息按位置插回，开头与之前的消息逐字节不变；
+ *   例外是补丁移除了工具——工具表本身已变、前缀必然失效，这时全部补丁照旧折回开头；
  * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
  * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
  *
@@ -55,16 +58,51 @@ function allowsImages(options) {
     return options?.model === undefined || options.model.input.includes("image");
 }
 export function normalizeContext(context, options) {
-    const state = new SystemState();
+    const head = new SystemState();
+    const tools = new SystemState();
     const messages = [];
     const allowImages = allowsImages(options);
+    const fold = removesToolsMidway(context.messages);
+    let pending = [];
+    const flush = () => {
+        if (pending.length === 0)
+            return;
+        messages.push({ role: "user", content: systemReminderText(pending), timestamp: 0 });
+        pending = [];
+    };
     for (const message of context.messages) {
-        if (message.role === "system")
-            state.apply(message);
-        else
+        if (message.role !== "system") {
+            flush();
             messages.push(filterMessage(message, allowImages));
+            continue;
+        }
+        tools.apply(message);
+        if (fold || messages.length === 0) {
+            head.apply(message);
+            continue;
+        }
+        const text = renderSystemUpdate(message);
+        if (text.length > 0)
+            pending.push(text);
     }
-    return { ...state.snapshot(), messages };
+    flush();
+    return { ...head.snapshot(), tools: tools.snapshot().tools, messages };
+}
+/** 对话开始之后有补丁移除了工具（这时整段前缀必然失效，补丁全部折回开头）。 */
+function removesToolsMidway(transcript) {
+    let started = false;
+    for (const message of transcript) {
+        if (message.role !== "system")
+            started = true;
+        else if (started && (message.toolsRemoved?.length ?? 0) > 0)
+            return true;
+    }
+    return false;
+}
+/** 中途节补丁作为尾部上下文消息送达时的文本（固定英文，与界面语言无关）。 */
+export function systemReminderText(updates) {
+    return (`<system-reminder>\n${updates.join("\n\n")}\n\n` +
+        "These updates replace the earlier versions of those system prompt sections.\n</system-reminder>");
 }
 /** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
 export function renderSystemUpdate(message) {

package/dist/ai/providers/catalog-data.js

@@ -6,7 +6,7 @@ export const CATALOG_SOURCES = {
     anthropic: '{"version":1,"provider":"anthropic","modelsDev":"anthropic","models":[{"id":"claude-fable-5-1","thinkingLevelMap":{"off":null,"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":512},"compat":{"adaptiveThinking":true}},{"id":"claude-fable-5","thinkingLevelMap":{"off":null,"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":512},"compat":{"adaptiveThinking":true}},{"id":"claude-opus-5-5","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":512},"compat":{"adaptiveThinking":true}},{"id":"claude-opus-5","thinkingLevelMap":{"off":null,"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":512},"compat":{"adaptiveThinking":true}},{"id":"claude-opus-4-8","thinkingLevelMap":{"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":1024},"compat":{"adaptiveThinking":true}},{"id":"claude-opus-4-7","thinkingLevelMap":{"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":2048},"compat":{"adaptiveThinking":true}},{"id":"claude-opus-4-6","promptCache":{"short":300,"long":3600,"minTokens":4096},"compat":{"adaptiveThinking":true}},{"id":"claude-sonnet-5-5","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":512},"compat":{"adaptiveThinking":true}},{"id":"claude-sonnet-5","thinkingLevelMap":{"xhigh":"xhigh"},"promptCache":{"short":300,"long":3600,"minTokens":1024},"compat":{"adaptiveThinking":true}},{"id":"claude-sonnet-4-6","promptCache":{"short":300,"long":3600,"minTokens":1024},"compat":{"adaptiveThinking":true}},{"id":"claude-sonnet-4-5","promptCache":{"short":300,"long":3600,"minTokens":1024}},{"id":"claude-haiku-4-5","promptCache":{"short":300,"long":3600,"minTokens":4096}},{"id":"claude-opus-4-5","promptCache":{"short":300,"long":3600,"minTokens":4096}}]}',
     chatgpt: '{"version":1,"provider":"chatgpt","modelsDev":false,"models":[]}',
     dashscope: '{"version":1,"provider":"dashscope","modelsDev":"alibaba-cn","models":[{"id":"qwen3.8-max","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":null,"xhigh":"xhigh"},"compat":{"supportsReasoningEffort":true}},{"id":"qwen3.8-flash","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":null,"xhigh":"xhigh"},"compat":{"supportsReasoningEffort":true}},{"id":"qwen3.7-max","maxTokens":131072,"compat":{"supportsReasoningEffort":false}},{"id":"qwen3.7-plus","maxTokens":65536,"compat":{"supportsReasoningEffort":false}},{"id":"qwen3.6-plus","compat":{"supportsReasoningEffort":false}},{"id":"qwen3.6-flash","compat":{"supportsReasoningEffort":false}}]}',
-    deepseek: '{"version":1,"provider":"deepseek","modelsDev":"deepseek","models":[{"id":"deepseek-v4-pro","maxTokens":384000,"cost":{"input":1.32,"output":3.96,"cacheRead":0.044},"thinkingLevelMap":{"minimal":null,"low":null,"medium":null,"high":"high"},"_reason":"按官方价格页的高峰价（UTC 工作日 01–04、06–10 时）计，作上界；平峰为半价。快照价是平峰价或旧价"},{"id":"deepseek-flash","maxTokens":384000,"cost":{"input":0.3,"output":1.2,"cacheRead":0.006},"thinkingLevelMap":{"minimal":null,"low":"low","medium":null,"high":"high"},"_reason":"按官方价格页的高峰价（UTC 工作日 01–04、06–10 时）计，作上界；平峰为半价。快照价是平峰价或旧价"}]}',
+    deepseek: '{"version":1,"provider":"deepseek","modelsDev":"deepseek","models":[{"id":"deepseek-v4-pro","maxTokens":384000,"cost":{"input":1.32,"output":3.96,"cacheRead":0.044},"thinkingLevelMap":{"minimal":null,"low":null,"medium":null,"high":"high"},"_reason":"按官方价格页的高峰价（UTC 工作日 01–04、06–10 时）计，作上界；平峰为半价。快照价是平峰价或旧价","promptCache":{"short":3600,"minTokens":2048}},{"id":"deepseek-flash","maxTokens":384000,"cost":{"input":0.3,"output":1.2,"cacheRead":0.006},"thinkingLevelMap":{"minimal":null,"low":"low","medium":null,"high":"high"},"_reason":"按官方价格页的高峰价（UTC 工作日 01–04、06–10 时）计，作上界；平峰为半价。快照价是平峰价或旧价","promptCache":{"short":3600,"minTokens":2048}}]}',
     google: '{"version":1,"provider":"google","modelsDev":"google","models":[{"id":"gemini-3.8-flash","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-3.7-flash","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-3.5-flash","thinkingLevelMap":{"off":null,"minimal":"minimal","low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-3.5-flash-lite","thinkingLevelMap":{"off":null,"minimal":"minimal","low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-3.1-pro-preview","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-3-flash-preview","thinkingLevelMap":{"off":null,"minimal":"minimal","low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"gemini-2.5-pro","thinkingLevelMap":{"off":null,"minimal":128,"low":2048,"medium":8192,"high":32768}},{"id":"gemini-2.5-flash","thinkingLevelMap":{"minimal":128,"low":2048,"medium":8192,"high":24576}},{"id":"gemini-2.5-flash-lite","thinkingLevelMap":{"minimal":512,"low":2048,"medium":8192,"high":24576}}]}',
     groq: '{"version":1,"provider":"groq","modelsDev":"groq","models":[{"id":"openai/gpt-oss-120b","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"openai/gpt-oss-20b","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"openai/gpt-oss-safeguard-20b","thinkingLevelMap":{"off":null,"minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"qwen/qwen3.8-27b","thinkingLevelMap":{"off":"none","minimal":null,"low":"low","medium":"medium","high":"high","xhigh":null}},{"id":"qwen/qwen3.6-27b","thinkingLevelMap":{"off":"none","minimal":null,"low":null,"medium":null,"high":"default","xhigh":null}},{"id":"llama-3.3-70b-versatile"},{"id":"llama-3.1-8b-instant"}]}',
     lmstudio: '{"version":1,"provider":"lmstudio","modelsDev":false,"models":[]}',