@armadra/agent 0.7.4 → 0.7.6

package/dist/session/manager.d.ts

@@ -11,6 +11,9 @@
  *   不复制 leaf 行；给了 `head` 时它成为新根条目，复制的首条重挂到它下面（fork 子会话的 ama.task）；
  *   `cwd` 缺省同本会话（[ME-A] 隔离的 fork 子会话传 worktree）。
  * - `close()`：释放锁；之后的 append 抛错。
+ * - 图片卸载（#170，offload.ts）：已落盘会话里，活动分支上被 `context_edit` 改写的含图消息只留占位
+ *   （`data: ""`），`entries()` / `branch()` / `getEntry()` 返回卸载后的对象；`getEntries()` 与
+ *   `fork()` 从文件回读原文；`setLeaf()` 换分支后回读不再被改写的条目。内存会话不卸载。
  */
 import type { SessionEntry, SessionEntryInput, SessionHeader, SessionListItem, SessionManagerApi, SessionTreeNode } from "./types.js";
 export interface SessionManagerOptions {
@@ -20,6 +23,8 @@ export interface SessionManagerOptions {
     parentSession?: string;
     /** 指定会话 id（`--session-id`）。 */
     id?: string;
+    /** 图片回读失败等告警（缺省丢弃）。 */
+    warn?: (message: string) => void;
 }
 export declare class SessionManager implements SessionManagerApi {
     readonly id: string;
@@ -31,6 +36,10 @@ export declare class SessionManager implements SessionManagerApi {
     private storage;
     private closed;
     private readonly now;
+    private readonly images;
+    private warn;
+    /** 已知的会话文件字节数（新行的行首偏移）。 */
+    private fileBytes;
     private constructor();
     private static newHeader;
     static inMemory(cwd: string, options?: SessionManagerOptions): SessionManager;
@@ -39,6 +48,7 @@ export declare class SessionManager implements SessionManagerApi {
     static createForCwd(sessionsRoot: string, cwd: string, options?: SessionManagerOptions): SessionManager;
     static open(file: string, options?: {
         now?: () => Date;
+        warn?: (message: string) => void;
     }): SessionManager;
     /** `--continue`：本目录最近一条（跳过子 Agent 会话，只读文件头两行）；没有则新建（延迟落盘）。 */
     static continueRecent(dir: string, cwd: string): SessionManager;
@@ -51,6 +61,14 @@ export declare class SessionManager implements SessionManagerApi {
     leafId(): string | null;
     append(input: SessionEntryInput): SessionEntry;
     setLeaf(id: string | null): void;
+    /** 按当前活动分支卸载 / 回读图片（只对已落盘的会话）。 */
+    private syncImages;
+    /** 原文条目（已卸载的从文件回读一份副本）。 */
+    private original;
+    /** 接上（或换掉）告警出口（图片读不回等）；`open()` 期间缓冲的告警随即按序冲出（#183）。 */
+    setWarn(warn: (message: string) => void): void;
+    /** 已卸载图片的条目数（测试与诊断用）。 */
+    offloadedCount(): number;
     private leafLine;
     branch(leafId?: string | null): SessionEntry[];
     getEntries(since?: string): {

package/dist/session/manager.js

@@ -11,6 +11,9 @@
  *   不复制 leaf 行；给了 `head` 时它成为新根条目，复制的首条重挂到它下面（fork 子会话的 ama.task）；
  *   `cwd` 缺省同本会话（[ME-A] 隔离的 fork 子会话传 worktree）。
  * - `close()`：释放锁；之后的 append 抛错。
+ * - 图片卸载（#170，offload.ts）：已落盘会话里，活动分支上被 `context_edit` 改写的含图消息只留占位
+ *   （`data: ""`），`entries()` / `branch()` / `getEntry()` 返回卸载后的对象；`getEntries()` 与
+ *   `fork()` 从文件回读原文；`setLeaf()` 换分支后回读不再被改写的条目。内存会话不卸载。
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
@@ -19,6 +22,7 @@ import { AmaError } from "../errors.js";
 import { AMA_VERSION } from "../version.js";
 import { listSessionItems } from "./list.js";
 import { migrateSessionLines } from "./migrate.js";
+import { ImageOffload, editTargets } from "./offload.js";
 import { acquireLock, appendLines, isSubagentSessionFile, listSessionFiles, readSessionLines, sessionDirForCwd, sessionFileName, writeNewSessionFile, } from "./store.js";
 import { buildTree, indexEntries, pathToRoot } from "./tree.js";
 import { SESSION_FORMAT_VERSION } from "./types.js";
@@ -39,7 +43,11 @@ export class SessionManager {
     storage;
     closed = false;
     now;
-    constructor(header, entries, storage, now, leafId) {
+    images;
+    warn;
+    /** 已知的会话文件字节数（新行的行首偏移）。 */
+    fileBytes = 0;
+    constructor(header, entries, storage, now, leafId, warn, images) {
         this._header = header;
         this.id = header.id;
         this.cwd = header.cwd;
@@ -50,6 +58,8 @@ export class SessionManager {
             leafId === undefined || (leafId !== null && !this.index.has(leafId)) ? last : leafId;
         this.storage = storage;
         this.now = now;
+        this.warn = warn;
+        this.images = images ?? new ImageOffload(warn);
     }
     static newHeader(cwd, options, now) {
         const header = {
@@ -71,7 +81,7 @@ export class SessionManager {
     /** `dir` 是会话文件所在目录（通常是 `sessionDirForCwd(sessionsRoot, cwd)`）。 */
     static create(dir, cwd, options = {}) {
         const now = options.now ?? (() => new Date());
-        return new SessionManager(this.newHeader(cwd, options, now()), [], { kind: "lazy", dir }, now);
+        return new SessionManager(this.newHeader(cwd, options, now()), [], { kind: "lazy", dir }, now, undefined, options.warn);
     }
     static createForCwd(sessionsRoot, cwd, options = {}) {
         return this.create(sessionDirForCwd(sessionsRoot, cwd), cwd, options);
@@ -79,10 +89,21 @@ export class SessionManager {
     static open(file, options = {}) {
         const lock = acquireLock(file);
         try {
-            const { lines } = readSessionLines(file, { repair: true });
+            const images = new ImageOffload(options.warn);
+            const targets = editTargets(file);
+            const { lines, bytes } = readSessionLines(file, {
+                repair: true,
+                onLine: (line, locator) => {
+                    const entry = line;
+                    images.load(entry, locator, targets.has(entry.id));
+                },
+            });
             const { header, entries, leafId } = migrateSessionLines(lines, file);
             internSessionImages(entries); // D5：同一图片的 base64 只留一份；JSONL 不变
-            return new SessionManager(header, entries, { kind: "file", file, lock }, options.now ?? (() => new Date()), leafId);
+            const manager = new SessionManager(header, entries, { kind: "file", file, lock }, options.now ?? (() => new Date()), leafId, options.warn, images);
+            manager.fileBytes = bytes ?? 0;
+            manager.syncImages();
+            return manager;
         }
         catch (error) {
             lock.release();
@@ -125,11 +146,19 @@ export class SessionManager {
             parentId: this.leaf,
             timestamp: this.now().toISOString(),
         };
-        if (this.storage.kind === "file")
-            appendLines(this.storage.file, [entry]);
+        if (this.storage.kind === "file") {
+            const written = appendLines(this.storage.file, [entry]);
+            this.images.track(entry, { offset: this.fileBytes, length: written - 1 });
+            this.fileBytes += written;
+        }
         this._entries.push(entry);
         this.index.set(entry.id, entry);
         this.leaf = entry.id;
+        if (entry.type === "context_edit" && this.storage.kind === "file") {
+            const target = this.index.get(entry.targetId);
+            if (target !== undefined && this.branch().includes(target))
+                this.images.offload(target);
+        }
         return entry;
     }
     setLeaf(id) {
@@ -137,8 +166,30 @@ export class SessionManager {
             throw new AmaError("invalid_arguments", `no such session entry: ${id}`);
         }
         this.leaf = id;
+        if (this.storage.kind === "file") {
+            this.fileBytes += appendLines(this.storage.file, [this.leafLine()]);
+        }
+        this.syncImages();
+    }
+    /** 按当前活动分支卸载 / 回读图片（只对已落盘的会话）。 */
+    syncImages() {
         if (this.storage.kind === "file")
-            appendLines(this.storage.file, [this.leafLine()]);
+            this.images.sync(this.storage.file, this.branch(), this.index);
+    }
+    /** 原文条目（已卸载的从文件回读一份副本）。 */
+    original(entry) {
+        if (this.storage.kind !== "file" || !this.images.isOffloaded(entry.id))
+            return entry;
+        return this.images.original(this.storage.file, entry);
+    }
+    /** 接上（或换掉）告警出口（图片读不回等）；`open()` 期间缓冲的告警随即按序冲出（#183）。 */
+    setWarn(warn) {
+        this.warn = warn;
+        this.images.setWarn(warn);
+    }
+    /** 已卸载图片的条目数（测试与诊断用）。 */
+    offloadedCount() {
+        return this.images.size;
     }
     leafLine() {
         return { type: "leaf", id: this.leaf, timestamp: this.now().toISOString() };
@@ -147,11 +198,9 @@ export class SessionManager {
         return pathToRoot(this.index, leafId === undefined ? this.leaf : leafId);
     }
     getEntries(since) {
-        if (since === undefined)
-            return { entries: [...this._entries], leafId: this.leaf };
-        const at = this._entries.findIndex((entry) => entry.id === since);
+        const at = since === undefined ? -1 : this._entries.findIndex((entry) => entry.id === since);
         return {
-            entries: at < 0 ? [...this._entries] : this._entries.slice(at + 1),
+            entries: this._entries.slice(at + 1).map((entry) => this.original(entry)),
             leafId: this.leaf,
         };
     }
@@ -172,7 +221,10 @@ export class SessionManager {
         if (!this.index.has(entryId)) {
             throw new AmaError("invalid_arguments", `no such session entry: ${entryId}`);
         }
-        const copied = this.branch(entryId).map((entry) => structuredClone(entry));
+        const copied = this.branch(entryId).map((entry) => {
+            const original = this.original(entry);
+            return original === entry ? structuredClone(entry) : original;
+        });
         if (forkOptions.head !== undefined) {
             const head = {
                 ...forkOptions.head,
@@ -196,7 +248,7 @@ export class SessionManager {
             storage = { kind: "lazy", dir: this.storage.dir };
         else
             storage = { kind: "lazy", dir: dirname(this.storage.file) };
-        const forked = new SessionManager(header, copied, storage, this.now);
+        const forked = new SessionManager(header, copied, storage, this.now, undefined, this.warn);
         if (parentFile !== undefined)
             forked.flush();
         return forked;
@@ -214,11 +266,19 @@ export class SessionManager {
             return this.storage.file;
         const file = join(this.storage.dir, sessionFileName(new Date(this._header.timestamp), this.id));
         const moved = this.leaf !== (this._entries.at(-1)?.id ?? null);
-        writeNewSessionFile(file, [
+        const lengths = writeNewSessionFile(file, [
             this._header,
             ...this._entries,
             ...(moved ? [this.leafLine()] : []),
         ]);
+        let offset = 0;
+        lengths.forEach((length, i) => {
+            const entry = i === 0 ? undefined : this._entries[i - 1];
+            if (entry !== undefined)
+                this.images.track(entry, { offset, length });
+            offset += length + 1;
+        });
+        this.fileBytes = offset;
         let lock;
         try {
             lock = acquireLock(file);
@@ -227,6 +287,7 @@ export class SessionManager {
             lock = undefined;
         }
         this.storage = { kind: "file", file, lock };
+        this.syncImages();
         return file;
     }
     isPersisted() {

package/dist/session/offload.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 会话图片卸载（#170）：被 `context_edit` 改写的旧消息不再进上下文，内存里只留它在会话文件中的行位置，
+ * 图片 base64 需要时再从文件回读。JSONL 格式不变。
+ *
+ * - 对象：活动分支上、被活动分支上的 `context_edit`（任何 reason）改写的 `message` 条目里的 `image` 块；
+ *   不在活动分支上的条目一律保持原文（rewind 回到编辑点之前、`/tree` 换分支时回读）；
+ * - 打开文件时先扫一遍 `context_edit` 行（只解码行首判断类型）收集目标，读条目时目标里的图片解析完
+ *   随即剥掉，峰值不再含全部旧图；随后按活动分支对齐（不在分支上的编辑目标回读）；
+ * - 卸载**不改共享的 ImageBlock**（驻留 block 被其它条目 / 会话共享）：`entry.message` 换成浅拷贝，
+ *   `content` 换新数组，image 块换成 `data: ""` 的占位；
+ * - 回读：按行位置 `readSync` 一行、`JSON.parse`，校验 id 与内容块数，图片经 `internImage` 驻留后
+ *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
+ *   保留 `""` 并告警，不再重试；告警通道可后接（`setWarn`）：接上之前的告警先缓冲（最多
+ *   `PENDING_WARNINGS` 条，其余折叠成一条计数），接上时按序冲出（#183）；
+ * - `original(entry)`：给 `getEntries` / `fork` 的原文副本，不改内存状态。
+ */
+import type { SessionEntry } from "./types.js";
+/** 一行在会话文件里的位置：行首偏移与字节数（不含行尾）。 */
+export interface LineLocator {
+    offset: number;
+    length: number;
+}
+/** `message` 条目的内容里有图片块。 */
+export declare function hasImages(entry: SessionEntry): boolean;
+/** 读文件里 `locator` 处的一行并解析。 */
+export declare function readLineAt(file: string, locator: LineLocator): unknown;
+/** 文件里全部 `context_edit` 的目标 id（只解析 context_edit 行；读不了时为空集）。 */
+export declare function editTargets(file: string): Set<string>;
+/** 告警通道接上之前最多缓冲的条数；超出的只计数，冲出时折叠成一条。 */
+export declare const PENDING_WARNINGS = 16;
+export declare class ImageOffload {
+    /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
+    private readonly locators;
+    private readonly offloaded;
+    private warn;
+    private readonly pending;
+    private dropped;
+    constructor(warn?: (message: string) => void);
+    /** 接上（或换掉）告警通道；之前缓冲的告警按序冲出。 */
+    setWarn(warn: (message: string) => void): void;
+    /** 记下条目的行位置；不含图片的条目忽略。 */
+    track(entry: SessionEntry, locator: LineLocator): void;
+    /** 读文件时逐行调用：记下行位置；`strip` 时就地换成占位（刚解析的对象，别处没有引用）。 */
+    load(line: SessionEntry, locator: LineLocator, strip: boolean): void;
+    isOffloaded(id: string): boolean;
+    /** 已卸载的条目数（测试与诊断用）。 */
+    get size(): number;
+    /** 把条目里的图片换成占位；没有行位置（未落盘、不含图）或已卸载时返回 false。 */
+    offload(entry: SessionEntry): boolean;
+    /** 就地放回图片；读不回时返回 false（占位保留，之后不再卸载 / 回读这一条）。 */
+    hydrate(file: string, entry: SessionEntry): boolean;
+    /** 原文：已卸载的条目从文件读一份新副本（图片驻留），否则原样返回。读不回时返回占位版本。 */
+    original(file: string, entry: SessionEntry): SessionEntry;
+    /** 按活动分支对齐：分支上被生效编辑改写的含图条目卸载，其余已卸载的回读。 */
+    sync(file: string, branch: readonly SessionEntry[], index: ReadonlyMap<string, SessionEntry>): void;
+    /** 从文件读回条目（新对象）；不成功时告警、忘掉行位置并返回 undefined。 */
+    private read;
+    private report;
+}

package/dist/session/offload.js

@@ -0,0 +1,218 @@
+/**
+ * 会话图片卸载（#170）：被 `context_edit` 改写的旧消息不再进上下文，内存里只留它在会话文件中的行位置，
+ * 图片 base64 需要时再从文件回读。JSONL 格式不变。
+ *
+ * - 对象：活动分支上、被活动分支上的 `context_edit`（任何 reason）改写的 `message` 条目里的 `image` 块；
+ *   不在活动分支上的条目一律保持原文（rewind 回到编辑点之前、`/tree` 换分支时回读）；
+ * - 打开文件时先扫一遍 `context_edit` 行（只解码行首判断类型）收集目标，读条目时目标里的图片解析完
+ *   随即剥掉，峰值不再含全部旧图；随后按活动分支对齐（不在分支上的编辑目标回读）；
+ * - 卸载**不改共享的 ImageBlock**（驻留 block 被其它条目 / 会话共享）：`entry.message` 换成浅拷贝，
+ *   `content` 换新数组，image 块换成 `data: ""` 的占位；
+ * - 回读：按行位置 `readSync` 一行、`JSON.parse`，校验 id 与内容块数，图片经 `internImage` 驻留后
+ *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
+ *   保留 `""` 并告警，不再重试；告警通道可后接（`setWarn`）：接上之前的告警先缓冲（最多
+ *   `PENDING_WARNINGS` 条，其余折叠成一条计数），接上时按序冲出（#183）；
+ * - `original(entry)`：给 `getEntries` / `fork` 的原文副本，不改内存状态。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { internImage } from "../ai/image-intern.js";
+import { forEachLineSync, lineTypeOf } from "./line-reader.js";
+import { collectContextEdits } from "./projection.js";
+function isImage(block) {
+    return (typeof block === "object" &&
+        block !== null &&
+        block.type === "image" &&
+        typeof block.data === "string");
+}
+function contentOf(entry) {
+    if (entry.type !== "message")
+        return undefined;
+    const content = entry.message.content;
+    return Array.isArray(content) ? content : undefined;
+}
+/** `message` 条目的内容里有图片块。 */
+export function hasImages(entry) {
+    return contentOf(entry)?.some(isImage) === true;
+}
+/** 读文件里 `locator` 处的一行并解析。 */
+export function readLineAt(file, locator) {
+    const fd = openSync(file, "r");
+    try {
+        const buf = Buffer.allocUnsafe(locator.length);
+        let read = 0;
+        while (read < locator.length) {
+            const n = readSync(fd, buf, read, locator.length - read, locator.offset + read);
+            if (n === 0)
+                throw new Error("unexpected end of file");
+            read += n;
+        }
+        return JSON.parse(buf.toString("utf8"));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 文件里全部 `context_edit` 的目标 id（只解析 context_edit 行；读不了时为空集）。 */
+export function editTargets(file) {
+    const targets = new Set();
+    try {
+        forEachLineSync(file, (line) => {
+            if (lineTypeOf(line)?.type !== "context_edit")
+                return;
+            try {
+                const id = JSON.parse(line.toString("utf8")).targetId;
+                if (typeof id === "string")
+                    targets.add(id);
+            }
+            catch {
+                // 末尾半行：随后的 readSessionLines 修复
+            }
+        });
+    }
+    catch {
+        // 读不了：由随后的 readSessionLines 报错
+    }
+    return targets;
+}
+const placeholder = (block) => ({ ...block, data: "" });
+/** 告警通道接上之前最多缓冲的条数；超出的只计数，冲出时折叠成一条。 */
+export const PENDING_WARNINGS = 16;
+export class ImageOffload {
+    /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
+    locators = new Map();
+    offloaded = new Set();
+    warn;
+    pending = [];
+    dropped = 0;
+    constructor(warn) {
+        this.warn = warn;
+    }
+    /** 接上（或换掉）告警通道；之前缓冲的告警按序冲出。 */
+    setWarn(warn) {
+        this.warn = warn;
+        const pending = this.pending.splice(0);
+        if (this.dropped > 0)
+            pending.push(`and ${this.dropped} more session entries could not be read back`);
+        this.dropped = 0;
+        for (const message of pending)
+            warn(message);
+    }
+    /** 记下条目的行位置；不含图片的条目忽略。 */
+    track(entry, locator) {
+        if (hasImages(entry))
+            this.locators.set(entry.id, locator);
+    }
+    /** 读文件时逐行调用：记下行位置；`strip` 时就地换成占位（刚解析的对象，别处没有引用）。 */
+    load(line, locator, strip) {
+        if (typeof line.id !== "string" || !hasImages(line))
+            return;
+        this.locators.set(line.id, locator);
+        if (!strip)
+            return;
+        const content = contentOf(line);
+        content.forEach((block, i) => {
+            if (isImage(block))
+                content[i] = placeholder(block);
+        });
+        this.offloaded.add(line.id);
+    }
+    isOffloaded(id) {
+        return this.offloaded.has(id);
+    }
+    /** 已卸载的条目数（测试与诊断用）。 */
+    get size() {
+        return this.offloaded.size;
+    }
+    /** 把条目里的图片换成占位；没有行位置（未落盘、不含图）或已卸载时返回 false。 */
+    offload(entry) {
+        if (entry.type !== "message" || this.offloaded.has(entry.id))
+            return false;
+        const content = contentOf(entry);
+        if (content === undefined || !this.locators.has(entry.id))
+            return false;
+        entry.message = {
+            ...entry.message,
+            content: content.map((block) => (isImage(block) ? placeholder(block) : block)),
+        };
+        this.offloaded.add(entry.id);
+        return true;
+    }
+    /** 就地放回图片；读不回时返回 false（占位保留，之后不再卸载 / 回读这一条）。 */
+    hydrate(file, entry) {
+        if (!this.offloaded.has(entry.id))
+            return true;
+        this.offloaded.delete(entry.id);
+        const source = this.read(file, entry);
+        const content = contentOf(entry);
+        if (source === undefined || content === undefined)
+            return false;
+        const originals = contentOf(source) ?? [];
+        content.forEach((block, i) => {
+            const original = originals[i];
+            if (isImage(block) && block.data === "" && isImage(original)) {
+                content[i] = internImage(original);
+            }
+        });
+        return true;
+    }
+    /** 原文：已卸载的条目从文件读一份新副本（图片驻留），否则原样返回。读不回时返回占位版本。 */
+    original(file, entry) {
+        if (!this.offloaded.has(entry.id))
+            return entry;
+        const copy = this.read(file, entry);
+        if (copy === undefined)
+            return entry;
+        const content = contentOf(copy) ?? [];
+        content.forEach((block, i) => {
+            if (isImage(block))
+                content[i] = internImage(block);
+        });
+        return copy;
+    }
+    /** 按活动分支对齐：分支上被生效编辑改写的含图条目卸载，其余已卸载的回读。 */
+    sync(file, branch, index) {
+        const edits = collectContextEdits(branch);
+        const onBranch = new Set();
+        for (const entry of branch)
+            if (edits.has(entry.id))
+                onBranch.add(entry.id);
+        for (const id of [...this.offloaded]) {
+            const entry = index.get(id);
+            if (entry !== undefined && !onBranch.has(id))
+                this.hydrate(file, entry);
+        }
+        for (const id of onBranch) {
+            const entry = index.get(id);
+            if (entry !== undefined)
+                this.offload(entry);
+        }
+    }
+    /** 从文件读回条目（新对象）；不成功时告警、忘掉行位置并返回 undefined。 */
+    read(file, entry) {
+        const locator = this.locators.get(entry.id);
+        try {
+            if (locator === undefined)
+                throw new Error("no line locator");
+            const line = readLineAt(file, locator);
+            const content = line.id === entry.id ? contentOf(line) : undefined;
+            if (content === undefined || content.length !== contentOf(entry)?.length) {
+                throw new Error("line does not match the entry");
+            }
+            return line;
+        }
+        catch (error) {
+            this.locators.delete(entry.id);
+            this.offloaded.delete(entry.id);
+            this.report(`cannot read session entry ${entry.id} back from ${file}: ${String(error)}`);
+            return undefined;
+        }
+    }
+    report(message) {
+        if (this.warn !== undefined)
+            this.warn(message);
+        else if (this.pending.length < PENDING_WARNINGS)
+            this.pending.push(message);
+        else
+            this.dropped++;
+    }
+}

package/dist/session/store.d.ts

@@ -7,6 +7,7 @@
  * - 锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在 → 视为陈旧锁并接管。
  * - prune：移到 `<sessionsRoot>/.trash/`，文件名前缀删除时间；`purgeTrash` 清理超过 7 天的。
  */
+import type { LineLocator } from "./offload.js";
 import type { SessionLine } from "./types.js";
 export declare const SESSION_FILE_SUFFIX = ".jsonl";
 export declare const TRASH_DIR_NAME = ".trash";
@@ -22,6 +23,8 @@ export interface ReadResult {
     lines: SessionLine[];
     /** 末尾半行被截掉时为 true。 */
     repairedTail: boolean;
+    /** 给了 `onLine` 时：读完（含修复）后的文件字节数。 */
+    bytes?: number;
 }
 /** 空白行（同旧口径 `trim() === ""`）：ASCII 空白直接判定，遇到非 ASCII 字节才解码再 trim。 */
 export declare function isBlankLine(line: Buffer): boolean;
@@ -31,11 +34,16 @@ export declare function isBlankLine(line: Buffer): boolean;
  */
 export declare function readSessionLines(file: string, options?: {
     repair?: boolean;
+    /** 每解析出一行就回调（行位置不含行尾；#170 图片卸载在这里就地剥掉图片）。 */
+    onLine?: (line: SessionLine, locator: LineLocator) => void;
 }): ReadResult;
-/** 追加若干行（一次 write，O_APPEND）。 */
-export declare function appendLines(file: string, lines: readonly SessionLine[]): void;
-/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
-export declare function writeNewSessionFile(file: string, lines: readonly SessionLine[]): void;
+/** 追加若干行（一次 write，O_APPEND），返回写入的字节数。 */
+export declare function appendLines(file: string, lines: readonly SessionLine[]): number;
+/**
+ * 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。返回每行的字节数（不含行尾，与
+ * `lines` 同序）。
+ */
+export declare function writeNewSessionFile(file: string, lines: readonly SessionLine[]): number[];
 export interface SessionLock {
     readonly path: string;
     release(): void;

package/dist/session/store.js

@@ -57,8 +57,9 @@ export function readSessionLines(file, options = {}) {
                 unterminated = true;
             if (isBlankLine(buf))
                 return;
+            let line;
             try {
-                lines.push(JSON.parse(buf.toString("utf8")));
+                line = JSON.parse(buf.toString("utf8"));
             }
             catch (error) {
                 if (last) {
@@ -71,6 +72,8 @@ export function readSessionLines(file, options = {}) {
                     cause: error,
                 });
             }
+            options.onLine?.(line, { offset, length: buf.length });
+            lines.push(line);
         });
     }
     catch (error) {
@@ -82,32 +85,39 @@ export function readSessionLines(file, options = {}) {
         // 最后一行完整但缺 LF：补上，保证后续追加另起一行。
         appendRaw(file, "\n");
     }
-    return { lines, repairedTail };
+    if (options.onLine === undefined)
+        return { lines, repairedTail };
+    return { lines, repairedTail, bytes: statSync(file).size };
 }
 function appendRaw(file, text) {
     const fd = openSync(file, "a");
     try {
-        writeSync(fd, text);
+        return writeSync(fd, text);
     }
     finally {
         closeSync(fd);
     }
 }
-/** 追加若干行（一次 write，O_APPEND）。 */
+/** 追加若干行（一次 write，O_APPEND），返回写入的字节数。 */
 export function appendLines(file, lines) {
     if (lines.length === 0)
-        return;
-    appendRaw(file, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
+        return 0;
+    return appendRaw(file, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
 }
-/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
+/**
+ * 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。返回每行的字节数（不含行尾，与
+ * `lines` 同序）。
+ */
 export function writeNewSessionFile(file, lines) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     if (existsSync(file)) {
         throw new AmaError("session_exists", `session file already exists: ${file}`);
     }
     const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, lines.map((line) => JSON.stringify(line)).join("\n") + "\n", { mode: 0o600 });
+    const texts = lines.map((line) => JSON.stringify(line));
+    writeFileSync(tmp, texts.join("\n") + "\n", { mode: 0o600 });
     renameSync(tmp, file);
+    return texts.map((text) => Buffer.byteLength(text));
 }
 // ---------------------------------------------------------------------------
 // 锁

package/dist/tools/background-jobs.d.ts

@@ -5,14 +5,14 @@
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
  *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
  * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
- *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ *   `output(id, options?)`：读输出文件尾部（缺省 2000 行 / 50 KB，调用方可传字节上限）。
  * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
  *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
  * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
  */
 import type { ChildProcess } from "node:child_process";
 import { type ProcessDeps } from "./process-tree.js";
-import { type TruncateResult } from "./truncate.js";
+import { type TruncateOptions, type TruncateResult } from "./truncate.js";
 export type JobStatus = "running" | "exited" | "stopped";
 export interface Job {
     id: string;
@@ -49,8 +49,8 @@ export declare class BackgroundJobs {
     /** 等到退出或超时（`signal` 可提前结束等待，不杀进程）。 */
     wait(id: string, timeoutMs: number, signal?: AbortSignal): Promise<Job | undefined>;
     stop(id: string): Promise<Job | undefined>;
-    /** 输出文件尾部（2000 行 / 50 KB）。 */
-    output(id: string): (TruncateResult & {
+    /** 输出文件尾部（缺省 2000 行 / 50 KB；调用方可传字节上限，#155）。 */
+    output(id: string, options?: TruncateOptions): (TruncateResult & {
         job: Job;
     }) | undefined;
     /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */