@armadra/agent 0.7.4 → 0.7.5

package/docs/acp.md

@@ -49,10 +49,13 @@ ama --mode acp                      # 与 -p 互斥；其余参数（--model、-
   再应用到权限管线，并再发一条 `current_mode_update`。所以对排队中的会话改模式不会影响正在跑的那个。
 - 后台子 Agent 完成后的通知回合不经这个队列，在会话空闲时自己开始；它在跑时，对同一会话的 `session/prompt` 也等它
   结束再开始（不报 busy），等待期间客户端先收到通知回合的 `session/update`。等待中 `session/cancel` 会中断通知回合，
-  这条提示回 `cancelled`，之后也不会再被发出。
+  这条提示回 `cancelled`，之后也不会再被发出。这条提示答复里的 `usage` 只算它自己的回合，不含之前的通知回合。
 - 每个回合结束后发 `session_info_update`（`updatedAt`，标题变了才带 `title`）。
-- 关掉一个会话只释放它（跑 SessionEnd Hook），它的转录、图片与子 Agent 句柄随之可被回收；进程启动时建的那个会话
-  对象由进程持有到退出。stdin 关闭时排队的提示回 `cancelled`，等在跑的结束，再依次释放全部会话。
+- 关掉一个会话只释放它（跑 SessionEnd Hook），它的转录、图片与子 Agent 句柄随之可被回收，进程启动时建的那个会话
+  也一样。关闭前先让它安静下来：它的排队提示回 `cancelled`、在跑的后台子 Agent 停掉（不再发完成通知）、在跑的回合
+  （含通知回合）被中断，已排着的通知也不再开回合；`session/close` 之后该会话不再有 `session/update`。被中断的
+  通知回合与 `session/cancel` 一样在会话文件里留下中断标记。stdin 关闭时排队的提示回 `cancelled`，等在跑的提示结束，
+  通知回合与后台子 Agent 按上面的方式停下，再依次释放全部会话。
 
 ### 事件映射
 

package/docs/en/acp.md

@@ -47,9 +47,9 @@ One `ama --mode acp` process can keep several sessions open (Zed's threads share
 - **One turn runs at a time**: while another session runs, `session/prompt` goes into a FIFO queue and starts when the previous turn ends; it no longer fails busy. `session/new`, `load`, `resume`, `list`, `set_mode`, `set_config_option` and `close` can be called at any time.
 - When a turn starts, its session becomes the "foreground" session: the host (`HostApi.session.*`), the common fields of hooks and the session seen by tools all switch to it, and "allowed for this session" grants are cleared (switching back means allowing again, as with `/resume` in the TUI).
 - Permission modes are kept per session: `set_mode` on the foreground session applies at once; on another session it is only recorded (a `current_mode_update` is still sent) and applied to the permission pipeline when that session's turn starts, with another `current_mode_update`. So changing the mode of a queued session does not affect the one that is running.
-- The notification turn that follows a finished background subagent does not go through this queue; it starts on its own once the session is idle. While it runs, `session/prompt` on the same session also waits for it to end (no busy error), and the client sees the notification turn's `session/update` first. `session/cancel` while waiting interrupts the notification turn; the prompt answers `cancelled` and is not sent later either.
+- The notification turn that follows a finished background subagent does not go through this queue; it starts on its own once the session is idle. While it runs, `session/prompt` on the same session also waits for it to end (no busy error), and the client sees the notification turn's `session/update` first. `session/cancel` while waiting interrupts the notification turn; the prompt answers `cancelled` and is not sent later either. The `usage` in that prompt's answer covers only its own turn, not the notification turn before it.
 - After every turn a `session_info_update` is sent (`updatedAt`; `title` only when it changed).
-- Closing a session releases only that session (running the SessionEnd hook), and its transcript, images and subagent handles can then be garbage-collected; the session object created at process start is held by the process until exit. When stdin closes, queued prompts answer `cancelled`, the running turn is allowed to finish, then all sessions are released in turn.
+- Closing a session releases only that session (running the SessionEnd hook), and its transcript, images and subagent handles can then be garbage-collected, including the session created at process start. The session is quieted first: its queued prompts answer `cancelled`, running background subagents are stopped (no completion notification), the running turn (notification turns included) is interrupted and notifications already queued no longer start a turn; after `session/close` that session sends no more `session/update`. An interrupted notification turn leaves an interruption marker in the session file, as `session/cancel` does. When stdin closes, queued prompts answer `cancelled`, running prompts are allowed to finish, notification turns and background subagents are stopped as above, then all sessions are released in turn.
 
 ### Event mapping
 

package/docs/session-format.md

@@ -99,6 +99,16 @@
 - fork（`--fork <id>`、`/fork`、RPC `fork`）：把根 → 指定条目的分支复制到新文件，头的 `parentSession` 指回原文件；不复制 `leaf` 行。
 - `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 类型
 
 `custom` 不进上下文，`custom_message` 进上下文。ama 自己使用的 `customType`：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [