@armadra/agent 0.7.3 → 0.7.5

package/dist/tools/bash.d.ts

@@ -3,7 +3,7 @@
  *
  * - `spawn(shell, args, { detached: !win, stdio: [ignore, pipe, pipe] })`，stdout / stderr 合流；
  * - 超时（缺省 120 s，上限 600 s）与 abort 都走 `killProcessTree`：SIGTERM → 2 s → SIGKILL；
- * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB）尾截断并落全文；
+ * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB 与会话结果上限减余量取小）尾截断并落全文；
  * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
  *   信号退出 `128 + signo`；非零退出码 → isError；
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。

package/dist/tools/bash.js

@@ -3,7 +3,7 @@
  *
  * - `spawn(shell, args, { detached: !win, stdio: [ignore, pipe, pipe] })`，stdout / stderr 合流；
  * - 超时（缺省 120 s，上限 600 s）与 abort 都走 `killProcessTree`：SIGTERM → 2 s → SIGKILL；
- * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB）尾截断并落全文；
+ * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB 与会话结果上限减余量取小）尾截断并落全文；
  * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
  *   信号退出 `128 + signo`；非零退出码 → isError；
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
@@ -21,7 +21,7 @@ import { resolvePath } from "./paths.js";
 import { buildShellArgs, buildToolEnv, resolveShell } from "./shell.js";
 import { exitCodeOf, isGroupAlive, killProcessTree, trackProcessGroup, untrackProcessGroup, } from "./process-tree.js";
 import { OutputAccumulator } from "./output-accumulator.js";
-import { formatSize, resolveOutputDir, safeFileName } from "./truncate.js";
+import { formatSize, resolveOutputDir, safeFileName, toolOutputBytes } from "./truncate.js";
 import { jobsForSession } from "./background-jobs.js";
 import { looksLikeSandboxDenial, runsSandboxed, sandboxDenialHint, wrapBashCommand, } from "../sandbox/bash.js";
 export const DEFAULT_BASH_TIMEOUT_MS = 120_000;
@@ -128,6 +128,7 @@ export async function executeBash(input, ctx, options = {}) {
         return startBackground(command, { cwd, env, shell, isWindows, sandbox }, ctx, options);
     const started = Date.now();
     const acc = new OutputAccumulator({
+        maxBytes: toolOutputBytes(ctx.maxResultChars),
         spillPath: () => join(resolveOutputDir(ctx.outputDir), safeFileName(`bash-${ctx.toolCallId}.log`)),
     });
     let child;
@@ -345,8 +346,8 @@ export function createBashTool(options = {}) {
     return {
         name: "bash",
         label: "Bash",
-        description: "Run a shell command; stdout+stderr combined, keeps the last 2000 lines / 50 KB (full " +
-            `output saved). Timeout ${DEFAULT_BASH_TIMEOUT_MS / 1000} s, max ${MAX_BASH_TIMEOUT_MS / 1000} s. ` +
+        description: "Run a shell command; stdout+stderr combined, keeps the tail (full output saved to a " +
+            `file). Timeout ${DEFAULT_BASH_TIMEOUT_MS / 1000} s, max ${MAX_BASH_TIMEOUT_MS / 1000} s. ` +
             "background:true gives a job id for {job, action}." +
             sandboxDescription(options.sandbox),
         parameters: {

package/dist/tools/glob.d.ts

@@ -5,7 +5,7 @@
  * 以 `!` 开头的模式是排除。不含 `/` 的模式匹配**文件名**（任意深度），含 `/` 的匹配相对搜索根的
  * 路径。点文件同样参与匹配（`.git` 由遍历层排除）。Windows 上大小写不敏感。
  *
- * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 1000。
+ * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 200（[ME-D] P2-2，原 1000）。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 export interface GlobBodyOptions {
@@ -32,7 +32,7 @@ export interface GlobInput {
     path?: string;
     limit?: number;
 }
-export declare const DEFAULT_GLOB_LIMIT = 1000;
+export declare const DEFAULT_GLOB_LIMIT = 200;
 export interface GlobMatchFile {
     abs: string;
     rel: string;

package/dist/tools/glob.js

@@ -5,7 +5,7 @@
  * 以 `!` 开头的模式是排除。不含 `/` 的模式匹配**文件名**（任意深度），含 `/` 的匹配相对搜索根的
  * 路径。点文件同样参与匹配（`.git` 由遍历层排除）。Windows 上大小写不敏感。
  *
- * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 1000。
+ * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 200（[ME-D] P2-2，原 1000）。
  */
 import { stat } from "node:fs/promises";
 import { displayPath, resolvePath } from "./paths.js";
@@ -145,7 +145,7 @@ export class GlobMatcher {
         return included && !this.exclude.some((g) => GlobMatcher.hit(g, rel));
     }
 }
-export const DEFAULT_GLOB_LIMIT = 1000;
+export const DEFAULT_GLOB_LIMIT = 200;
 /** 收集匹配文件并按 mtime 倒序（同 mtime 按路径）。 */
 export async function globFiles(root, pattern, signal) {
     const matcher = new GlobMatcher(pattern);

package/dist/tools/grep.js

@@ -13,7 +13,7 @@ import { displayPath, resolvePath } from "./paths.js";
 import { walk } from "./ignore.js";
 import { GlobMatcher } from "./glob.js";
 import { isBinary } from "./read.js";
-import { DEFAULT_MAX_BYTES, truncateHead, truncateLine } from "./truncate.js";
+import { formatSize, toolOutputBytes, truncateHead, truncateLine } from "./truncate.js";
 export const DEFAULT_GREP_LIMIT = 100;
 export const GREP_MAX_FILE_BYTES = 2 * 1024 * 1024;
 export const GREP_CONCURRENCY = 16;
@@ -141,16 +141,14 @@ export async function executeGrep(input, ctx) {
     if (matches === 0)
         return { content: "No matches found", details: { matches: 0, files: 0 } };
     const joined = blocks.join(context > 0 ? "\n--\n" : "\n");
-    const cut = truncateHead(joined, {
-        maxLines: Number.MAX_SAFE_INTEGER,
-        maxBytes: DEFAULT_MAX_BYTES,
-    });
+    const maxBytes = toolOutputBytes(ctx.maxResultChars);
+    const cut = truncateHead(joined, { maxLines: Number.MAX_SAFE_INTEGER, maxBytes });
     let content = cut.content;
     if (limited) {
         content += `\n\n[Stopped at ${limit} matches. Narrow the search or raise limit.]`;
     }
     else if (cut.truncated) {
-        content += "\n\n[Output truncated at 50 KB. Narrow the search.]";
+        content += `\n\n[Output truncated at ${formatSize(maxBytes)}. Narrow the search.]`;
     }
     return {
         content,

package/dist/tools/image-file.js

@@ -10,6 +10,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { extname } from "node:path";
 import { AmaError } from "../errors.js";
+import { internImage } from "../ai/image-intern.js";
 import { DEFAULT_IMAGE_BASE64_LIMIT, MAX_IMAGE_EDGE, base64Size, formatMb, } from "../ai/image-limits.js";
 import { resizeImage } from "./image-resize.js";
 /** 读进内存前的硬上限（原始字节）：再大的文件缩放也不现实，直接拒绝。 */
@@ -218,7 +219,7 @@ export async function loadImageFile(path, options = {}) {
     if (!fit.ok)
         throw fitError(path, fit, limit, buf.length, options.resize === "off");
     return {
-        block: { type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType },
+        block: internImage({ type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType }),
         path,
         mimeType: fit.mimeType,
         bytes: fit.buf.length,

package/dist/tools/read-lines.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ *
+ * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
+ * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）
+ * 逐字节相同：
+ * - 行终止符是 `\r\n`、`\n` 或孤立 `\r`（`normalizeToLF` 把孤立 `\r` 也当换行，R1）；块边界上的
+ *   `\r` | `\n` 记作一个终止符；最后一个终止符之后还有字节则多一行；
+ * - UTF-8 BOM 只看文件前 3 字节；
+ * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
+ * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
+ *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
+ */
+/** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
+export declare const STREAM_READ_THRESHOLD: number;
+export interface LineWindow {
+    /** 窗口内的行：首行已去 BOM、已按 LF 切分、已去行尾 `\r`。 */
+    lines: string[];
+    /** 全文行数（口径同 `normalized.replace(/\n$/, "").split("\n")`）。 */
+    totalLines: number;
+    /** 因 `maxBytes` 提前停止收集。 */
+    truncatedBy?: "bytes";
+    /** 文件以 UTF-8 BOM 开头。 */
+    bom: boolean;
+}
+/** 文件开头至多 `bytes` 字节（一次 `readSync`，用于二进制嗅探）。 */
+export declare function readHead(abs: string, bytes: number): Buffer;
+/** `readHead` 的异步版（#171）。 */
+export declare function readHeadAsync(abs: string, bytes: number): Promise<Buffer>;
+/**
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
+ */
+export declare class LineScanner {
+    private readonly first;
+    private readonly stop;
+    private readonly maxBytes;
+    private readonly lineCap;
+    private readonly lines;
+    private truncatedBy;
+    private collected;
+    private index;
+    private parts;
+    private partBytes;
+    private pending;
+    private skipLF;
+    private bom;
+    private firstChunk;
+    constructor(first: number, stop: number, maxBytes: number);
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf: Buffer, end: number, eof: boolean): number;
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish(): LineWindow;
+    private collecting;
+    private take;
+    private endLine;
+}
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
+ */
+export declare function readLineWindow(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): LineWindow;
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export declare function readLineWindowAsync(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): Promise<LineWindow>;

package/dist/tools/read-lines.js

@@ -0,0 +1,224 @@
+/**
+ * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ *
+ * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
+ * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）
+ * 逐字节相同：
+ * - 行终止符是 `\r\n`、`\n` 或孤立 `\r`（`normalizeToLF` 把孤立 `\r` 也当换行，R1）；块边界上的
+ *   `\r` | `\n` 记作一个终止符；最后一个终止符之后还有字节则多一行；
+ * - UTF-8 BOM 只看文件前 3 字节；
+ * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
+ * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
+ *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { open } from "node:fs/promises";
+/** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
+export const STREAM_READ_THRESHOLD = 1024 * 1024;
+const CHUNK_BYTES = 64 * 1024;
+/** 截短超长行时多留的字节：盖住行号前缀与 `sliceHeadBytes` 回退到字符起点的余量。 */
+const LINE_SLACK = 64;
+const LF = 0x0a;
+const CR = 0x0d;
+/** 文件开头至多 `bytes` 字节（一次 `readSync`，用于二进制嗅探）。 */
+export function readHead(abs, bytes) {
+    const fd = openSync(abs, "r");
+    try {
+        const buf = Buffer.alloc(bytes);
+        let got = 0;
+        while (got < bytes) {
+            const n = readSync(fd, buf, got, bytes - got, null);
+            if (n === 0)
+                break;
+            got += n;
+        }
+        return buf.subarray(0, got);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** `readHead` 的异步版（#171）。 */
+export async function readHeadAsync(abs, bytes) {
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(bytes);
+        let got = 0;
+        while (got < bytes) {
+            const { bytesRead } = await handle.read(buf, got, bytes - got, null);
+            if (bytesRead === 0)
+                break;
+            got += bytesRead;
+        }
+        return buf.subarray(0, got);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
+ */
+export class LineScanner {
+    first;
+    stop;
+    maxBytes;
+    lineCap;
+    lines = [];
+    truncatedBy;
+    collected = 0;
+    index = 0; // 已完成的行数
+    parts = [];
+    partBytes = 0;
+    pending = false; // 最后一个终止符之后已有字节
+    skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
+    bom = false;
+    firstChunk = true;
+    constructor(first, stop, maxBytes) {
+        this.first = first;
+        this.stop = stop;
+        this.maxBytes = maxBytes;
+        this.lineCap = maxBytes + LINE_SLACK;
+    }
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf, end, eof) {
+        let pos = 0;
+        if (this.firstChunk) {
+            if (end < 3 && !eof)
+                return end;
+            this.firstChunk = false;
+            if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+                this.bom = true;
+                pos = 3;
+            }
+        }
+        if (this.skipLF && pos < end) {
+            if (buf[pos] === LF)
+                pos++;
+            this.skipLF = false;
+        }
+        let nextLF = buf.indexOf(LF, pos);
+        let nextCR = buf.indexOf(CR, pos);
+        while (pos < end) {
+            if (nextLF !== -1 && nextLF < pos)
+                nextLF = buf.indexOf(LF, pos);
+            if (nextCR !== -1 && nextCR < pos)
+                nextCR = buf.indexOf(CR, pos);
+            const lf = nextLF === -1 || nextLF >= end ? end : nextLF;
+            const cr = nextCR === -1 || nextCR >= end ? end : nextCR;
+            const at = Math.min(lf, cr);
+            if (at > pos) {
+                this.pending = true;
+                if (this.collecting())
+                    this.take(buf, pos, at);
+            }
+            if (at === end)
+                break;
+            this.endLine();
+            pos = at + 1;
+            if (at === cr) {
+                if (pos < end) {
+                    if (buf[pos] === LF)
+                        pos++;
+                }
+                else {
+                    this.skipLF = true;
+                }
+            }
+        }
+        return 0;
+    }
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish() {
+        if (this.pending)
+            this.endLine();
+        const { lines, truncatedBy, bom } = this;
+        return { lines, totalLines: this.index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+    }
+    collecting() {
+        return this.truncatedBy === undefined && this.index >= this.first && this.index < this.stop;
+    }
+    take(buf, from, to) {
+        if (to <= from || this.partBytes >= this.lineCap)
+            return;
+        const end = Math.min(to, from + this.lineCap - this.partBytes);
+        this.parts.push(Buffer.from(buf.subarray(from, end)));
+        this.partBytes += end - from;
+    }
+    endLine() {
+        if (this.collecting()) {
+            const { parts } = this;
+            const line = (parts.length === 1 ? parts[0] : Buffer.concat(parts)).toString("utf8");
+            this.lines.push(line);
+            this.collected += Buffer.byteLength(line) + 1;
+            if (this.collected > this.maxBytes)
+                this.truncatedBy = "bytes";
+        }
+        if (this.partBytes > 0)
+            this.parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
+        this.partBytes = 0;
+        this.pending = false;
+        this.index++;
+    }
+}
+function scanner(offset, limit, maxBytes) {
+    const first = offset - 1;
+    return new LineScanner(first, limit === undefined ? Infinity : first + limit, maxBytes);
+}
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
+ */
+export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
+    const size = Math.max(3, chunkBytes);
+    const fd = openSync(abs, "r");
+    try {
+        const buf = Buffer.alloc(size);
+        let carry = 0; // 首块凑满 3 字节判断 BOM
+        for (;;) {
+            const n = readSync(fd, buf, carry, size - carry, null);
+            const end = carry + n;
+            if (end === 0)
+                break;
+            carry = scan.feed(buf, end, n === 0);
+            if (n === 0)
+                break;
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    return scan.finish();
+}
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export async function readLineWindowAsync(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
+    const size = Math.max(3, chunkBytes);
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(size);
+        let carry = 0;
+        for (;;) {
+            const { bytesRead: n } = await handle.read(buf, carry, size - carry, null);
+            const end = carry + n;
+            if (end === 0)
+                break;
+            carry = scan.feed(buf, end, n === 0);
+            if (n === 0)
+                break;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return scan.finish();
+}

package/dist/tools/read.d.ts

@@ -1,10 +1,12 @@
 /**
  * `read` 工具（设计 §5.2）。[B3]
  *
- * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
- * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 字节上限先到者（50 KB 与
+ * 会话结果上限减余量取小，[ME-D] 一次截到位），末尾提示 `offset` 续读；NUL 嗅探判二进制并拒绝；
+ * png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
  * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片、超过当前端点的单图上限（base64 后，
  * [W5-I] 按端点分档）或任一边 > 8000 px 时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
+ * [M-E] 超过 1 MiB 的文本按字节窗口读（read-lines.ts），输出与整读逐字节相同。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 import { type ImageFitOptions } from "./image-file.js";
@@ -19,6 +21,8 @@ export interface ReadToolOptions {
     supportsImages?(ctx: ToolContext): boolean;
     /** [W5-I] 当前模型的单图上限与缩放设置；缺省 5 MB（base64 后）。 */
     imageOptions?(ctx: ToolContext): ImageFitOptions;
+    /** [M-E] 超过这个字节数的文本文件走字节窗口；缺省 `STREAM_READ_THRESHOLD`，测试注入 0 / Infinity。 */
+    streamThreshold?: number;
 }
 export declare function isBinary(buf: Buffer): boolean;
 /**

package/dist/tools/read.js

@@ -1,15 +1,19 @@
 /**
  * `read` 工具（设计 §5.2）。[B3]
  *
- * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
- * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 字节上限先到者（50 KB 与
+ * 会话结果上限减余量取小，[ME-D] 一次截到位），末尾提示 `offset` 续读；NUL 嗅探判二进制并拒绝；
+ * png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
  * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片、超过当前端点的单图上限（base64 后，
  * [W5-I] 按端点分档）或任一边 > 8000 px 时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
+ * [M-E] 超过 1 MiB 的文本按字节窗口读（read-lines.ts），输出与整读逐字节相同。
  */
 import { readFile, stat } from "node:fs/promises";
+import { internImage } from "../ai/image-intern.js";
 import { displayPath, resolvePath } from "./paths.js";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
+import { DEFAULT_MAX_LINES, formatSize, toolOutputBytes, truncateHead } from "./truncate.js";
 import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
+import { STREAM_READ_THRESHOLD, readHeadAsync, readLineWindowAsync } from "./read-lines.js";
 import { MAX_IMAGE_FILE_BYTES, fitImage, imageMimeFromPath, imageSize, sniffImageMime, } from "./image-file.js";
 export { imageSize } from "./image-file.js";
 const SNIFF_BYTES = 8000;
@@ -20,6 +24,7 @@ export function isBinary(buf) {
             return true;
     return false;
 }
+const binaryMessage = (shown) => `${shown} appears to be a binary file; refusing to read it`;
 function error(message) {
     return { content: message, isError: true };
 }
@@ -68,7 +73,7 @@ async function readImage(abs, shown, ctx, options) {
         : "";
     const blocks = [
         { type: "text", text: caption + note },
-        { type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType },
+        internImage({ type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType }),
     ];
     return { content: blocks, details };
 }
@@ -86,42 +91,58 @@ export async function executeRead(input, ctx, options = {}) {
         return error(`${shown} is a directory; ${directoryHint(shown, ctx)}`);
     if (imageMimeFromPath(abs) !== undefined)
         return readImage(abs, shown, ctx, options);
-    const buf = await readFile(abs);
-    if (isBinary(buf))
-        return error(`${shown} appears to be a binary file; refusing to read it`);
-    const { text } = splitBom(buf.toString("utf8"));
-    const normalized = normalizeToLF(text);
-    const allLines = normalized === "" ? [] : normalized.replace(/\n$/, "").split("\n");
+    const offset = input.offset ?? 1;
+    const badOffset = !Number.isInteger(offset) || offset < 1;
+    const badLimit = input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1);
+    const maxBytes = toolOutputBytes(ctx.maxResultChars);
+    let totalLines;
+    let selected;
+    if (info.size > (options.streamThreshold ?? STREAM_READ_THRESHOLD)) {
+        // [M-E] 大文件按字节窗口读：只解码要显示的行，结果与整读逐字节相同（D1）
+        if (isBinary(await readHeadAsync(abs, SNIFF_BYTES)))
+            return error(binaryMessage(shown));
+        const want = Math.min(input.limit ?? Infinity, DEFAULT_MAX_LINES + 1);
+        const win = await readLineWindowAsync(abs, badOffset ? 1 : offset, badOffset || badLimit ? 0 : want, maxBytes);
+        totalLines = win.totalLines;
+        selected = win.lines;
+    }
+    else {
+        const buf = await readFile(abs);
+        if (isBinary(buf))
+            return error(binaryMessage(shown));
+        const { text } = splitBom(buf.toString("utf8"));
+        const normalized = normalizeToLF(text);
+        const allLines = normalized === "" ? [] : normalized.replace(/\n$/, "").split("\n");
+        totalLines = allLines.length;
+        const end = input.limit === undefined ? undefined : offset - 1 + input.limit;
+        selected = badOffset || badLimit ? [] : allLines.slice(offset - 1, end);
+    }
     ctx.markRead(abs);
-    if (allLines.length === 0) {
+    if (totalLines === 0) {
         return { content: `(${shown} is empty)`, details: { path: abs, totalLines: 0 } };
     }
-    const offset = input.offset ?? 1;
-    if (!Number.isInteger(offset) || offset < 1)
+    if (badOffset)
         return error("offset must be an integer ≥ 1");
-    if (offset > allLines.length) {
-        return error(`offset ${offset} is beyond the end of ${shown} (${allLines.length} lines)`);
+    if (offset > totalLines) {
+        return error(`offset ${offset} is beyond the end of ${shown} (${totalLines} lines)`);
     }
-    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1)) {
+    if (badLimit)
         return error("limit must be an integer ≥ 1");
-    }
-    const end = input.limit === undefined ? allLines.length : offset - 1 + input.limit;
-    const selected = allLines.slice(offset - 1, end);
     const numbered = numberLines(selected, offset);
-    const cut = truncateHead(numbered, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+    const cut = truncateHead(numbered, { maxLines: DEFAULT_MAX_LINES, maxBytes });
     const lastShown = offset - 1 + cut.outputLines;
     let content = cut.content;
-    if (lastShown < allLines.length) {
+    if (lastShown < totalLines) {
         const reason = cut.truncated
-            ? ` (output limit ${cut.truncatedBy === "bytes" ? formatSize(DEFAULT_MAX_BYTES) : `${DEFAULT_MAX_LINES} lines`} reached)`
+            ? ` (output limit ${cut.truncatedBy === "bytes" ? formatSize(maxBytes) : `${DEFAULT_MAX_LINES} lines`} reached)`
             : "";
-        content += `\n\n[Showing lines ${offset}-${lastShown} of ${allLines.length}${reason}. Use offset=${lastShown + 1} to continue.]`;
+        content += `\n\n[Showing lines ${offset}-${lastShown} of ${totalLines}${reason}. Use offset=${lastShown + 1} to continue.]`;
     }
     return {
         content,
         details: {
             path: abs,
-            totalLines: allLines.length,
+            totalLines,
             firstLine: offset,
             lastLine: lastShown,
             truncated: cut.truncated,
@@ -132,9 +153,8 @@ export function createReadTool(options = {}) {
     return {
         name: "read",
         label: "Read",
-        description: "Read a file. Text comes with line numbers (cat -n), limited to " +
-            `${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; page with offset/limit. ` +
-            "Images (png, jpg, gif, webp) come as attachments.",
+        description: "Read a file with line numbers (cat -n); page with offset/limit, a cut result says where " +
+            "to continue. Images (png, jpg, gif, webp) come as attachments.",
         parameters: {
             type: "object",
             properties: {

package/dist/tools/task.d.ts

@@ -12,6 +12,8 @@
  * - **parallel**：同一回复里的多个 task 真并行（会话注册表的池限流，缺省 4）；与 sequential 工具
  *   （edit 等）同批时仍按 tool-runner 的规则整批串行。
  * - 深度 ≤ 1：子会话的工具表里保留 task（与父字节一致，缓存前缀可复用），运行时在这里拒绝。
+ * - [ME-A] `context: "fork"`：子会话继承本会话已完成的回合（同模型、同前缀）；`details.context` 是实际
+ *   模式（不满足条件时回落 `fresh`）。
  * - 结果 = 子 Agent 的最终报告（> 50 KB 截头尾、全文落 outputs/，见 agents/result.ts）+ details。
  */
 import type { ModelThinkingLevel } from "../ai/types.js";
@@ -31,10 +33,17 @@ export interface TaskInput {
     model?: string;
     thinkingLevel?: ModelThinkingLevel;
     maxTurns?: number;
+    context?: "fork" | "fresh";
 }
 /** 预留（并发上限在会话的任务注册表，见 agent/subagent-registry.ts）。 */
 export interface TaskToolOptions {
 }
+/**
+ * [ME-A] 两版描述共用的开头：fresh / fork 两种上下文。default+task 与 codemode-only 的预算余量都只有
+ * 几十 token，加 `context` 参数时整段改写、字符数基本不增（`agent` 参数的「Default general」也去掉，
+ * 清单里 general 已标 default）。
+ */
+export declare const TASK_CONTEXT_LEAD: string;
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
 export declare const FOREGROUND_DESCRIPTION: string;
 /** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */