@armadra/agent 0.7.3 → 0.7.5

package/dist/session/list.js

@@ -0,0 +1,150 @@
+/**
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
+ * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
+ *
+ * 口径与「`migrateSessionLines(readSessionLines(file).lines)` 再统计」一致：空行跳过、末尾半行忽略、
+ * 头必须是 `type: "session"` / `version === SESSION_FORMAT_VERSION` / id 与 cwd 为字符串、`leaf` 行不算
+ * 条目、重复的头与解析失败的中间行让整个文件跳过。差别只有一处：不解析的 ama 行不再逐条检查
+ * `id`（ama 写入的条目总有 id）；行尾不是 `}` 的（写到一半又被追加的坏行）仍会退回完整解析。
+ * 不经 `migrateSessionLines`——格式升到 v2 时要同时改这里（R6，见 migrate.ts）。
+ */
+import { statSync } from "node:fs";
+import { forEachLineSync, lineTypeOf } from "./line-reader.js";
+import { isBlankLine, isSubagentSession, listSessionFiles } from "./store.js";
+import { SESSION_FORMAT_VERSION } from "./types.js";
+class SkipFile extends Error {
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function endsWithBrace(line) {
+    for (let i = line.length - 1; i >= 0; i--) {
+        const byte = line[i];
+        if (byte === 0x20 || (byte >= 0x09 && byte <= 0x0d))
+            continue;
+        return byte === 0x7d;
+    }
+    return false;
+}
+function promptText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((block) => (block.type === "text" ? block.text : ""))
+        .join("");
+}
+/** 统计一条已解析的行（头之后）；不合 v1 规则时抛 SkipFile。 */
+function tallyParsed(tally, line) {
+    if (isObject(line) && line["type"] === "leaf") {
+        const id = line["id"];
+        if (id !== null && typeof id !== "string")
+            throw new SkipFile();
+        return;
+    }
+    if (!isObject(line) || typeof line["id"] !== "string" || typeof line["type"] !== "string") {
+        throw new SkipFile();
+    }
+    if (line["type"] === "session")
+        throw new SkipFile();
+    if (!tally.hasFirst) {
+        tally.hasFirst = true;
+        tally.first = line;
+    }
+    if (line["type"] === "session_info" && line["name"] !== undefined) {
+        tally.name = line["name"];
+    }
+    if (line["type"] !== "message")
+        return;
+    const message = line["message"];
+    if (message.role === "system")
+        return;
+    tally.messageCount++;
+    if (tally.firstPrompt === undefined && message.role === "user") {
+        tally.firstPrompt = promptText(message.content);
+    }
+}
+function parseHeader(line) {
+    if (!isObject(line) || line["type"] !== "session")
+        throw new SkipFile();
+    if (line["version"] !== SESSION_FORMAT_VERSION)
+        throw new SkipFile();
+    if (typeof line["id"] !== "string" || typeof line["cwd"] !== "string")
+        throw new SkipFile();
+    return line;
+}
+/** 不解析就能统计的 ama 行：已过第一条条目、类型确定、行尾完整，且不需要读出内容。 */
+function tallyByType(tally, line, firstPromptTaken) {
+    if (!tally.hasFirst || !endsWithBrace(line))
+        return false;
+    const kind = lineTypeOf(line);
+    if (kind === undefined)
+        return false;
+    if (kind.type === "leaf" || kind.type === "session_info" || kind.type === "session")
+        return false;
+    if (kind.type !== "message")
+        return true;
+    if (kind.role === undefined)
+        return false;
+    if (kind.role === "system")
+        return true;
+    if (kind.role === "user" && !firstPromptTaken)
+        return false;
+    tally.messageCount++;
+    return true;
+}
+function tallyFile(file) {
+    const tally = { hasFirst: false, messageCount: 0 };
+    forEachLineSync(file, (buf, _index, last) => {
+        if (isBlankLine(buf))
+            return;
+        if (tally.header !== undefined && !last) {
+            if (tallyByType(tally, buf, tally.firstPrompt !== undefined))
+                return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(buf.toString("utf8"));
+        }
+        catch {
+            if (last)
+                return false; // 末尾半行：与 readSessionLines 一样忽略
+            throw new SkipFile();
+        }
+        if (tally.header === undefined)
+            tally.header = parseHeader(parsed);
+        else
+            tallyParsed(tally, parsed);
+    });
+    return tally;
+}
+/** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+export function listSessionItems(dir) {
+    const items = [];
+    for (const file of listSessionFiles(dir)) {
+        try {
+            const { header, first, name, firstPrompt, messageCount } = tallyFile(file);
+            if (header === undefined)
+                continue;
+            const item = {
+                id: header.id,
+                file,
+                cwd: header.cwd,
+                createdAt: header.timestamp,
+                modifiedAt: statSync(file).mtime.toISOString(),
+                messageCount,
+            };
+            if (name !== undefined)
+                item.name = name;
+            if (isSubagentSession(header, first))
+                item.subagent = true;
+            if (firstPrompt !== undefined)
+                item.firstPrompt = firstPrompt.slice(0, 200);
+            items.push(item);
+        }
+        catch {
+            // 损坏 / 不可读：列表里跳过（sessions show 会给出具体错误）
+        }
+    }
+    return items;
+}

package/dist/session/manager.d.ts

@@ -7,9 +7,13 @@
  * - `open(file)`：读文件（修复末尾半行）、校验版本、加锁；叶子 = 文件中最后一条条目，
  *   若其后还有 `leaf` 行（`/tree` 换叶子落盘，第三波 A7）则取最后一条 leaf 行。
  * - `setLeaf(id)`：已落盘时追加一行 `leaf{id, timestamp}`；延迟会话在 `flush()` 时补写。
- * - `fork(entryId)`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
- *   不复制 leaf 行。
+ * - `fork(entryId, { head })`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
+ *   不复制 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 {
@@ -19,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;
@@ -30,6 +36,10 @@ export declare class SessionManager implements SessionManagerApi {
     private storage;
     private closed;
     private readonly now;
+    private readonly images;
+    private readonly warn;
+    /** 已知的会话文件字节数（新行的行首偏移）。 */
+    private fileBytes;
     private constructor();
     private static newHeader;
     static inMemory(cwd: string, options?: SessionManagerOptions): SessionManager;
@@ -38,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;
@@ -50,6 +61,12 @@ export declare class SessionManager implements SessionManagerApi {
     leafId(): string | null;
     append(input: SessionEntryInput): SessionEntry;
     setLeaf(id: string | null): void;
+    /** 按当前活动分支卸载 / 回读图片（只对已落盘的会话）。 */
+    private syncImages;
+    /** 原文条目（已卸载的从文件回读一份副本）。 */
+    private original;
+    /** 已卸载图片的条目数（测试与诊断用）。 */
+    offloadedCount(): number;
     private leafLine;
     branch(leafId?: string | null): SessionEntry[];
     getEntries(since?: string): {
@@ -59,7 +76,10 @@ export declare class SessionManager implements SessionManagerApi {
     getTree(): SessionTreeNode[];
     name(): string | undefined;
     setName(name: string): void;
-    fork(entryId: string): SessionManager;
+    fork(entryId: string, forkOptions?: {
+        head?: SessionEntryInput;
+        cwd?: string;
+    }): SessionManager;
     /** 延迟会话：建文件、写头与缓存条目、加锁。返回文件路径（内存会话为 undefined）。幂等。 */
     flush(): string | undefined;
     isPersisted(): boolean;

package/dist/session/manager.js

@@ -7,17 +7,23 @@
  * - `open(file)`：读文件（修复末尾半行）、校验版本、加锁；叶子 = 文件中最后一条条目，
  *   若其后还有 `leaf` 行（`/tree` 换叶子落盘，第三波 A7）则取最后一条 leaf 行。
  * - `setLeaf(id)`：已落盘时追加一行 `leaf{id, timestamp}`；延迟会话在 `flush()` 时补写。
- * - `fork(entryId)`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
- *   不复制 leaf 行。
+ * - `fork(entryId, { head })`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
+ *   不复制 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 { statSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { internSessionImages } from "../ai/image-intern.js";
 import { AmaError } from "../errors.js";
 import { AMA_VERSION } from "../version.js";
+import { listSessionItems } from "./list.js";
 import { migrateSessionLines } from "./migrate.js";
-import { acquireLock, appendLines, isSubagentSession, isSubagentSessionFile, listSessionFiles, readSessionLines, sessionDirForCwd, sessionFileName, writeNewSessionFile, } from "./store.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";
 function newEntryId(taken) {
@@ -37,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;
@@ -48,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 = {
@@ -69,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);
@@ -77,9 +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);
-            return new SessionManager(header, entries, { kind: "file", file, lock }, options.now ?? (() => new Date()), leafId);
+            internSessionImages(entries); // D5：同一图片的 base64 只留一份；JSONL 不变
+            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();
@@ -93,48 +117,7 @@ export class SessionManager {
     }
     /** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
     static list(dir) {
-        const items = [];
-        for (const file of listSessionFiles(dir)) {
-            try {
-                const { header, entries } = migrateSessionLines(readSessionLines(file).lines, file);
-                let name;
-                let firstPrompt;
-                let messageCount = 0;
-                for (const entry of entries) {
-                    if (entry.type === "session_info" && entry.name !== undefined)
-                        name = entry.name;
-                    if (entry.type !== "message" || entry.message.role === "system")
-                        continue;
-                    messageCount++;
-                    if (firstPrompt === undefined && entry.message.role === "user") {
-                        const { content } = entry.message;
-                        firstPrompt =
-                            typeof content === "string"
-                                ? content
-                                : content.map((block) => (block.type === "text" ? block.text : "")).join("");
-                    }
-                }
-                const item = {
-                    id: header.id,
-                    file,
-                    cwd: header.cwd,
-                    createdAt: header.timestamp,
-                    modifiedAt: statSync(file).mtime.toISOString(),
-                    messageCount,
-                };
-                if (name !== undefined)
-                    item.name = name;
-                if (isSubagentSession(header, entries[0]))
-                    item.subagent = true;
-                if (firstPrompt !== undefined)
-                    item.firstPrompt = firstPrompt.slice(0, 200);
-                items.push(item);
-            }
-            catch {
-                // 损坏 / 不可读：列表里跳过（sessions show 会给出具体错误）
-            }
-        }
-        return items;
+        return listSessionItems(dir);
     }
     // -------------------------------------------------------------------------
     // SessionManagerApi
@@ -163,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) {
@@ -175,8 +166,25 @@ 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);
+    }
+    /** 已卸载图片的条目数（测试与诊断用）。 */
+    offloadedCount() {
+        return this.images.size;
     }
     leafLine() {
         return { type: "leaf", id: this.leaf, timestamp: this.now().toISOString() };
@@ -185,11 +193,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,
         };
     }
@@ -206,16 +212,30 @@ export class SessionManager {
     setName(name) {
         this.append({ type: "session_info", name });
     }
-    fork(entryId) {
+    fork(entryId, forkOptions = {}) {
         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,
+                id: newEntryId(indexEntries(copied)),
+                parentId: null,
+                timestamp: this.now().toISOString(),
+            };
+            if (copied[0] !== undefined)
+                copied[0].parentId = head.id;
+            copied.unshift(head);
+        }
         const options = { now: this.now };
         const parentFile = this.file();
         if (parentFile !== undefined)
             options.parentSession = parentFile;
-        const header = SessionManager.newHeader(this.cwd, options, this.now());
+        const header = SessionManager.newHeader(forkOptions.cwd ?? this.cwd, options, this.now());
         let storage;
         if (this.storage.kind === "memory")
             storage = { kind: "memory" };
@@ -223,7 +243,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;
@@ -241,11 +261,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);
@@ -254,6 +282,7 @@ export class SessionManager {
             lock = undefined;
         }
         this.storage = { kind: "file", file, lock };
+        this.syncImages();
         return file;
     }
     isPersisted() {

package/dist/session/migrate.d.ts

@@ -7,7 +7,8 @@
  * - 缺头 / 头损坏 / 条目缺 id → 拒绝，不猜测、不重写文件。
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
- * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）。
+ * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
  */
 import type { SessionEntry, SessionHeader, SessionLine } from "./types.js";
 export interface MigratedSession {

package/dist/session/migrate.js

@@ -7,7 +7,8 @@
  * - 缺头 / 头损坏 / 条目缺 id → 拒绝，不猜测、不重写文件。
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
- * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）。
+ * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
  */
 import { AmaError } from "../errors.js";
 import { SESSION_FORMAT_VERSION } from "./types.js";

package/dist/session/offload.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 会话图片卸载（#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` 驻留后
+ *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
+ *   保留 `""` 并告警，不再重试；
+ * - `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 class ImageOffload {
+    private readonly warn;
+    /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
+    private readonly locators;
+    private readonly offloaded;
+    constructor(warn?: (message: string) => 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;
+}