@armadra/agent 0.7.3 → 0.7.4

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,32 @@
+/**
+ * `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` 字节），超长行不会整行进内存。
+ */
+/** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
+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;
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ */
+export declare function readLineWindow(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): LineWindow;

package/dist/tools/read-lines.js

@@ -0,0 +1,147 @@
+/**
+ * `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` 字节），超长行不会整行进内存。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+/** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
+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);
+    }
+}
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ */
+export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const first = offset - 1;
+    const stop = limit === undefined ? Infinity : first + limit;
+    const lineCap = maxBytes + LINE_SLACK;
+    const lines = [];
+    let truncatedBy;
+    let collected = 0;
+    let index = 0; // 已完成的行数
+    let parts = [];
+    let partBytes = 0;
+    let pending = false; // 最后一个终止符之后已有字节
+    let skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
+    let bom = false;
+    const collecting = () => truncatedBy === undefined && index >= first && index < stop;
+    const take = (buf, from, to) => {
+        if (to <= from || partBytes >= lineCap)
+            return;
+        const end = Math.min(to, from + lineCap - partBytes);
+        parts.push(Buffer.from(buf.subarray(from, end)));
+        partBytes += end - from;
+    };
+    const finish = () => {
+        if (collecting()) {
+            const line = (parts.length === 1 ? parts[0] : Buffer.concat(parts)).toString("utf8");
+            lines.push(line);
+            collected += Buffer.byteLength(line) + 1;
+            if (collected > maxBytes)
+                truncatedBy = "bytes";
+        }
+        if (partBytes > 0)
+            parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
+        partBytes = 0;
+        pending = false;
+        index++;
+    };
+    const size = Math.max(3, chunkBytes);
+    const fd = openSync(abs, "r");
+    try {
+        const buf = Buffer.alloc(size);
+        let carry = 0; // 首块凑满 3 字节判断 BOM
+        let firstChunk = true;
+        for (;;) {
+            const n = readSync(fd, buf, carry, size - carry, null);
+            const end = carry + n;
+            carry = 0;
+            if (n === 0 && end === 0)
+                break;
+            let pos = 0;
+            if (firstChunk) {
+                if (end < 3 && n > 0) {
+                    carry = end;
+                    continue;
+                }
+                firstChunk = false;
+                if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+                    bom = true;
+                    pos = 3;
+                }
+            }
+            if (skipLF && pos < end) {
+                if (buf[pos] === LF)
+                    pos++;
+                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) {
+                    pending = true;
+                    if (collecting())
+                        take(buf, pos, at);
+                }
+                if (at === end)
+                    break;
+                finish();
+                pos = at + 1;
+                if (at === cr) {
+                    if (pos < end) {
+                        if (buf[pos] === LF)
+                            pos++;
+                    }
+                    else {
+                        skipLF = true;
+                    }
+                }
+            }
+            if (n === 0)
+                break;
+        }
+        if (pending)
+            finish();
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { lines, totalLines: index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+}

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, readHead, readLineWindow } 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(readHead(abs, SNIFF_BYTES)))
+            return error(binaryMessage(shown));
+        const want = Math.min(input.limit ?? Infinity, DEFAULT_MAX_LINES + 1);
+        const win = readLineWindow(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）时的描述。 */

package/dist/tools/task.js

@@ -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 { AgentCatalog } from "../agents/catalog.js";
@@ -26,15 +28,20 @@ const THINKING = [
     "high",
     "xhigh",
 ];
+/**
+ * [ME-A] 两版描述共用的开头：fresh / fork 两种上下文。default+task 与 codemode-only 的预算余量都只有
+ * 几十 token，加 `context` 参数时整段改写、字符数基本不增（`agent` 参数的「Default general」也去掉，
+ * 清单里 general 已标 default）。
+ */
+export const TASK_CONTEXT_LEAD = "Delegate to a sub-agent (fresh context: give full instructions; context fork: inherits " +
+    "this conversation).";
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
-export const FOREGROUND_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Returns its final report. " +
-    "Tasks in one reply run in parallel; writers should use isolation worktree. background: " +
-    "returns a taskId now (see task_ctl); taskId: continue that task.";
+export const FOREGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Returns its final report. Parallel in one reply; writers use isolation ` +
+    "worktree. background: returns a taskId (see task_ctl); taskId: continue it.";
 /** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
-export const BACKGROUND_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Runs in the background by " +
-    "default: returns a taskId; a <task-notification> follows when done, so keep working. " +
-    "background:false if your next step needs the result. taskId: continue a task. Tasks in one " +
-    "reply run in parallel; writers use isolation worktree.";
+export const BACKGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Runs in the background by default: returns a taskId; a ` +
+    "<task-notification> follows; keep working. background:false waits for the result. " +
+    "taskId: continue it. Parallel in one reply; writers use isolation worktree.";
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export const TASK_AGENTS_HEADING = "\nAgents:\n";
 const catalogs = new WeakMap();
@@ -68,6 +75,8 @@ export function buildSubagentRequest(input, ctx) {
         return 'isolation must be "none" or "worktree"';
     if (input.budgetUsd !== undefined && !(input.budgetUsd > 0))
         return "budgetUsd must be > 0";
+    if (input.context !== undefined && input.context !== "fork" && input.context !== "fresh")
+        return 'context must be "fork" or "fresh"';
     const request = {
         prompt: input.prompt,
         parentToolCallId: ctx.toolCallId,
@@ -96,6 +105,8 @@ export function buildSubagentRequest(input, ctx) {
         request.model = input.model;
     if (input.thinkingLevel !== undefined)
         request.thinkingLevel = input.thinkingLevel;
+    if (input.context !== undefined)
+        request.context = input.context;
     return request;
 }
 export function createTaskTool(_options = {}) {
@@ -111,7 +122,7 @@ export function createTaskTool(_options = {}) {
             type: "object",
             properties: {
                 prompt: { type: "string" },
-                agent: { type: "string", description: "Default general" },
+                agent: { type: "string" },
                 description: { type: "string" },
                 background: { type: "boolean" },
                 taskId: { type: "string" },
@@ -121,6 +132,7 @@ export function createTaskTool(_options = {}) {
                 model: { type: "string" },
                 thinkingLevel: { type: "string", enum: [...THINKING] },
                 maxTurns: { type: "integer" },
+                context: { type: "string", enum: ["fork", "fresh"] },
             },
             required: ["prompt"],
             additionalProperties: false,
@@ -145,6 +157,7 @@ export function createTaskTool(_options = {}) {
                     ...(result.status !== undefined ? { status: result.status } : {}),
                     ...(result.sessionFile !== undefined ? { sessionFile: result.sessionFile } : {}),
                     ...(result.outputFile !== undefined ? { outputFile: result.outputFile } : {}),
+                    ...(result.context !== undefined ? { context: result.context } : {}),
                     usage: result.usage,
                     stopReason: result.stopReason,
                 };

package/dist/tools/truncate.d.ts

@@ -8,6 +8,13 @@
  */
 export declare const DEFAULT_MAX_LINES = 2000;
 export declare const DEFAULT_MAX_BYTES: number;
+/** [ME-D] 自截时给说明行留的余量（字符）。 */
+export declare const RESULT_NOTE_RESERVE = 512;
+/**
+ * [ME-D] 工具自截的字节上限（D11）：会话的结果上限（`ToolContext.maxResultChars`）减去说明行余量，
+ * 不超过 50 KB——一次截到位，不再被会话层二次截中段。字节数 ≤ N 时字符数必然 ≤ N。
+ */
+export declare function toolOutputBytes(maxResultChars: number | undefined): number;
 /** grep 匹配行的字符上限。 */
 export declare const GREP_MAX_LINE_CHARS = 500;
 export interface TruncateOptions {

package/dist/tools/truncate.js

@@ -11,6 +11,17 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 export const DEFAULT_MAX_LINES = 2000;
 export const DEFAULT_MAX_BYTES = 50 * 1024;
+/** [ME-D] 自截时给说明行留的余量（字符）。 */
+export const RESULT_NOTE_RESERVE = 512;
+/**
+ * [ME-D] 工具自截的字节上限（D11）：会话的结果上限（`ToolContext.maxResultChars`）减去说明行余量，
+ * 不超过 50 KB——一次截到位，不再被会话层二次截中段。字节数 ≤ N 时字符数必然 ≤ N。
+ */
+export function toolOutputBytes(maxResultChars) {
+    if (maxResultChars === undefined)
+        return DEFAULT_MAX_BYTES;
+    return Math.max(1024, Math.min(DEFAULT_MAX_BYTES, maxResultChars - RESULT_NOTE_RESERVE));
+}
 /** grep 匹配行的字符上限。 */
 export const GREP_MAX_LINE_CHARS = 500;
 export function byteLength(text) {

package/dist/tools/types.d.ts

@@ -102,6 +102,8 @@ export interface SubagentRequest {
     isolation?: "none" | "worktree";
     /** [W5-C0] 外部 Agent 的美元预算。 */
     budgetUsd?: number;
+    /** [ME-C0] `fork`：继承父会话已完成的回合（同模型、同前缀）；缺省 `fresh`。 */
+    context?: "fork" | "fresh";
 }
 /** [W5-C0] 子 Agent 任务的终态（`subagent_end.status`）。 */
 export type SubagentStatus = "completed" | "failed" | "aborted" | "max_turns" | "interrupted";
@@ -133,6 +135,8 @@ export interface SubagentResult {
     /** [W5-C0] 结果全文（> 50 KB 截断时、后台任务的输出文件）。 */
     outputFile?: string;
     sessionRef?: SubagentSessionRef;
+    /** [ME-A] 请求了 `context: "fork"` 时的实际模式（回落为 `fresh`）；未请求 fork 时缺省。 */
+    context?: "fork" | "fresh";
 }
 /** runner 上报的进度（由注册表转成 `subagent_update` 事件）。 */
 export type SubagentEvent = {
@@ -173,6 +177,11 @@ export type SubagentEvent = {
     type: "notice";
     level: "info" | "warn";
     text: string;
+}
+/** [ME-A] ama 子会话请求了 `context: "fork"` 时的实际模式（注册表写进 `TaskInfo.context`）。 */
+ | {
+    type: "context";
+    mode: "fork" | "fresh";
 };
 export interface SubagentRunRequest {
     prompt: string;
@@ -225,6 +234,8 @@ export interface TaskInfo {
     contextWindow?: number;
     outputFile?: string;
     sessionRef?: SubagentSessionRef;
+    /** [ME-C0] 子会话的实际上下文模式（fork 回落为 fresh 时记 `fresh`）；外部 Agent 缺省。 */
+    context?: "fork" | "fresh";
 }
 /** [W5-C0] 任务注册表的只读视图（W5-G 的 `SubagentRegistry` 提供）。 */
 export interface TaskRegistryView {
@@ -243,6 +254,8 @@ export interface ToolContext {
     readonly thinkingLevel?: ModelThinkingLevel;
     /** 截断全文的落盘目录（`<sessionDir>/outputs`）；内存会话为 undefined。 */
     readonly outputDir?: string;
+    /** [ME-C0] 会话层的工具结果上限（字符）；工具据此一次截到位。宿主 / SDK 自建上下文可不给。 */
+    readonly maxResultChars?: number;
     onUpdate(partial: string): void;
     /** 本会话已 read 的绝对路径（write / edit 先读后写检查）。 */
     readonly readFiles: ReadonlySet<string>;

package/dist/trace/build-index.js

@@ -33,7 +33,17 @@ export function traceData(entry) {
         ? data
         : undefined;
 }
+/** [ME-A] fork 式子会话从父复制来的条目（首条 `ama.task{context:"fork"}` 之后到 forkedFrom 为止）。 */
+function forkInherited(entries) {
+    const head = entries[0];
+    const data = head?.type === "custom" && head.customType === TASK_CUSTOM_TYPE ? head.data : {};
+    if (!isObject(data) || data["context"] !== "fork" || typeof data["forkedFrom"] !== "string")
+        return new Set();
+    const end = entries.findIndex((entry) => entry.id === data["forkedFrom"]);
+    return new Set(entries.slice(1, end + 1).map((entry) => entry.id));
+}
 export function buildIndex(entries) {
+    const inherited = forkInherited(entries);
     const index = {
         stepByAssistant: new Map(),
         toolTiming: new Map(),
@@ -52,9 +62,11 @@ export function buildIndex(entries) {
         }
         if (entry.type === "custom" && entry.customType === TASK_CUSTOM_TYPE) {
             const data = entry.data;
-            // 子会话自己的首条没有 status，不是父会话的快照
+            // 子会话自己的首条没有 status，不是父会话的快照；fork 继承来的父快照也不算
             if (!isObject(data) || typeof data["taskId"] !== "string" || data["status"] === undefined)
                 continue;
+            if (inherited.has(entry.id))
+                continue;
             const parent = typeof data["parentToolCallId"] === "string" ? data["parentToolCallId"] : "";
             const byTask = index.tasks.get(parent) ?? new Map();
             byTask.set(data["taskId"], { data: data, entryId: entry.id });

package/dist/tui/ansi.d.ts

@@ -7,6 +7,8 @@
  * - 所有截断 / 切片在保留 SGR 样式的同时，于末尾补 `\x1b[0m`，保证「每行末尾重置样式」。
  */
 export declare const SGR_RESET = "\u001B[0m";
+/** 字素切分器，首次用到才构造（-p / RPC / ACP / --version 不付 ICU 断字数据的初始化）。 */
+export declare function graphemeSegmenter(): Intl.Segmenter;
 /** 单个码点的列宽（0 / 1 / 2）。 */
 export declare function codePointWidth(cp: number): 0 | 1 | 2;
 /** 一个字素簇的列宽：首码点决定基础宽度；VS16（U+FE0F）把文本型 emoji 升为 2 列。 */

package/dist/tui/ansi.js

@@ -7,7 +7,11 @@
  * - 所有截断 / 切片在保留 SGR 样式的同时，于末尾补 `\x1b[0m`，保证「每行末尾重置样式」。
  */
 export const SGR_RESET = "\x1b[0m";
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+let segmenter;
+/** 字素切分器，首次用到才构造（-p / RPC / ACP / --version 不付 ICU 断字数据的初始化）。 */
+export function graphemeSegmenter() {
+    return (segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" }));
+}
 /** 东亚宽（W）与全角（F）区段，含常见 emoji 区块；按起点升序，二分查找。 */
 const WIDE_RANGES = [
     [0x1100, 0x115f],
@@ -193,7 +197,7 @@ function textWidth(text) {
     if (isPlainAscii(text))
         return text.length;
     let width = 0;
-    for (const { segment } of segmenter.segment(text))
+    for (const { segment } of graphemeSegmenter().segment(text))
         width += graphemeWidth(segment);
     return width;
 }
@@ -221,7 +225,7 @@ function* pieces(s) {
                 yield { text: ch, width: 1, escape: false };
         }
         else {
-            for (const { segment } of segmenter.segment(run)) {
+            for (const { segment } of graphemeSegmenter().segment(run)) {
                 yield { text: segment, width: graphemeWidth(segment), escape: false };
             }
         }

package/dist/tui/components/editor-buffer.js

@@ -7,10 +7,10 @@
  * - 撤销：每次编辑前存快照；连续输入同类字符合并为一步；上限 50 步。
  * - 不做选区（无鼠标、无 kill ring，§12.9）。
  */
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+import { graphemeSegmenter } from "../ansi.js";
 function graphemeStarts(line) {
     const starts = [];
-    for (const { index } of segmenter.segment(line))
+    for (const { index } of graphemeSegmenter().segment(line))
         starts.push(index);
     starts.push(line.length);
     return starts;