@armadra/agent 0.7.3 → 0.7.5

package/docs/session-format.md

@@ -49,7 +49,7 @@
 
 - `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → memory → hooks → cwd → host → role`；`memory` 是第六波的记忆索引节，未开启记忆时不出现）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装：首条非 system 消息之前的部分折进开头，之后的节补丁作为尾部上下文送达、不改写开头（移除工具的补丁除外，见 [providers.md](providers.md)「缓存」）。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
 - `user`：`content`、`origin?`（缺省 = 普通用户输入；`steer` / `followUp` 是运行中插话与排队，`host` 是宿主 `sendUser` 注入，`interrupt` 是打断并立即发送开的新回合（TUI `Ctrl+X`、line 模式 `/interrupt`、RPC / SDK 的 `interrupt: true`；投影与普通 user 消息相同），`direct` 是用户在子 Agent 视图里直接发给该子 Agent 的消息（第六波 W6-A，写在子会话里；投影与普通 user 消息相同），其它字符串原样记录）。
-- `assistant`：`content`（文本 / 思考 / 工具调用块）、`api`、`provider`、`model`、`usage`、`stopReason`，以及可选的 `responseId`、`thinkingLevel`、`providerThinkingLevel`、`rawStopReason`、`errorMessage`。`usage` 是 `{ input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost?, cacheReported? }`：`input` 不含缓存部分，`cost` 是 `{ input, output, cacheRead, cacheWrite, total }`（美元，模型无价格时缺省），`cacheReported` 表示原始响应里出现过缓存字段。
+- `assistant`：`content`（文本 / 思考 / 工具调用块）、`api`、`provider`、`model`、`usage`、`stopReason`，以及可选的 `responseId`、`thinkingLevel`、`providerThinkingLevel`、`rawStopReason`、`errorMessage`、`retryAfterMs`（失败响应的 `Retry-After`，毫秒；会话层退避取它与指数退避中的较大值）。工具调用块是 `{ type: "toolCall", id, name, arguments, thoughtSignature?, rawArguments? }`：`rawArguments` 是模型输出的原始参数字符串（能严格解析为 JSON 时才记），同协议回放时原样发回，没有时回落 `JSON.stringify(arguments)`。两者都是可选字段，格式版本不变，旧文件照常读取。`usage` 是 `{ input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost?, cacheReported? }`：`input` 不含缓存部分，`cost` 是 `{ input, output, cacheRead, cacheWrite, total }`（美元，模型无价格时缺省），`cacheReported` 表示原始响应里出现过缓存字段。
 - `toolResult`：对应工具调用的结果（`toolCallId`、`toolName`、`content`、`isError`、`details?`）。
 
 ### `usage` 条目
@@ -97,7 +97,17 @@
 
 - `/tree`：同一文件换叶子（落 `leaf` 行）；从旧位置再发消息就形成新分支。离开的分支可以写 `branch_summary` 带进新分支。
 - fork（`--fork <id>`、`/fork`、RPC `fork`）：把根 → 指定条目的分支复制到新文件，头的 `parentSession` 指回原文件；不复制 `leaf` 行。
-- `task` 子会话：独立文件，头带 `parentSession`，首条条目是 `custom{customType:"ama.task"}`。
+- `task` 子会话：独立文件，头带 `parentSession`，首条条目是 `custom{customType:"ama.task"}`。fork 式子会话（`task.context: "fork"`）同样如此：父会话分支被复制到新文件，首条 `ama.task` 作为新根条目，复制的首条重挂到它下面（`data.context: "fork"`、`data.forkedFrom` = 复制到的父条目 id）。
+
+## 内存表示
+
+文件格式与上面完全一致；以下只是 `SessionManager` 在内存里的取舍（#170）。已落盘的会话里，**活动分支上被活动分支上的 `context_edit`（任何 reason）改写的 `message` 条目**不再进上下文，它的图片块在内存里换成 `data: ""` 的占位（`mimeType` 保留），只记该行在文件中的位置，需要原文时按位置读回一行：
+
+- `entries()` / `branch()` / `getEntry()` 与 SDK 的 `session.entries` 返回占位版本；投影不受影响（被改写的条目本来就用替换文本）。
+- RPC `get_entries`（`getEntries()`）与 fork 从文件读回原文，fork 出的文件含全部 base64。
+- 换叶子（`/tree`、rewind 回到编辑之前）后，不再被生效编辑改写的条目就地回读，之前拿到的同一消息对象也随之恢复；回到编辑之后再次卸载。打开文件时先扫一遍 `context_edit` 行，读到被改写的条目时随即剥掉图片，峰值不含这些旧图。
+- 内存会话（`inMemory`）与尚未落盘的延迟会话不卸载。文本内容（如被 `prune` 的工具结果）照旧常驻。
+- 会话文件被其它进程改写（如 trash 后被清理）导致读不回时，该条目保留占位并告警，不抛错。
 
 ## custom 类型
 
@@ -116,6 +126,7 @@
 `data` = `TaskInfo`（`taskId, agent, runner, description, background, status, startedAt, endedAt?, turns?, usage?, costUsd?,
 contextTokens?, contextWindow?, outputFile?, sessionRef?`；`contextTokens / contextWindow` 只有外部 Agent 报告时才有）+ `parentToolCallId`、`cwd`。同一 `taskId` 取分支上最后一条；resume 时据此重建任务注册表，
 `status: "running"` 视为 `interrupted`（`taskId` 续聊重开 `sessionRef.sessionFile`）。没有 `status` 的是子会话自己的首条。
+模型调用效率批次（docs/model-efficiency-plan.md）起，两处的 `data` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式，fork 回落为 fresh 时记 `fresh`；缺省即 `fresh`），子会话首条另可带 `forkedFrom?`（fork 点的父条目 id）。都是可选字段，格式版本不变。
 
 第五波登记的类型（docs/wave5-plan.md；括号里是开始写入的批次，之前的版本不会产生，读到未知 `customType` 一律忽略）。`custom_message` 类都是 `display: false`，经扩展点 `beforePrompts` 追加在末尾，不改缓存前缀：
 

package/docs/sessions.md

@@ -1,6 +1,6 @@
 # 会话统计、检索、复用、导出与检查点
 
-这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。范围缺省是**当前目录**的会话，`--all` 看全部。
+这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。会话文件按块逐行读取，不整份读进内存：`ama sessions list` 只解析每个文件的头、首条条目、改名与首条提示，其余行只看类型，几十 MB 的会话也不会让内存随文件大小上涨；`--resume` 打开会话同样逐行解析。范围缺省是**当前目录**的会话，`--all` 看全部。
 
 ## 统计：`ama stats`
 
@@ -71,6 +71,8 @@ RPC `get_session_stats` 原样输出，状态栏与 `/session` 也读它们）
 | `context.autoCompactAt`  | 自动摘要（档二）的阈值 = 窗口 − `compaction.reserveTokens`；自动压缩关闭、连续失败熔断或窗口缺省时**缺省**                               |
 | `context.pruneAt`        | 工具结果裁剪（档一）的阈值 = 0.7 ×（窗口 − `reserveTokens`）；缺省条件同上                                                               |
 
+上表的「窗口」在设了 `compaction.contextBudget`（≥ 32768）时取 min(模型窗口, 它)：档一、档二、熔断与 `context_pressure` 都按这个软窗口算，`contextWindow` 与百分比仍显示模型的真实窗口。窗口很大、单价按上下文长度计的模型适合设它——例如 1M 窗口的模型设 `128000`，长会话按 128k 的节奏压缩，每回合重读的前缀就不会涨到几十万 token；窗口本身不大或按缓存读价计费已经很便宜时不必设。
+
 - **估算口径**：CJK 表意文字 / 假名 / 谚文每字 1 token，其余字符 / 4，图片每张 1 600；usage 取 `totalTokens`（缺则输入 + 输出 + 缓存读写，含输出）。
 - **第一次请求前**（`prefix`）：系统提示与工具表要到第一次请求时才写进会话，在此之前按「将要发送的那一份」（命名节文本 + 工具声明 JSON）估算，所以新会话一打开就不是 0。只用于统计，不写会话、不改请求体。
 - **压缩 / 上下文编辑之后**（`estimate`）：最后那条 usage 不再代表当前上下文，改为全量估算，直到下一次请求带回新的 usage；界面在数字前加 `≈`。

package/docs/tui.md

@@ -103,7 +103,7 @@ Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% 8.2k/272k a
 未命中行按原因分列（`3 次，重计费 61k token ≈ $0.18（空闲超时 2 · 前缀变化 1）`）；保温行在计时中显示 `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05`，停止时给原因；有 task 子会话时另有「子任务」行。
 
 - `/cache warm off|streaming|idle`：本会话内切换保温（不写配置；`idle` 在空闲时也保温，适合贵模型）。
-- `/cache fingerprint`：最近一次真实请求的前缀指纹——system 与工具表各一个 16 位哈希加模型名。两次之间哈希变了，就是宿主或 Hook 中途改了系统提示 / 工具表。
+- `/cache fingerprint`：最近一次真实请求的前缀指纹——system 与工具表各一个 16 位哈希加模型名，system 下逐节列出各节的哈希。两次之间哈希变了，就是宿主或扩展绕过补丁改了开头的系统提示 / 工具表，节哈希指出是哪一节。
 
 取舍：状态栏显示最近一次命中率（会话累计放 `/session`）；`cache.missNotices` 缺省开（门槛下很少触发）；`Meter` 组件不进缺省状态栏。命中率、未命中与保温的判定规则见 [providers.md](providers.md)「缓存」。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [
@@ -30,7 +30,7 @@
     "url": "git+https://github.com/Owlbay/armadra-agent.git"
   },
   "bin": {
-    "ama": "dist/cli/main.js"
+    "ama": "dist/bundle/ama.cjs"
   },
   "exports": {
     ".": {