@armadra/agent 0.7.3 → 0.7.5

package/dist/session/offload.js

@@ -0,0 +1,195 @@
+/**
+ * 会话图片卸载（#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 { 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 class ImageOffload {
+    warn;
+    /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
+    locators = new Map();
+    offloaded = new Set();
+    constructor(warn = () => { }) {
+        this.warn = warn;
+    }
+    /** 记下条目的行位置；不含图片的条目忽略。 */
+    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.warn(`cannot read session entry ${entry.id} back from ${file}: ${String(error)}`);
+            return undefined;
+        }
+    }
+}

package/dist/session/projection.d.ts

@@ -5,8 +5,11 @@
  *   `firstKeptEntryId` 到 compaction 之间的非 system 条目，再放 compaction 之后的条目。
  * - `buildProjection(branch)`：对上一步的条目套用 `context_edit`（同一目标在活动分支上最新一条赢；
  *   `null` 剔除，字符串只换内容、保留角色与元数据），并把每个条目映射为 `AgentMessage`。
- *   有 compaction 时，compaction 之前的全部 system 消息折成一条完整的 system 检查点放在最前
- *   （会话条目里不另存检查点，重放即可得到）。
+ *   有 compaction 时（[ME-B] D4「开头只写一次」）：检查点只重放**对话开始前**（首条非 system
+ *   条目之前）的 system 消息，与压缩前请求的开头逐字节相同；此后到 compaction 之间的补丁合并成一条
+ *   合成补丁放在摘要之后，由 normalizeContext 渲染为尾部提醒。合成补丁的 `toolsAdded` 按首次出现
+ *   的顺序、用首次发送的声明，工具表与压缩前一致；多次压缩递归成立（都从原始条目重放）。
+ *   会话条目里不另存检查点与合成补丁，重放即可得到。
  * - `buildContext(branch)`：投影消息 + 路径上最近的模型 / 思考级别选择。
  */
 import type { Message, ModelRef, ModelThinkingLevel, SystemMessage, ToolDecl } from "../ai/types.js";
@@ -42,9 +45,19 @@ export interface SystemState {
     sections: Record<string, string>;
     tools: ToolDecl[];
 }
-/** 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。 */
+/**
+ * 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。
+ * 工具「保留原位、只换内容」（与 normalizeContext 一致）；同一条里先加后删（`diffSystem` 的补丁两者
+ * 不相交，只有压缩的合成补丁会对同名既加又删：声明过、现已移除）。
+ */
 export declare function replaySystem(messages: Iterable<AgentMessage | Message>): SystemState | undefined;
 /** 把重放结果写成一条完整的 system 消息。 */
 export declare function systemCheckpoint(state: SystemState, timestamp: number): SystemMessage;
+/**
+ * 压缩的合成补丁：`head`（对话开始前的状态）→ 之后全部补丁重放的结果。节按差异给；工具先列对话中
+ * 首次出现的新名字（首次发送的声明，normalizeContext 冻结的就是它），再列内容有更新的（只更新重放
+ * 状态，不改请求工具表）；移除 = 声明过而现在不在。无差异 → undefined。
+ */
+export declare function synthesizeSystemPatch(head: SystemState, later: readonly SystemMessage[], timestamp: number): SystemMessage | undefined;
 export declare function buildProjection(branch: readonly SessionEntry[]): Projection;
 export declare function buildContext(branch: readonly SessionEntry[]): ProjectedContext;

package/dist/session/projection.js

@@ -5,8 +5,11 @@
  *   `firstKeptEntryId` 到 compaction 之间的非 system 条目，再放 compaction 之后的条目。
  * - `buildProjection(branch)`：对上一步的条目套用 `context_edit`（同一目标在活动分支上最新一条赢；
  *   `null` 剔除，字符串只换内容、保留角色与元数据），并把每个条目映射为 `AgentMessage`。
- *   有 compaction 时，compaction 之前的全部 system 消息折成一条完整的 system 检查点放在最前
- *   （会话条目里不另存检查点，重放即可得到）。
+ *   有 compaction 时（[ME-B] D4「开头只写一次」）：检查点只重放**对话开始前**（首条非 system
+ *   条目之前）的 system 消息，与压缩前请求的开头逐字节相同；此后到 compaction 之间的补丁合并成一条
+ *   合成补丁放在摘要之后，由 normalizeContext 渲染为尾部提醒。合成补丁的 `toolsAdded` 按首次出现
+ *   的顺序、用首次发送的声明，工具表与压缩前一致；多次压缩递归成立（都从原始条目重放）。
+ *   会话条目里不另存检查点与合成补丁，重放即可得到。
  * - `buildContext(branch)`：投影消息 + 路径上最近的模型 / 思考级别选择。
  */
 function parseTime(iso) {
@@ -98,7 +101,11 @@ export function applyReplacement(message, text) {
             return message;
     }
 }
-/** 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。 */
+/**
+ * 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。
+ * 工具「保留原位、只换内容」（与 normalizeContext 一致）；同一条里先加后删（`diffSystem` 的补丁两者
+ * 不相交，只有压缩的合成补丁会对同名既加又删：声明过、现已移除）。
+ */
 export function replaySystem(messages) {
     let found = false;
     const sections = new Map();
@@ -113,12 +120,10 @@ export function replaySystem(messages) {
             else
                 sections.set(name, text);
         }
+        for (const tool of message.toolsAdded ?? [])
+            tools.set(tool.name, tool);
         for (const name of message.toolsRemoved ?? [])
             tools.delete(name);
-        for (const tool of message.toolsAdded ?? []) {
-            tools.delete(tool.name);
-            tools.set(tool.name, tool);
-        }
     }
     if (!found)
         return undefined;
@@ -131,39 +136,101 @@ export function systemCheckpoint(state, timestamp) {
         message.toolsAdded = state.tools.map((tool) => ({ ...tool }));
     return message;
 }
+function sameDecl(a, b) {
+    return (a.description === b.description && JSON.stringify(a.parameters) === JSON.stringify(b.parameters));
+}
+/**
+ * 压缩的合成补丁：`head`（对话开始前的状态）→ 之后全部补丁重放的结果。节按差异给；工具先列对话中
+ * 首次出现的新名字（首次发送的声明，normalizeContext 冻结的就是它），再列内容有更新的（只更新重放
+ * 状态，不改请求工具表）；移除 = 声明过而现在不在。无差异 → undefined。
+ */
+export function synthesizeSystemPatch(head, later, timestamp) {
+    const full = replaySystem([systemCheckpoint(head, timestamp), ...later]) ?? head;
+    const sections = {};
+    for (const [name, text] of Object.entries(full.sections))
+        if (head.sections[name] !== text)
+            sections[name] = text;
+    for (const name of Object.keys(head.sections))
+        if (!(name in full.sections))
+            sections[name] = null;
+    const sent = new Map(head.tools.map((tool) => [tool.name, tool]));
+    const added = [];
+    for (const message of later)
+        for (const tool of message.toolsAdded ?? []) {
+            if (sent.has(tool.name))
+                continue;
+            sent.set(tool.name, tool);
+            added.push(tool);
+        }
+    const now = new Map(full.tools.map((tool) => [tool.name, tool]));
+    for (const [name, tool] of sent) {
+        const current = now.get(name);
+        if (current !== undefined && !sameDecl(current, tool))
+            added.push(current);
+    }
+    const removed = [...sent.keys()].filter((name) => !now.has(name));
+    if (Object.keys(sections).length === 0 && added.length === 0 && removed.length === 0)
+        return undefined;
+    const patch = { role: "system", sections, timestamp };
+    if (added.length > 0)
+        patch.toolsAdded = added.map((tool) => ({ ...tool }));
+    if (removed.length > 0)
+        patch.toolsRemoved = removed;
+    return patch;
+}
 // ---------------------------------------------------------------------------
 // 投影
 // ---------------------------------------------------------------------------
+/** 对话开始：首条进上下文且不是 system 的条目（custom_message 算；custom / usage 等不算）。 */
+function startsConversation(entry) {
+    const message = entryToMessage(entry);
+    return message !== undefined && message.role !== "system";
+}
+function systemMessagesOf(entries) {
+    const out = [];
+    for (const entry of entries)
+        if (entry.type === "message" && entry.message.role === "system")
+            out.push(entry.message);
+    return out;
+}
+/** 压缩之前的 system 状态：开头检查点（对话开始前）+ 合成补丁（之后的全部补丁）。 */
+function compactedSystem(before, timestamp) {
+    let headEnd = before.findIndex(startsConversation);
+    if (headEnd < 0)
+        headEnd = before.length;
+    const head = replaySystem(systemMessagesOf(before.slice(0, headEnd)));
+    const later = systemMessagesOf(before.slice(headEnd));
+    const out = {};
+    if (head !== undefined)
+        out.checkpoint = systemCheckpoint(head, timestamp);
+    if (later.length === 0)
+        return out;
+    const patch = synthesizeSystemPatch(head ?? { sections: {}, tools: [] }, later, timestamp);
+    if (patch !== undefined)
+        out.patch = patch;
+    return out;
+}
 export function buildProjection(branch) {
     const edits = collectContextEdits(branch);
     const at = latestCompactionIndex(branch);
     const compaction = at >= 0 ? branch[at] : undefined;
     const items = [];
-    if (compaction !== undefined) {
-        const before = [];
-        for (const entry of branch.slice(0, at)) {
-            if (entry.type === "message" && entry.message.role === "system")
-                before.push(entry.message);
-        }
-        const state = replaySystem(before);
-        if (state !== undefined) {
-            items.push({
-                entry: compaction,
-                message: systemCheckpoint(state, parseTime(compaction.timestamp)),
-            });
-        }
-    }
+    const system = compaction === undefined
+        ? {}
+        : compactedSystem(branch.slice(0, at), parseTime(compaction.timestamp));
+    if (compaction !== undefined && system.checkpoint !== undefined)
+        items.push({ entry: compaction, message: system.checkpoint });
     for (const entry of buildContextEntries(branch)) {
         let message = entryToMessage(entry);
-        if (message === undefined)
-            continue;
-        const edit = edits.get(entry.id);
-        if (edit !== undefined) {
-            if (edit.replacement === null)
-                continue;
-            message = applyReplacement(message, edit.replacement);
+        if (message !== undefined) {
+            const edit = edits.get(entry.id);
+            if (edit === undefined)
+                items.push({ entry, message });
+            else if (edit.replacement !== null)
+                items.push({ entry, message: applyReplacement(message, edit.replacement) });
         }
-        items.push({ entry, message });
+        if (entry === compaction && system.patch !== undefined)
+            items.push({ entry: compaction, message: system.patch });
     }
     return { items, messages: items.map((item) => item.message), compaction };
 }

package/dist/session/scan.d.ts

@@ -3,7 +3,7 @@
  *
  * 与 store.ts / manager.ts 的区别：这里**从不加锁、不修复、不写文件**——正在运行的会话也能读。
  * - `sessionFilesInScope`：按 cwd（只看它的编码子目录）或全部子目录（跳过 `.trash`）列文件，最新在前；
- * - `forEachLine`：按行回调（不先 split 出整个数组）；
+ * - `forEachLine`：按块读盘、按行回调（不读全文、不 split）；提前返回即停止读盘；
  * - `lineType`：ama 写入的行以 `{"type":"…"` 开头（manager 的 append 把 type 放在第一个键），
  *   据此不解析就能跳过不需要的行；其它程序写的行退回 JSON.parse；
  * - `readSessionReadOnly`：头 + 条目 + 叶子（同 migrate.ts 的规则），末尾半行忽略、中间坏行抛错。
@@ -18,9 +18,9 @@ export declare function sessionFilesInScope(root: string, cwd?: string): string[
 export declare function findSessionFileReadOnly(root: string, id: string, cwd?: string): string;
 /**
  * 逐行回调（不含行尾 `\n` / `\r`，跳过空行）；`last` 表示文件最后一行且没有换行结尾
- * （可能是写入中途的半行）。回调返回 false 提前结束。
+ * （可能是写入中途的半行）。回调返回 false 提前结束——按块读盘（line-reader.ts），停下即不再读。
  */
-export declare function forEachLine(file: string, visit: (line: string, index: number, last: boolean) => boolean | void): void;
+export declare function forEachLine(file: string, visit: (line: string, index: number, last: boolean) => boolean | void, chunkBytes?: number): void;
 /** ama 写的行：不解析就取出 type（与消息的 role，若紧随其后）；不是这种形状时 undefined。 */
 export declare function lineType(line: string): {
     type: string;

package/dist/session/scan.js

@@ -3,14 +3,15 @@
  *
  * 与 store.ts / manager.ts 的区别：这里**从不加锁、不修复、不写文件**——正在运行的会话也能读。
  * - `sessionFilesInScope`：按 cwd（只看它的编码子目录）或全部子目录（跳过 `.trash`）列文件，最新在前；
- * - `forEachLine`：按行回调（不先 split 出整个数组）；
+ * - `forEachLine`：按块读盘、按行回调（不读全文、不 split）；提前返回即停止读盘；
  * - `lineType`：ama 写入的行以 `{"type":"…"` 开头（manager 的 append 把 type 放在第一个键），
  *   据此不解析就能跳过不需要的行；其它程序写的行退回 JSON.parse；
  * - `readSessionReadOnly`：头 + 条目 + 叶子（同 migrate.ts 的规则），末尾半行忽略、中间坏行抛错。
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { AmaError } from "../errors.js";
+import { forEachLineSync } from "./line-reader.js";
 import { migrateSessionLines } from "./migrate.js";
 import { SESSION_FILE_SUFFIX, TRASH_DIR_NAME, listSessionFiles, sessionDirForCwd, sessionIdFromFileName, } from "./store.js";
 import { msg } from "../i18n/index.js";
@@ -68,26 +69,16 @@ export function findSessionFileReadOnly(root, id, cwd) {
 }
 /**
  * 逐行回调（不含行尾 `\n` / `\r`，跳过空行）；`last` 表示文件最后一行且没有换行结尾
- * （可能是写入中途的半行）。回调返回 false 提前结束。
+ * （可能是写入中途的半行）。回调返回 false 提前结束——按块读盘（line-reader.ts），停下即不再读。
  */
-export function forEachLine(file, visit) {
-    const text = readFileSync(file, "utf8");
-    let start = 0;
+export function forEachLine(file, visit, chunkBytes) {
     let index = 0;
-    while (start < text.length) {
-        let end = text.indexOf("\n", start);
-        const last = end === -1;
-        if (last)
-            end = text.length;
-        let line = text.slice(start, end);
-        if (line.endsWith("\r"))
-            line = line.slice(0, -1);
-        start = end + 1;
+    forEachLineSync(file, (buf, _physical, last) => {
+        const line = buf.toString("utf8");
         if (line.trim() === "")
-            continue;
-        if (visit(line, index++, last) === false)
             return;
-    }
+        return visit(line, index++, last);
+    }, chunkBytes);
 }
 const TYPE_PREFIX = '{"type":"';
 /** ama 写的行：不解析就取出 type（与消息的 role，若紧随其后）；不是这种形状时 undefined。 */

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,17 +23,27 @@ export interface ReadResult {
     lines: SessionLine[];
     /** 末尾半行被截掉时为 true。 */
     repairedTail: boolean;
+    /** 给了 `onLine` 时：读完（含修复）后的文件字节数。 */
+    bytes?: number;
 }
+/** 空白行（同旧口径 `trim() === ""`）：ASCII 空白直接判定，遇到非 ASCII 字节才解码再 trim。 */
+export declare function isBlankLine(line: Buffer): boolean;
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
+ * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 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

@@ -10,6 +10,7 @@
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, readSync, rmSync, statSync, truncateSync, writeFileSync, writeSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { AmaError } from "../errors.js";
+import { forEachLineSync } from "./line-reader.js";
 export const SESSION_FILE_SUFFIX = ".jsonl";
 export const TRASH_DIR_NAME = ".trash";
 export const TRASH_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -33,75 +34,90 @@ export function sessionIdFromFileName(file) {
     const at = stem.indexOf("_");
     return at < 0 ? undefined : stem.slice(at + 1);
 }
+/** 空白行（同旧口径 `trim() === ""`）：ASCII 空白直接判定，遇到非 ASCII 字节才解码再 trim。 */
+export function isBlankLine(line) {
+    for (const byte of line) {
+        if (byte === 0x20 || (byte >= 0x09 && byte <= 0x0d))
+            continue;
+        return byte >= 0x80 && line.toString("utf8").trim() === "";
+    }
+    return true;
+}
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
+ * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 export function readSessionLines(file, options = {}) {
-    let text;
-    try {
-        text = readFileSync(file, "utf8");
-    }
-    catch (error) {
-        throw new AmaError("session_not_found", `cannot read session file ${file}`, { cause: error });
-    }
-    const rawLines = text.split("\n");
-    const endsWithNewline = text.endsWith("\n");
-    if (endsWithNewline)
-        rawLines.pop();
     const lines = [];
     let repairedTail = false;
-    for (let i = 0; i < rawLines.length; i++) {
-        const raw = (rawLines[i] ?? "").replace(/\r$/, "");
-        if (raw.trim() === "")
-            continue;
-        try {
-            lines.push(JSON.parse(raw));
-        }
-        catch (error) {
-            const isLast = i === rawLines.length - 1;
-            if (isLast && !endsWithNewline) {
-                repairedTail = true;
-                if (options.repair === true) {
-                    const keep = Buffer.byteLength(rawLines.slice(0, i).join("\n"), "utf8") + (i > 0 ? 1 : 0);
-                    truncateSync(file, keep);
+    let unterminated = false;
+    try {
+        forEachLineSync(file, (buf, index, last, offset) => {
+            if (last)
+                unterminated = true;
+            if (isBlankLine(buf))
+                return;
+            let line;
+            try {
+                line = JSON.parse(buf.toString("utf8"));
+            }
+            catch (error) {
+                if (last) {
+                    repairedTail = true;
+                    if (options.repair === true)
+                        truncateSync(file, offset);
+                    return false;
                 }
-                break;
+                throw new AmaError("session_corrupt", `${file}:${index + 1}: invalid JSON line`, {
+                    cause: error,
+                });
             }
-            throw new AmaError("session_corrupt", `${file}:${i + 1}: invalid JSON line`, {
-                cause: error,
-            });
-        }
+            options.onLine?.(line, { offset, length: buf.length });
+            lines.push(line);
+        });
     }
-    if (!repairedTail && !endsWithNewline && text.length > 0 && options.repair === true) {
+    catch (error) {
+        if (error instanceof AmaError)
+            throw error;
+        throw new AmaError("session_not_found", `cannot read session file ${file}`, { cause: error });
+    }
+    if (!repairedTail && unterminated && options.repair === true) {
         // 最后一行完整但缺 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/session/types.d.ts

@@ -199,7 +199,12 @@ export interface SessionManagerApi {
     getTree(): SessionTreeNode[];
     name(): string | undefined;
     setName(name: string): void;
-    /** 复制 root → entryId 的分支到新文件（parentSession 指回）。 */
-    fork(entryId: string): SessionManagerApi;
+    /**
+     * 复制 root → entryId 的分支到新文件（parentSession 指回）；`head` 作为新根条目，复制的首条重挂到
+     * 它下面（[ME-C0] fork 子会话的 `custom{ama.task}` 标记）。
+     */
+    fork(entryId: string, options?: {
+        head?: SessionEntryInput;
+    }): SessionManagerApi;
 }
 export {};