@armadra/agent 0.7.4 → 0.7.5

package/dist/cli/bootstrap.js

@@ -76,7 +76,8 @@ export async function bootstrap(argsIn, deps, io) {
         request = { kind: "resume", id };
     }
     const sessionRequest = request;
-    const sessionManager = await step(ExitCode.Session, m().steps.session, () => deps.sessions.open(sessionRequest, { sessionDir: paths.sessionDir, cwd: paths.cwd }));
+    // [#165] 会话替换后跟随当前会话（闭包只经它取，启动会话的 manager 不被常驻）
+    let sessionManager = await step(ExitCode.Session, m().steps.session, () => deps.sessions.open(sessionRequest, { sessionDir: paths.sessionDir, cwd: paths.cwd }));
     let sessionCwd = sessionManager.cwd;
     if (!existsSync(sessionCwd)) {
         const replacement = interactive ? await deps.ui?.askCwd?.(sessionCwd) : undefined;
@@ -281,6 +282,8 @@ export async function bootstrap(argsIn, deps, io) {
             uiBroker: () => uiBroker,
             onSessionReplaced: (next) => {
                 session = next;
+                sessionManager = next.manager ?? sessionManager;
+                assembly.sessionManager = sessionManager;
             },
             sessionStartContext: () => sessionStartContext,
             unattended,
@@ -302,7 +305,7 @@ export async function bootstrap(argsIn, deps, io) {
         if (Object.keys(overrides).length > 0)
             assembly.overrides = overrides;
         session = await step(ExitCode.RuntimeError, m().steps.assembly, () => deps.session.create(assembly));
-        const active = session;
+        const active = session; // 只同步使用：闭包捕获它会让启动会话常驻（#165）
         let disposed;
         shutdown = (reason) => {
             disposed ??= (async () => {
@@ -310,7 +313,7 @@ export async function bootstrap(argsIn, deps, io) {
                 await hooks.run("SessionEnd", { reason }).catch(() => undefined);
                 await disposeHost(host, (e) => warn(m().hostDisposeFailed(String(e))));
                 // 会话被替换过时 dispose 当前那个（旧会话由替换方负责）
-                await (session ?? active).dispose();
+                await session?.dispose();
             })();
             return disposed;
         };
@@ -339,8 +342,13 @@ export async function bootstrap(argsIn, deps, io) {
             providers,
             model,
             thinkingLevel,
-            sessionManager,
-            session: active,
+            // [#165] 跟随当前会话（ACP 关掉启动会话后它可被回收）
+            get sessionManager() {
+                return sessionManager;
+            },
+            get session() {
+                return session;
+            },
             hooks,
             host,
             permission,

package/dist/cli/deps.d.ts

@@ -107,7 +107,7 @@ export interface SessionAssembly {
     /**
      * 模式层把当前会话换成另一个（`/new`、`/resume`、`/fork`、RPC `switch_session`）后调用：
      * bootstrap 让 HostApi.session.*、宿主 sendUser、Hook 公共字段与退出时的 dispose 跟随 `next`。
-     * 旧会话由调用方自行 dispose；`Runtime.session` 仍指初始会话。
+     * 旧会话由调用方自行 dispose；`Runtime.session` / `sessionManager` 也随之指向 `next`（#165）。
      */
     onSessionReplaced(next: AgentSession): void;
     /** SessionStart Hook 的 additionalContext（系统提示 hooks 节）；首次装配系统提示时读取。 */

package/dist/modes/acp/acp-server.js

@@ -19,9 +19,10 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { stopReasonOf } from "../../ai/apis/shared.js";
-import { createSessionAlongside, currentSession, disposeSessionAlongside, setForegroundSession, } from "../../cli/compose-session.js";
+import { createSessionAlongside, currentSession, setForegroundSession, } from "../../cli/compose-session.js";
 import { listSessions } from "../../cli/compose-store.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { taskControl } from "../../agents/task-control.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { isPermissionMode } from "../../permissions/modes.js";
@@ -31,7 +32,7 @@ import { AcpEventMapper, permissionModes, toolKind, toolLocations, toolTitle, }
 import { msg } from "../../i18n/index.js";
 import { CONFIG_IDS, applyConfigOption, availableCommands, buildConfigOptions, prepareConfigOptions, } from "./acp-config.js";
 import { clientCapabilitiesOf } from "./acp-connection.js";
-import { PromptQueue, cancelledResult, pageSessions, promptWhenIdle, sessionTitle, } from "./acp-sessions.js";
+import { PromptQueue, cancelledResult, disposeQuiet, pageSessions, promptWhenIdle, quiesce, sessionTitle, } from "./acp-sessions.js";
 export const ACP_AGENT_CAPABILITIES = {
     loadSession: true,
     promptCapabilities: { image: true, audio: false, embeddedContext: true },
@@ -157,8 +158,9 @@ export class AcpServer {
                 .abort()
                 .catch(() => undefined);
         await this.queue.settled();
-        for (const session of this.sessions())
-            await session.waitForIdle().catch(() => undefined);
+        for (const s of this.sessions())
+            if (s instanceof AgentSessionImpl)
+                await quiesce(s, taskControl(s.state.sessionId));
         const foreground = this.session();
         for (const entry of this.pool.values())
             entry.unsubscribe();
@@ -167,7 +169,7 @@ export class AcpServer {
                 continue;
             if (!(foreground instanceof AgentSessionImpl))
                 continue;
-            await disposeSessionAlongside(this.runtime, session, foreground).catch(() => undefined);
+            await disposeQuiet(this.runtime, session, foreground).catch(() => undefined);
         }
         this.pool.clear();
         this.standby = undefined;
@@ -311,12 +313,11 @@ export class AcpServer {
             return {};
         this.pool.delete(id);
         this.queue.cancelQueued(id);
-        const running = this.queue.running;
-        if (running?.sessionId === id) {
-            running.cancelRequested = true;
-            await entry.session.abort().catch(() => undefined);
-            await this.queue.settled(id);
-        }
+        // [#167] 通知回合不经队列：不论谁在跑都先安静下来（停后台任务、abort 到空闲）
+        if (this.queue.running?.sessionId === id)
+            this.queue.running.cancelRequested = true;
+        await quiesce(entry.session, taskControl(id));
+        await this.queue.settled(id);
         entry.unsubscribe();
         let fallback = this.session();
         if (fallback === entry.session) {
@@ -330,7 +331,7 @@ export class AcpServer {
             }
         }
         if (fallback instanceof AgentSessionImpl)
-            await disposeSessionAlongside(this.runtime, entry.session, fallback);
+            await disposeQuiet(this.runtime, entry.session, fallback, taskControl(id));
         return {};
     }
     async prompt(params, signal) {
@@ -377,16 +378,17 @@ export class AcpServer {
         setForegroundSession(this.runtime, session);
         if (this.runtime.permission.mode !== entry.mode)
             session.setPermissionMode(entry.mode);
-        const before = session.getStats().tokens;
+        let before = session.getStats().tokens;
         let failure;
         try {
-            await promptWhenIdle(session, job);
+            // [#166] 起点取在真正发起时：等待期间结束的通知回合不计入本次 usage
+            await promptWhenIdle(session, job, () => void (before = session.getStats().tokens));
         }
         catch (error) {
             failure = error;
         }
-        await this.peer.flush();
         const after = session.getStats().tokens;
+        await this.peer.flush();
         const usage = {
             inputTokens: after.input - before.input,
             outputTokens: after.output - before.output,

package/dist/modes/acp/acp-sessions.d.ts

@@ -8,6 +8,8 @@
  */
 import type { ImageBlock } from "../../ai/types.js";
 import type { AgentSessionImpl } from "../../agent/session.js";
+import type { TaskControl } from "../../agents/task-control.js";
+import type { Runtime } from "../../cli/runtime.js";
 import type { AgentMessage, SessionListItem } from "../../session/types.js";
 import { type AcpPromptResult, type AcpListSessionsResult } from "../../drivers/acp/types.js";
 import type { PermissionMode } from "../../permissions/types.js";
@@ -86,4 +88,15 @@ export declare function pageSessions(items: readonly SessionListItem[], cursor:
  * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
  * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
  */
-export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob): Promise<void>;
+export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob, onStart?: () => void): Promise<void>;
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export declare function quiesce(session: AgentSessionImpl, control: TaskControl | undefined, rounds?: number): Promise<boolean>;
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export declare function disposeQuiet(runtime: Runtime, session: AgentSessionImpl, fallback: AgentSessionImpl, control?: TaskControl, retries?: number): Promise<void>;

package/dist/modes/acp/acp-sessions.js

@@ -6,6 +6,7 @@
  * - 同一时刻只跑一个回合，其它会话的 `session/prompt` 进 {@link PromptQueue}（FIFO），不再回 busy；
  * - `session/list`：按 `updatedAt` 降序、`sessionId` 次序分页，cursor 是 `updatedAt|sessionId` 的 base64。
  */
+import { disposeSessionAlongside } from "../../cli/compose-session.js";
 import { RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
 import { AmaError } from "../../errors.js";
@@ -164,12 +165,14 @@ export function pageSessions(items, cursor, pageSize = LIST_PAGE_SIZE) {
  * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
  * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
  */
-export async function promptWhenIdle(session, job) {
+export async function promptWhenIdle(session, job, onStart) {
     for (;;) {
         // 等周期而不是看 `state.isStreaming`：busy 以周期为准，周期的收尾阶段 isStreaming 已是 false
         await session.waitForIdle();
         if (job.cancelRequested)
             return;
+        // [#166] 每次真正发起前回调（busy 重试时再调，最后一次为准）：usage 的起点不含之前的通知回合
+        onStart?.();
         try {
             await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
             return;
@@ -180,3 +183,43 @@ export async function promptWhenIdle(session, job) {
         }
     }
 }
+const BUSY = Symbol("busy");
+/** 当前没有周期（含收尾阶段）：`waitForIdle()` 已结算即空闲。 */
+async function idleNow(session) {
+    return (await Promise.race([session.waitForIdle(), Promise.resolve(BUSY)])) !== BUSY;
+}
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export async function quiesce(session, control, rounds = 50) {
+    for (const task of control?.list() ?? [])
+        if (task.status === "running")
+            await control?.stop(task.taskId).catch(() => undefined);
+    for (let i = 0; i < rounds; i++) {
+        await session.abort();
+        await new Promise((resolve) => setImmediate(resolve));
+        if (await idleNow(session))
+            return true;
+    }
+    return false;
+}
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export async function disposeQuiet(runtime, session, fallback, control, retries = 3) {
+    for (let i = 0;; i++) {
+        try {
+            await disposeSessionAlongside(runtime, session, fallback);
+            break;
+        }
+        catch (error) {
+            if (i >= retries || !(error instanceof AmaError && error.code === "busy"))
+                throw error;
+            await quiesce(session, control);
+        }
+    }
+    await session.abort();
+}

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 readonly 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,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): {

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,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() };
@@ -147,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,
         };
     }
@@ -172,7 +216,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 +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;
@@ -214,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);
@@ -227,6 +282,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,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;
+}