@armadra/agent 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.5 (2026-10-10)
+
+### Memory footprint
+
+- **`read` no longer blocks the event loop on large files**: the byte-window path for text files over 1 MiB now reads 64 KiB chunks asynchronously, awaiting once per chunk, so TUI/RPC/ACP stay responsive while a 256 MB file is scanned (longest event-loop stall about 170–320 ms → under 20 ms). Output is byte-for-byte identical (the sync and async readers share one line parser); peak memory is unchanged (still one chunk buffer).
+- **Request bodies with images no longer copy each image**: image data goes from the transcript straight into the request body instead of first being joined into a new data-URL string on every request, its escape check runs once per image, and the body is encoded in chunks of at most 256 Ki characters instead of one whole image at a time. Mock 300-step session with 15 images: peak RSS about 630–690 → 390–400 MB, peak heapUsed about 270 → 85 MB. Request bytes are unchanged; SDK `onPayload` callbacks now see large images as objects with `toJSON` (`JSON.stringify` gives the same text).
+- **Old images released after downgrade**: once `context_edit` (for example `image_budget`) replaces a message on the active branch, its image base64 is no longer kept in memory — only the line's position in the session file — and is read back on demand: `get_entries` and fork return the original, and moving the leaf back before the edit (`/tree`, rewind) restores the images. Resuming a session also strips those images while reading, so they no longer count toward the peak (55 MB session with 10 downgraded 3 MB images: peak RSS about 254 → 210 MB). The JSONL format is unchanged; in `entries()` / `branch()` / SDK `session.entries` such image blocks now have `data: ""`.
+- **Closed ACP sessions free the startup session too**: `Runtime.session` and `Runtime.sessionManager` now follow the current session instead of staying on the one created at startup, so after `session/close` its transcript and images are garbage-collected like any other session's (8 sessions × 4 rounds, all closed: external 16.3 → 7.0 MB). SDK code that reads `runtime.session` after a session switch now gets the new session.
+- **ACP `session/prompt` usage covers only its own turn**: a prompt that waited for a background subagent's notification turn no longer counts that turn's tokens in `usage`.
+- **`session/close` during a notification turn**: it used to fail with -32603 and keep the session in memory; now running background subagents are stopped, the running turn (notification turns included) is interrupted, already queued notifications no longer start a turn, and the session is released with no further `session/update`. Closing stdin quiets sessions the same way.
+
 ## 0.7.4 (2026-10-10)
 
 - **Parallel worktree isolation**: two isolated tasks starting together could fail with `could not read .git/worktrees/<id>/commondir`, because `git worktree add` read the other task's half-created admin directory. Worktree add / remove and branch deletion now run one at a time per repository, and the same transient errors from another ama process are retried briefly.

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,17 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.7.5（2026-10-10）
+
+### 内存占用
+
+- **`read` 读大文件不再阻塞事件循环**：超过 1 MiB 的文本走的字节窗口改为异步按 64 KiB 分块读，每块一次 `await`，扫描 256 MB 文件期间 TUI / RPC / ACP 仍能响应（事件循环最长停顿约 170–320 ms → 20 ms 以内）。输出逐字节不变（同步与异步共用同一个行解析器），峰值内存不变（仍只有一块缓冲）。
+- **带图请求体不再复制每张图**：图片数据从转录直接写入请求体，不再每个请求先拼出一份新的 data URL 字符串；转义检查每张图只做一次；请求体按每块最多 256 Ki 码元编码，不再一次编码一整张图。mock 300 步带 15 张图：峰值 RSS 约 630–690 → 390–400 MB，heapUsed 峰值约 270 → 85 MB。请求字节不变；SDK 的 `onPayload` 回调里大图变为带 `toJSON` 的对象（`JSON.stringify` 结果相同）。
+- **降级后释放旧图**：活动分支上的消息被 `context_edit`（如 `image_budget`）改写后，图片 base64 不再常驻内存，只记该行在会话文件中的位置，需要时按位置读回：`get_entries` 与 fork 返回原文，换叶子回到编辑之前（`/tree`、rewind）时恢复图片。续会话读文件时随读随剥，这些旧图不再计入峰值（55 MB、含 10 张被降级的 3 MB 图的会话：峰值 RSS 约 254 → 210 MB）。JSONL 格式不变；`entries()` / `branch()` / SDK `session.entries` 里这类图片块的 `data` 为空串。
+- **ACP 关掉的启动会话也能回收**：`Runtime.session` 与 `Runtime.sessionManager` 改为跟随当前会话（原先固定指向启动时建的会话），`session/close` 之后它的转录与图片和其它会话一样被回收（8 会话 × 4 轮全部关闭后 external 16.3 → 7.0 MB）。SDK 代码在切换会话后读 `runtime.session` 得到的是新会话。
+- **ACP `session/prompt` 的 usage 只算本回合**：等过后台子 Agent 通知回合的提示，`usage` 不再计入那一回合的 token。
+- **通知回合在跑时 `session/close`**：原先以 -32603 失败且会话留在内存；现在先停在跑的后台子 Agent、中断在跑的回合（含通知回合）、已排着的通知不再开回合，然后释放会话，之后不再有 `session/update`。stdin 关闭时同样这样收尾。
+
 ## 0.7.4（2026-10-10）
 
 - **并行 worktree 隔离**：两个隔离任务同时开始时，可能报 `无法读取 .git/worktrees/<id>/commondir`——`git worktree add` 读到了另一个任务建了一半的管理目录。现在同一仓库的 worktree 增删与删分支按顺序执行，另一个 ama 进程造成的同类瞬时错误短暂重试。

package/dist/ai/apis/anthropic-request.js

@@ -17,6 +17,7 @@
  * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
  */
 import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { largeString } from "../json-body.js";
 import { budgetedMaxTokens, clampThinkingLevel, mappedThinkingValue, thinkingBudget, } from "../thinking.js";
 import { detectAnthropicCompat } from "./anthropic-compat.js";
 import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
@@ -76,7 +77,11 @@ function convertBlocks(content) {
         else {
             blocks.push({
                 type: "image",
-                source: { type: "base64", media_type: block.mimeType, data: block.data },
+                source: {
+                    type: "base64",
+                    media_type: block.mimeType,
+                    data: largeString("", block, block.data),
+                },
             });
         }
     }

package/dist/ai/apis/cache-params.js

@@ -14,6 +14,7 @@
  * 并提示一次（实测：某中转的 Responses 对 DeepSeek 拒收 prompt_cache_retention / _options）。
  */
 import { HttpError, postJson } from "../http.js";
+import { LargeString } from "../json-body.js";
 import { msg } from "../../i18n/index.js";
 const DEFAULT_BASE_URLS = {
     "anthropic-messages": "https://api.anthropic.com",
@@ -133,7 +134,7 @@ export function isCacheParamRejection(error) {
 function stripInto(value, removed) {
     if (Array.isArray(value))
         return value.map((item) => stripInto(item, removed));
-    if (typeof value !== "object" || value === null)
+    if (typeof value !== "object" || value === null || value instanceof LargeString)
         return value;
     const out = {};
     for (const [key, inner] of Object.entries(value)) {

package/dist/ai/apis/google-request.js

@@ -13,6 +13,7 @@
  * - `toolChoice: "none"`（有工具时）→ `toolConfig.functionCallingConfig.mode: "NONE"`。
  */
 import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { largeString } from "../json-body.js";
 import { DEFAULT_THINKING_BUDGETS, clampBudgetToAnswerRoom, clampThinkingLevel, discreteThinkingLevel, } from "../thinking.js";
 export const GOOGLE_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
 const GOOGLE_COMPAT_KEYS = [
@@ -63,7 +64,7 @@ function validSignature(signature) {
         BASE64.test(signature));
 }
 function inlineData(block) {
-    return { inlineData: { mimeType: block.mimeType, data: block.data } };
+    return { inlineData: { mimeType: block.mimeType, data: largeString("", block, block.data) } };
 }
 function convertUser(message) {
     if (typeof message.content === "string") {

package/dist/ai/apis/openai-request.js

@@ -19,12 +19,14 @@ import { contentText, normalizeContext, normalizeContextInline, sanitizeText, }
 import { DEFAULT_THINKING_BUDGETS, clampBudgetToAnswerRoom, clampThinkingLevel, mappedThinkingValue, } from "../thinking.js";
 import { cacheControlFor } from "./anthropic-request.js";
 import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
+import { largeString } from "../json-body.js";
 import { detectCompat } from "./openai-compat.js";
 /** 思考文本回放用的字段名；thinkingSignature 记录来源字段，回放时原样放回。 */
 export const REASONING_FIELDS = ["reasoning_content", "reasoning", "reasoning_text"];
 export const ASSISTANT_BRIDGE_TEXT = "Tool results received.";
 function imagePart(block) {
-    return { type: "image_url", image_url: { url: `data:${block.mimeType};base64,${block.data}` } };
+    const url = largeString(`data:${block.mimeType};base64,`, block, block.data);
+    return { type: "image_url", image_url: { url } };
 }
 function convertUser(message) {
     if (typeof message.content === "string") {

package/dist/ai/apis/openai-responses-request.js

@@ -21,6 +21,7 @@
  * - [W6-O] compat `chatgptBackend`（ChatGPT 订阅后端）：最后经 chatgpt-backend.ts 按后端白名单改写。
  */
 import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { largeString } from "../json-body.js";
 import { clampThinkingLevel, mappedThinkingValue } from "../thinking.js";
 import { resolveCacheRetention, resolvePromptCacheCompat } from "./cache-params.js";
 import { transformChatGptBody } from "./chatgpt-backend.js";
@@ -110,7 +111,7 @@ function imagePart(block) {
     return {
         type: "input_image",
         detail: "auto",
-        image_url: `data:${block.mimeType};base64,${block.data}`,
+        image_url: largeString(`data:${block.mimeType};base64,`, block, block.data),
     };
 }
 function convertUser(message) {

package/dist/ai/json-body.d.ts

@@ -11,9 +11,36 @@
  * 键、`[`）与已验证无需转义的大字符串（需要转义的大字符串整个交给原生）；`toJSON`、`undefined` /
  * 函数 / symbol 的跳过与 `null`、数字格式、转义全部由原生处理（带 `toJSON` 的值经单键容器序列化，
  * 保证 `toJSON(key)` 收到与原生相同的键）。
+ *
+ * 图片由转换器包成 {@link LargeString}（`prefix + text`）：片段路径直接写转录里的原字符串，不经模板串
+ * 拼接后的扁平化；无需转义的结论与字节数按 ImageBlock 缓存，同一张图每进程只扫一次。流式发送时大片段
+ * 按 {@link STREAM_CHUNK_CHARS} 切块编码。
  */
 /** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
 export declare const LARGE_STRING_BYTES: number;
+/** `isPlain` 的调用次数（测试用：同一块图片第二次序列化不应再扫）。 */
+export declare const plainScans: {
+    count: number;
+};
+/**
+ * 请求体里的大字符串叶子 `prefix + text`（data URL 或裸 base64），用来代替模板串拼接：拼接得到的
+ * cons string 在每次序列化时都会被扁平化成一份新的整图字符串。片段路径直接写 `prefix` 与 `text`
+ * （`text` 是转录里的原字符串，不拷贝）；`text` 无需转义的结论按 `key`（转录里身份稳定的 ImageBlock）
+ * 缓存，同一块每进程只扫一次。约定：同一 `key` 的 `text` 不变。其它遍历者看到的是一个带 `toJSON`
+ * 的对象，原生 `JSON.stringify` 得到相同字符串。由 {@link largeString} 构造。
+ */
+export declare class LargeString {
+    readonly prefix: string;
+    readonly key: object;
+    readonly text: string;
+    constructor(prefix: string, key: object, text: string);
+    toJSON(): string;
+}
+/**
+ * `prefix + text` 作为请求体的值：`text` 够大且 `prefix` 自身无需转义时给 {@link LargeString}，
+ * 否则就是拼好的字符串（小图与以前完全相同）。
+ */
+export declare function largeString(prefix: string, key: object, text: string): string | LargeString;
 /** 与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同；大字符串不经中间字符串。 */
 export declare function serializeJsonBody(body: unknown): Buffer;
 /** `postJson` 交给 fetch 的请求体。 */
@@ -22,10 +49,15 @@ export interface JsonFetchBody {
     /** 流式请求体的字节数：调用方须作为 `content-length` 头发出（不走 chunked）。 */
     contentLength?: number;
 }
+/**
+ * 流式请求体每块最多编码的码元数：大片段（一整张图）按游标切片（V8 切片串不拷贝）逐块编码，
+ * 发送期间只多出一块的 UTF-8 字节，而不是一整张图。
+ */
+export declare const STREAM_CHUNK_CHARS: number;
 /**
  * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
  * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
  * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
- * 同一时刻只多出一个片段的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ * 同一时刻只多出一块（≤ {@link STREAM_CHUNK_CHARS} 码元）的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
  */
 export declare function jsonFetchBody(body: unknown): JsonFetchBody;

package/dist/ai/json-body.js

@@ -11,6 +11,10 @@
  * 键、`[`）与已验证无需转义的大字符串（需要转义的大字符串整个交给原生）；`toJSON`、`undefined` /
  * 函数 / symbol 的跳过与 `null`、数字格式、转义全部由原生处理（带 `toJSON` 的值经单键容器序列化，
  * 保证 `toJSON(key)` 收到与原生相同的键）。
+ *
+ * 图片由转换器包成 {@link LargeString}（`prefix + text`）：片段路径直接写转录里的原字符串，不经模板串
+ * 拼接后的扁平化；无需转义的结论与字节数按 ImageBlock 缓存，同一张图每进程只扫一次。流式发送时大片段
+ * 按 {@link STREAM_CHUNK_CHARS} 切块编码。
  */
 /** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
 export const LARGE_STRING_BYTES = 64 * 1024;
@@ -23,6 +27,7 @@ const CHECK_CHUNK = 16 * 1024;
  * 每个大字符串每次序列化只查这一次。
  */
 function isPlain(value) {
+    plainScans.count++;
     for (let i = 0; i < value.length; i += CHECK_CHUNK) {
         const chunk = value.slice(i, i + CHECK_CHUNK);
         if (JSON.stringify(chunk).length !== chunk.length + 2)
@@ -30,6 +35,54 @@ function isPlain(value) {
     }
     return true;
 }
+/** 短字符串无需转义（`LargeString.prefix` 用）。 */
+const isShortPlain = (value) => JSON.stringify(value).length === value.length + 2;
+/** `isPlain` 的调用次数（测试用：同一块图片第二次序列化不应再扫）。 */
+export const plainScans = { count: 0 };
+/**
+ * 请求体里的大字符串叶子 `prefix + text`（data URL 或裸 base64），用来代替模板串拼接：拼接得到的
+ * cons string 在每次序列化时都会被扁平化成一份新的整图字符串。片段路径直接写 `prefix` 与 `text`
+ * （`text` 是转录里的原字符串，不拷贝）；`text` 无需转义的结论按 `key`（转录里身份稳定的 ImageBlock）
+ * 缓存，同一块每进程只扫一次。约定：同一 `key` 的 `text` 不变。其它遍历者看到的是一个带 `toJSON`
+ * 的对象，原生 `JSON.stringify` 得到相同字符串。由 {@link largeString} 构造。
+ */
+export class LargeString {
+    prefix;
+    key;
+    text;
+    constructor(prefix, key, text) {
+        this.prefix = prefix;
+        this.key = key;
+        this.text = text;
+    }
+    toJSON() {
+        return this.prefix + this.text;
+    }
+}
+/**
+ * `prefix + text` 作为请求体的值：`text` 够大且 `prefix` 自身无需转义时给 {@link LargeString}，
+ * 否则就是拼好的字符串（小图与以前完全相同）。
+ */
+export function largeString(prefix, key, text) {
+    if (text.length < LARGE_STRING_BYTES || !isShortPlain(prefix))
+        return prefix + text;
+    return new LargeString(prefix, key, text);
+}
+/** 已确认无需转义的 `LargeString.text`：键是 `key`，值是当时的 UTF-8 字节数（同时省掉再数一遍）。 */
+const plainBytes = new WeakMap();
+/** `LargeString.text` 可原样写入时返回其 UTF-8 字节数，否则 undefined。 */
+function plainLargeBytes(value) {
+    if (!isShortPlain(value.prefix))
+        return undefined;
+    const known = plainBytes.get(value.key);
+    if (known !== undefined && known.length === value.text.length)
+        return known.bytes;
+    if (!isPlain(value.text))
+        return undefined;
+    const bytes = Buffer.byteLength(value.text, "utf8");
+    plainBytes.set(value.key, { length: value.text.length, bytes });
+    return bytes;
+}
 /** 结构遍历的深度上限：更深（或有环）时整棵子树交给原生，环由原生照常抛 TypeError。 */
 const MAX_DEPTH = 64;
 const isLargeString = (value) => typeof value === "string" && value.length >= LARGE_STRING_BYTES;
@@ -48,6 +101,8 @@ function isContainer(value) {
 function collectLarge(value, marked, depth) {
     if (isLargeString(value))
         return true;
+    if (value instanceof LargeString)
+        return value.text.length >= LARGE_STRING_BYTES;
     if (depth >= MAX_DEPTH || !isContainer(value))
         return false;
     let found = false;
@@ -81,18 +136,24 @@ function nativeValue(key, value) {
 /** 片段：已拼好的 JSON 文本与大字符串交替；连续的小文本先在字符串里累积。 */
 class Pieces {
     parts = [];
+    /** 已推入 `parts` 的 UTF-8 字节数。 */
+    bytes = 0;
     pending = "";
     text(chunk) {
         this.pending += chunk;
     }
-    /** 大字符串原样写入（引号进相邻的小片段）。 */
-    large(value) {
-        this.parts.push(`${this.pending}"`, value);
+    /** 大字符串原样写入（引号与 `head` 进前一个小片段）；`bytes` 已知时不再数一遍。 */
+    large(value, head = "", bytes = Buffer.byteLength(value, "utf8")) {
+        const before = `${this.pending}"${head}`;
+        this.parts.push(before, value);
+        this.bytes += Buffer.byteLength(before, "utf8") + bytes;
         this.pending = '"';
     }
     finish() {
-        if (this.pending.length > 0)
+        if (this.pending.length > 0) {
             this.parts.push(this.pending);
+            this.bytes += Buffer.byteLength(this.pending, "utf8");
+        }
         this.pending = "";
         return this.parts;
     }
@@ -109,6 +170,15 @@ function writeEntry(key, value, marked, out, prefix, depth) {
         }
         return true;
     }
+    if (value instanceof LargeString && value.text.length >= LARGE_STRING_BYTES) {
+        const bytes = plainLargeBytes(value);
+        out.text(prefix);
+        if (bytes !== undefined)
+            out.large(value.text, value.prefix, bytes);
+        else
+            out.text(JSON.stringify(value.toJSON())); // 需要转义：交给原生
+        return true;
+    }
     // 深度与 collectLarge 一致；有环时越过上限交给原生，由它抛 TypeError
     if (depth < MAX_DEPTH && isContainer(value) && marked.has(value)) {
         out.text(prefix);
@@ -150,18 +220,9 @@ function jsonParts(body) {
     if (!collectLarge(body, marked, 0))
         return undefined;
     const out = new Pieces();
-    if (isLargeString(body)) {
-        if (!isPlain(body))
-            return undefined;
-        out.large(body);
-    }
-    else
-        writeContainer(body, marked, out, 0);
+    writeEntry("", body, marked, out, "", 0); // 顶层：键为 ""，与原生调用 toJSON 的键相同
     const parts = out.finish();
-    let length = 0;
-    for (const part of parts)
-        length += Buffer.byteLength(part, "utf8");
-    return { parts, length };
+    return { parts, length: out.bytes };
 }
 /** 与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同；大字符串不经中间字符串。 */
 export function serializeJsonBody(body) {
@@ -178,11 +239,16 @@ export function serializeJsonBody(body) {
     }
     return buf;
 }
+/**
+ * 流式请求体每块最多编码的码元数：大片段（一整张图）按游标切片（V8 切片串不拷贝）逐块编码，
+ * 发送期间只多出一块的 UTF-8 字节，而不是一整张图。
+ */
+export const STREAM_CHUNK_CHARS = 256 * 1024;
 /**
  * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
  * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
  * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
- * 同一时刻只多出一个片段的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ * 同一时刻只多出一块（≤ {@link STREAM_CHUNK_CHARS} 码元）的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
  */
 export function jsonFetchBody(body) {
     const split = jsonParts(body);
@@ -190,6 +256,7 @@ export function jsonFetchBody(body) {
         return { body: JSON.stringify(body) };
     const { parts } = split;
     let next = 0;
+    let offset = 0; // 当前片段已发出的码元数
     const stream = new ReadableStream({
         pull(controller) {
             const part = parts[next];
@@ -197,8 +264,19 @@ export function jsonFetchBody(body) {
                 controller.close();
                 return;
             }
-            parts[next++] = ""; // 发出即放手，片段（拼出来的小文本）可尽早回收
-            controller.enqueue(Buffer.from(part, "utf8"));
+            let end = Math.min(part.length, offset + STREAM_CHUNK_CHARS);
+            // 不把成对代理项切开（片段里只有成对的：孤立代理项已被原生转义）
+            const last = part.charCodeAt(end - 1);
+            if (end < part.length && last >= 0xd800 && last <= 0xdbff)
+                end--;
+            const piece = offset === 0 && end === part.length ? part : part.slice(offset, end);
+            if (end === part.length) {
+                parts[next++] = ""; // 发完即放手，片段（拼出来的小文本）可尽早回收
+                offset = 0;
+            }
+            else
+                offset = end;
+            controller.enqueue(Buffer.from(piece, "utf8"));
         },
         cancel() {
             parts.length = 0;