@armadra/agent 0.5.1 → 0.6.0

package/dist/sdk.js

@@ -13,12 +13,14 @@
  * - [W5-F] 计划（docs/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
  *   返回的会话带 `plan.current() / respond() / todos()`。没有 `onProposed` 时按 `plan.unattended`
  *   （缺省 stop：计划落盘后停下，不替人批准）。
+ * - [W6-C0] `language`（两个入口都有）：界面语言，跟随宿主界面（docs/i18n.md）；进程级，`AMA_LANG` 仍优先。
  */
 import { resolve } from "node:path";
 import { ProviderRegistry } from "./ai/providers/registry.js";
 import { planController, } from "./agent/session-plan.js";
 import { parseArgs } from "./cli/args.js";
 import { bootstrap } from "./cli/bootstrap.js";
+import { resolveMemory } from "./cli/compose-memory.js";
 import { withExtraProviders } from "./cli/compose-providers.js";
 import { composeSession, emptyComposeState } from "./cli/compose-session.js";
 import { buildRules, createRuntimeDeps, createTools } from "./cli/compose.js";
@@ -26,8 +28,10 @@ import { pickDefaultModel } from "./cli/default-model.js";
 import { findContextFiles } from "./config/context-files.js";
 import { DEFAULT_CONFIG, mergeConfig } from "./config/merge.js";
 import { resolveConfigDir, resolveDataDir } from "./config/paths.js";
-import { canonicalPreset } from "./config/types.js";
+import { canonicalPreset, } from "./config/types.js";
+import { sdkSessionTrace } from "./trace/query-session.js";
 import { AmaError } from "./errors.js";
+import { msg, resolveLocale, setLocale } from "./i18n/index.js";
 import { hooksFromConfig } from "./hooks/config.js";
 import { HookDispatcher } from "./hooks/dispatcher.js";
 import { AgentEventBus } from "./host/api-impl.js";
@@ -38,7 +42,7 @@ import { PresetToolRegistry } from "./tools/presets.js";
 export async function createRuntime(options = {}) {
     const parsed = parseArgs(options.argv ?? []);
     if (parsed.kind !== "run")
-        throw new AmaError("invalid_arguments", "createRuntime 不接受子命令");
+        throw new AmaError("invalid_arguments", msg().errors.sdk.noSubcommand);
     const args = parsed.args;
     if (options.model !== undefined)
         args.model = options.model;
@@ -56,7 +60,13 @@ export async function createRuntime(options = {}) {
         args.profile = options.profile;
     if (options.unattended === true)
         args.print = true;
+    if (options.language !== undefined)
+        args.lang = options.language;
+    if (options.memory !== undefined)
+        args.memory = options.memory;
     const env = options.env ?? process.env;
+    if (args.lang !== undefined)
+        setLocale(resolveLocale(env, undefined, args.lang));
     const io = {
         stdout: () => undefined,
         stderr: options.stderr ?? ((text) => void process.stderr.write(text)),
@@ -85,6 +95,8 @@ function keyOptions(auth) {
 export async function createAgentSession(options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const warn = options.onWarning ?? (() => undefined);
+    if (options.language !== undefined)
+        setLocale(resolveLocale(process.env, undefined, options.language));
     let config = mergeConfig(DEFAULT_CONFIG, options.config);
     const { onProposed, ...planConfig } = options.plan ?? {};
     if (options.plan !== undefined)
@@ -105,18 +117,28 @@ export async function createAgentSession(options = {}) {
     if (ref !== undefined) {
         const found = providers.findModel(ref);
         if (!found.ok)
-            throw new AmaError("model_not_found", `模型不存在：${ref}`, { detail: found.candidates });
+            throw new AmaError("model_not_found", msg().errors.sdk.modelNotFound(ref), {
+                detail: found.candidates,
+            });
         choice = found;
     }
     else {
         choice = await pickDefaultModel(providers);
         if (choice === undefined)
-            throw new AmaError("no_api_key", "没有可用模型：传 model，或配置任一供应商的 key");
+            throw new AmaError("no_api_key", msg().errors.sdk.noModel);
     }
     const state = emptyComposeState();
     let tools;
     if (options.tools === undefined || options.tools === "default") {
-        tools = createTools({ config, cwd, mode: "line" }, { extraTools: options.extraTools ?? [] }, state);
+        // [W6-M] SDK 同嵌入宿主：只有 `options.memory = { enabled, dir }` 开启（workspace 作用域）
+        const memory = resolveMemory({
+            config,
+            cwd,
+            dataDir: resolveDataDir(),
+            trusted: true,
+            embedded: { memory: options.memory },
+        });
+        tools = createTools({ config, cwd, mode: "line", memory }, { extraTools: options.extraTools ?? [] }, state);
     }
     else {
         tools = new PresetToolRegistry();
@@ -214,12 +236,12 @@ function withPlanApi(session, onProposed) {
     const controller = planController(session);
     controller?.setAttendance(onProposed === undefined ? "unattended" : "callback", onProposed);
     const missing = () => {
-        throw new AmaError("not_implemented", "该会话没有装配 plan 扩展");
+        throw new AmaError("not_implemented", msg().errors.sdk.noPlan);
     };
     const plan = {
         current: () => controller?.current() ?? null,
         respond: (response) => (controller ?? missing()).respond(response),
         todos: () => controller?.todos() ?? [],
     };
-    return Object.assign(session, { plan });
+    return Object.assign(session, { plan, trace: (o) => sdkSessionTrace(session, o) }); // [W6-T2]
 }

package/dist/session/export.js

@@ -10,6 +10,7 @@
 import { contentImages, contentText, numberUserMessages } from "./reuse.js";
 import { redactSecrets, redactValue } from "./redact.js";
 import { indexEntries, pathToRoot } from "./tree.js";
+import { msg } from "../i18n/index.js";
 export function selectEntries(input, branch) {
     return branch === "all"
         ? [...input.entries]
@@ -52,7 +53,9 @@ function sessionName(entries) {
     return name;
 }
 function truncate(text, max) {
-    return text.length > max ? `${text.slice(0, max)}\n…（截断，原长 ${text.length} 字符）` : text;
+    return text.length > max
+        ? `${text.slice(0, max)}\n${msg().session.export.truncated(text.length)}`
+        : text;
 }
 function fence(text, lang = "") {
     let ticks = "```";
@@ -65,66 +68,64 @@ function time(iso) {
 }
 function imagesNote(content) {
     return contentImages(content)
-        .map((image) => `[图片 ${image.mimeType}]`)
+        .map((image) => msg().session.export.image(image.mimeType))
         .join(" ");
 }
 export function renderMarkdown(input, branch) {
     const entries = selectEntries(input, branch);
     const numbers = new Map(numberUserMessages(input.entries).map((u) => [u.entryId, u.n]));
     const name = sessionName(input.entries);
+    const m = msg().session.export;
     const out = [
-        `# ${name ?? `会话 ${input.header.id.slice(0, 8)}`}`,
+        `# ${name ?? m.title(input.header.id.slice(0, 8))}`,
         "",
-        `- id：${input.header.id}`,
-        `- 目录：${input.header.cwd}`,
-        `- 创建：${time(input.header.timestamp)}`,
-        `- 范围：${branch === "all" ? "全部条目" : "当前分支"}（${entries.length} 条条目）`,
-        ...(input.header.parentSession !== undefined
-            ? [`- 来源会话：${input.header.parentSession}`]
-            : []),
+        m.id(input.header.id),
+        m.cwd(input.header.cwd),
+        m.created(time(input.header.timestamp)),
+        m.scope(branch === "all", entries.length),
+        ...(input.header.parentSession !== undefined ? [m.parent(input.header.parentSession)] : []),
         "",
     ];
     for (const entry of entries) {
         switch (entry.type) {
             case "message": {
-                const m = entry.message;
-                if (m.role === "user") {
+                const message = entry.message;
+                if (message.role === "user") {
                     const n = numbers.get(entry.id);
-                    const origin = m.origin;
-                    out.push(`## 用户${n !== undefined ? ` #${n}` : ""}${origin !== undefined ? `（${origin}）` : ""} · ${time(entry.timestamp)}`, "");
-                    const text = contentText(m.content);
+                    const origin = message.origin;
+                    out.push(m.user(n, origin, time(entry.timestamp)), "");
+                    const text = contentText(message.content);
                     if (text !== "")
                         out.push(text, "");
-                    const images = imagesNote(m.content);
+                    const images = imagesNote(message.content);
                     if (images !== "")
                         out.push(images, "");
                 }
-                else if (m.role === "assistant") {
-                    out.push(`## 助手 · ${m.provider}/${m.model} · ${time(entry.timestamp)}`, "");
-                    for (const block of m.content) {
+                else if (message.role === "assistant") {
+                    out.push(m.assistant(`${message.provider}/${message.model}`, time(entry.timestamp)), "");
+                    for (const block of message.content) {
                         if (block.type === "text" && block.text.trim() !== "")
                             out.push(block.text, "");
                         if (block.type === "toolCall") {
-                            out.push(`**工具调用** \`${block.name}\``, "", fence(truncate(JSON.stringify(block.arguments, null, 2), 500), "json"), "");
+                            out.push(m.toolCall(block.name), "", fence(truncate(JSON.stringify(block.arguments, null, 2), 500), "json"), "");
                         }
                     }
-                    if (m.stopReason === "error" || m.stopReason === "aborted") {
-                        out.push(`> 停止：${m.stopReason}${m.errorMessage !== undefined ? ` · ${m.errorMessage}` : ""}`, "");
-                    }
+                    if (message.stopReason === "error" || message.stopReason === "aborted")
+                        out.push(m.stopped(message.stopReason, message.errorMessage), "");
                 }
-                else if (m.role === "toolResult") {
-                    out.push(`**结果** \`${m.toolName}\`${m.isError ? "（出错）" : ""}`, "", fence(truncate(contentText(m.content), 2000)), "");
-                    const images = imagesNote(m.content);
+                else if (message.role === "toolResult") {
+                    out.push(m.toolResult(message.toolName, message.isError), "", fence(truncate(contentText(message.content), 2000)), "");
+                    const images = imagesNote(message.content);
                     if (images !== "")
                         out.push(images, "");
                 }
                 break;
             }
             case "compaction":
-                out.push(`## 压缩摘要 · ${time(entry.timestamp)}`, "", entry.summary, "");
+                out.push(m.compaction(time(entry.timestamp)), "", entry.summary, "");
                 break;
             case "branch_summary":
-                out.push(`## 分支摘要 · ${time(entry.timestamp)}`, "", entry.summary, "");
+                out.push(m.branchSummary(time(entry.timestamp)), "", entry.summary, "");
                 break;
             case "custom_message":
                 if (entry.display) {
@@ -133,14 +134,14 @@ export function renderMarkdown(input, branch) {
                 }
                 break;
             case "model_change":
-                out.push(`_切换模型：${entry.provider}/${entry.modelId}${entry.channel !== undefined ? `@${entry.channel}` : ""}_`, "");
+                out.push(m.modelChange(`${entry.provider}/${entry.modelId}${entry.channel !== undefined ? `@${entry.channel}` : ""}`), "");
                 break;
             default:
                 break;
         }
     }
     const usage = usageTotals(entries);
-    out.push("## 用量", "", "| 请求 | 输入 | 输出 | 缓存读 | 缓存写 | 费用 |", "| ---: | ---: | ---: | ---: | ---: | ---: |", `| ${usage.requests} | ${usage.input} | ${usage.output} | ${usage.cacheRead} | ${usage.cacheWrite} | ${usage.cost !== undefined ? `$${usage.cost.toFixed(4)}` : "—"} |`, "");
+    out.push(m.usage, "", m.usageHeader, "| ---: | ---: | ---: | ---: | ---: | ---: |", `| ${usage.requests} | ${usage.input} | ${usage.output} | ${usage.cacheRead} | ${usage.cacheWrite} | ${usage.cost !== undefined ? `$${usage.cost.toFixed(4)}` : "—"} |`, "");
     return redactSecrets(out.join("\n"));
 }
 export function renderJson(input, branch) {

package/dist/session/manager.d.ts

@@ -39,7 +39,7 @@ export declare class SessionManager implements SessionManagerApi {
     static open(file: string, options?: {
         now?: () => Date;
     }): SessionManager;
-    /** `--continue`：本目录最近一条；没有则新建（延迟落盘）。 */
+    /** `--continue`：本目录最近一条（跳过子 Agent 会话，只读文件头两行）；没有则新建（延迟落盘）。 */
     static continueRecent(dir: string, cwd: string): SessionManager;
     /** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
     static list(dir: string): SessionListItem[];

package/dist/session/manager.js

@@ -17,7 +17,7 @@ import { dirname, join } from "node:path";
 import { AmaError } from "../errors.js";
 import { AMA_VERSION } from "../version.js";
 import { migrateSessionLines } from "./migrate.js";
-import { acquireLock, appendLines, listSessionFiles, readSessionLines, sessionDirForCwd, sessionFileName, writeNewSessionFile, } from "./store.js";
+import { acquireLock, appendLines, isSubagentSession, isSubagentSessionFile, listSessionFiles, readSessionLines, sessionDirForCwd, sessionFileName, writeNewSessionFile, } from "./store.js";
 import { buildTree, indexEntries, pathToRoot } from "./tree.js";
 import { SESSION_FORMAT_VERSION } from "./types.js";
 function newEntryId(taken) {
@@ -86,9 +86,9 @@ export class SessionManager {
             throw error;
         }
     }
-    /** `--continue`：本目录最近一条；没有则新建（延迟落盘）。 */
+    /** `--continue`：本目录最近一条（跳过子 Agent 会话，只读文件头两行）；没有则新建（延迟落盘）。 */
     static continueRecent(dir, cwd) {
-        const [latest] = listSessionFiles(dir);
+        const latest = listSessionFiles(dir).find((file) => !isSubagentSessionFile(file));
         return latest === undefined ? this.create(dir, cwd) : this.open(latest);
     }
     /** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
@@ -124,6 +124,8 @@ export class SessionManager {
                 };
                 if (name !== undefined)
                     item.name = name;
+                if (isSubagentSession(header, entries[0]))
+                    item.subagent = true;
                 if (firstPrompt !== undefined)
                     item.firstPrompt = firstPrompt.slice(0, 200);
                 items.push(item);

package/dist/session/reuse.js

@@ -8,6 +8,7 @@
  */
 import { AmaError } from "../errors.js";
 import { findSessionFileReadOnly, readSessionReadOnly } from "./scan.js";
+import { msg } from "../i18n/index.js";
 /** 内容 → 纯文本（文本块用空行连接；不含图片）。 */
 export function contentText(content) {
     if (typeof content === "string")
@@ -54,14 +55,14 @@ export function parseFromSpec(spec) {
     const at = spec.lastIndexOf("#");
     if (at < 0) {
         if (spec.trim() === "")
-            throw new AmaError("invalid_arguments", "--from 需要会话 id", { exitCode: 2 });
+            throw new AmaError("invalid_arguments", msg().session.lookup.fromNeedsId, { exitCode: 2 });
         return { id: spec };
     }
     const id = spec.slice(0, at);
     const raw = spec.slice(at + 1);
     const n = Number(raw);
     if (id === "" || !/^\d+$/.test(raw) || n < 1) {
-        throw new AmaError("invalid_arguments", `--from 应为 <会话 id> 或 <会话 id>#<编号>（收到 ${spec}）`, {
+        throw new AmaError("invalid_arguments", msg().session.lookup.fromInvalid(spec), {
             exitCode: 2,
         });
     }
@@ -74,13 +75,13 @@ export function resolveFromMessage(root, spec, cwd) {
     const session = readSessionReadOnly(file);
     const messages = numberUserMessages(session.entries);
     if (messages.length === 0) {
-        throw new AmaError("invalid_arguments", `会话 ${session.header.id} 没有用户消息`, {
+        throw new AmaError("invalid_arguments", msg().session.lookup.noUserMessages(session.header.id), {
             exitCode: 2,
         });
     }
     const picked = n === undefined ? messages.at(-1) : messages[n - 1];
     if (picked === undefined) {
-        throw new AmaError("invalid_arguments", `会话 ${session.header.id} 只有 ${messages.length} 条用户消息（收到 #${n}）`, { exitCode: 2 });
+        throw new AmaError("invalid_arguments", msg().session.lookup.tooFewMessages(session.header.id, messages.length, n), { exitCode: 2 });
     }
     return { ...picked, sessionId: session.header.id, file };
 }

package/dist/session/scan.js

@@ -13,6 +13,7 @@ import { basename, join } from "node:path";
 import { AmaError } from "../errors.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";
 /** 根目录下全部 cwd 子目录（不含 trash）。 */
 export function sessionSubdirs(root) {
     if (!existsSync(root))
@@ -56,13 +57,13 @@ export function findSessionFileReadOnly(root, id, cwd) {
     }
     if (prefix.length > 1) {
         const ids = prefix.map((f) => sessionIdFromFileName(f) ?? f).slice(0, 10);
-        throw new AmaError("invalid_arguments", `会话 id 前缀 ${id} 不唯一，候选：${ids.join(", ")}`, {
+        throw new AmaError("invalid_arguments", msg().session.lookup.ambiguousPrefix(id, ids.join(", ")), {
             exitCode: 5,
         });
     }
     const [file] = prefix;
     if (file === undefined)
-        throw new AmaError("session_not_found", `会话不存在：${id}`, { exitCode: 5 });
+        throw new AmaError("session_not_found", msg().session.lookup.notFound(id), { exitCode: 5 });
     return file;
 }
 /**

package/dist/session/stats-aggregate.d.ts

@@ -19,8 +19,10 @@ export interface StatsTotals {
     cacheWrite: number;
     /** 有价请求的费用；没有任何有价请求时缺省。 */
     cost?: number;
-    /** 无价请求数。 */
+    /** 无价请求数（不含订阅计费的）。 */
     unpriced: number;
+    /** [W6-I5] 订阅计费的请求数（ChatGPT 登录；不折算美元）；没有时缺省。 */
+    subscription?: number;
     /** 0–1；报告缓存的端点没有输入时缺省。 */
     hitRate?: number;
     errors: number;

package/dist/session/stats-aggregate.js

@@ -25,6 +25,7 @@ const newAcc = () => ({
     cacheWrite: 0,
     cost: 0,
     costed: 0,
+    subscription: 0,
     hitRead: 0,
     hitPrompt: 0,
     errors: 0,
@@ -45,6 +46,7 @@ function add(acc, b, reported, session) {
     acc.cacheWrite += b.cacheWrite;
     acc.cost += b.cost;
     acc.costed += b.costed;
+    acc.subscription += b.subscription;
     if (reported) {
         acc.hitRead += b.cacheRead;
         acc.hitPrompt += b.input + b.cacheRead + b.cacheWrite;
@@ -63,12 +65,14 @@ function totals(acc) {
         output: acc.output,
         cacheRead: acc.cacheRead,
         cacheWrite: acc.cacheWrite,
-        unpriced: acc.requests - acc.costed,
+        unpriced: acc.requests - acc.costed - acc.subscription,
         errors: acc.errors,
         retries: acc.retries,
     };
     if (acc.costed > 0)
         out.cost = acc.cost;
+    if (acc.subscription > 0)
+        out.subscription = acc.subscription;
     if (acc.hitPrompt > 0)
         out.hitRate = acc.hitRead / acc.hitPrompt;
     if (acc.timedTurns > 0)

package/dist/session/stats-index.js

@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "no
 import { dirname } from "node:path";
 import { summarizeSessionFile } from "./stats-scan.js";
 export const STATS_INDEX_FILE = "stats-index.json";
-const INDEX_VERSION = 1;
+// 2：桶加 subscription（[W6-I5]），旧索引里订阅请求被算成 $0 有价，整体重扫
+const INDEX_VERSION = 2;
 export function timeZoneKey(now = new Date()) {
     let zone = "";
     try {

package/dist/session/stats-scan.d.ts

@@ -5,7 +5,8 @@
  * - 请求来源：assistant 消息 = `turn`；`usage` 条目用自己的 `kind`（cache_warm、permission_classify…）；
  *   `compaction` / `branch_summary` 带的 usage 记为同名 kind（模型取最近一条 assistant 的）。
  * - token：input（不含缓存）/ output / cacheRead / cacheWrite；费用只累加有 `usage.cost` 的请求，
- *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。
+ *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。订阅计费
+ *   （`usage.billing: "subscription"`，ChatGPT 登录）单列 `subscription`，不进费用也不算无价。
  * - 缓存三态：桶记下是否出现过 cacheRead > 0 或 cacheWrite > 0（`cacheSeen`）；汇总时同一端点
  *   （provider/model@channel）任一桶出现过即算报告缓存，其余端点不进命中率分母（同会话层三态）。
  * - 回合：非 `steer` 的用户消息开始一个回合，到下一个回合开始为止；回合计入首条 assistant 的桶，
@@ -31,6 +32,8 @@ export interface StatsBucket {
     cost: number;
     /** 有价请求数。 */
     costed: number;
+    /** [W6-I5] 订阅计费的请求数（不折算美元）。 */
+    subscription: number;
     /** 出现过 cacheRead > 0 或 cacheWrite > 0。 */
     cacheSeen: boolean;
     errors: number;

package/dist/session/stats-scan.js

@@ -5,7 +5,8 @@
  * - 请求来源：assistant 消息 = `turn`；`usage` 条目用自己的 `kind`（cache_warm、permission_classify…）；
  *   `compaction` / `branch_summary` 带的 usage 记为同名 kind（模型取最近一条 assistant 的）。
  * - token：input（不含缓存）/ output / cacheRead / cacheWrite；费用只累加有 `usage.cost` 的请求，
- *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。
+ *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。订阅计费
+ *   （`usage.billing: "subscription"`，ChatGPT 登录）单列 `subscription`，不进费用也不算无价。
  * - 缓存三态：桶记下是否出现过 cacheRead > 0 或 cacheWrite > 0（`cacheSeen`）；汇总时同一端点
  *   （provider/model@channel）任一桶出现过即算报告缓存，其余端点不进命中率分母（同会话层三态）。
  * - 回合：非 `steer` 的用户消息开始一个回合，到下一个回合开始为止；回合计入首条 assistant 的桶，
@@ -64,6 +65,7 @@ export function summarizeSessionFile(file) {
                 cacheWrite: 0,
                 cost: 0,
                 costed: 0,
+                subscription: 0,
                 cacheSeen: false,
                 errors: 0,
                 retries: 0,
@@ -88,7 +90,9 @@ export function summarizeSessionFile(file) {
         bucket.cacheWrite += num(u.cacheWrite);
         if (num(u.cacheRead) > 0 || num(u.cacheWrite) > 0)
             bucket.cacheSeen = true;
-        if (isRec(u.cost) && typeof u.cost["total"] === "number") {
+        if (u.billing === "subscription")
+            bucket.subscription++;
+        else if (isRec(u.cost) && typeof u.cost["total"] === "number") {
             bucket.cost += num(u.cost["total"]);
             bucket.costed++;
         }

package/dist/session/store.d.ts

@@ -41,6 +41,17 @@ export interface SessionLock {
 export declare function acquireLock(file: string): SessionLock;
 /** 目录下的会话文件（按文件名倒序 = 最新在前）。 */
 export declare function listSessionFiles(dir: string): string[];
+/** 子 Agent（task）会话第一条条目的 customType（与 agents/task-record.ts 同值）。 */
+export declare const TASK_SESSION_CUSTOM_TYPE = "ama.task";
+/**
+ * 子 Agent 会话：头有 `parentSession`，且第一条条目是 `custom{ama.task}`（fork / clone 也带
+ * `parentSession`，但第一条不是任务记录，不算）。
+ */
+export declare function isSubagentSession(header: {
+    parentSession?: string;
+} | undefined, first: unknown): boolean;
+/** 只读文件开头的前两行（头 + 第一条条目）判断是否子 Agent 会话；读不了 / 解析不了 → false。 */
+export declare function isSubagentSessionFile(file: string): boolean;
 /** 移到 `<sessionsRoot>/.trash/<删除时间毫秒>__<编码目录>__<文件名>`，返回新路径。 */
 export declare function trashSession(file: string, sessionsRoot: string, now?: number): string;
 /** 删除 trash 中超过保留期的文件，返回删除的路径。 */

package/dist/session/store.js

@@ -7,7 +7,7 @@
  * - 锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在 → 视为陈旧锁并接管。
  * - prune：移到 `<sessionsRoot>/.trash/`，文件名前缀删除时间；`purgeTrash` 清理超过 7 天的。
  */
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, truncateSync, writeFileSync, writeSync, } from "node:fs";
+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";
 export const SESSION_FILE_SUFFIX = ".jsonl";
@@ -182,6 +182,53 @@ export function listSessionFiles(dir) {
         .reverse()
         .map((name) => join(dir, name));
 }
+/** 子 Agent（task）会话第一条条目的 customType（与 agents/task-record.ts 同值）。 */
+export const TASK_SESSION_CUSTOM_TYPE = "ama.task";
+/**
+ * 子 Agent 会话：头有 `parentSession`，且第一条条目是 `custom{ama.task}`（fork / clone 也带
+ * `parentSession`，但第一条不是任务记录，不算）。
+ */
+export function isSubagentSession(header, first) {
+    if (header?.parentSession === undefined)
+        return false;
+    const entry = first;
+    return entry?.type === "custom" && entry.customType === TASK_SESSION_CUSTOM_TYPE;
+}
+const HEAD_CHUNK = 16 * 1024;
+const HEAD_LIMIT = 1024 * 1024;
+/** 只读文件开头的前两行（头 + 第一条条目）判断是否子 Agent 会话；读不了 / 解析不了 → false。 */
+export function isSubagentSessionFile(file) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+        const chunks = [];
+        let size = 0;
+        let newlines = 0;
+        while (newlines < 2 && size < HEAD_LIMIT) {
+            const buffer = Buffer.alloc(HEAD_CHUNK);
+            const read = readSync(fd, buffer, 0, HEAD_CHUNK, size);
+            if (read === 0)
+                break;
+            const chunk = buffer.subarray(0, read);
+            for (const byte of chunk)
+                if (byte === 0x0a)
+                    newlines++;
+            chunks.push(chunk);
+            size += read;
+        }
+        const [header, first] = Buffer.concat(chunks).toString("utf8").split("\n", 2);
+        if (header === undefined || first === undefined || first.trim() === "")
+            return false;
+        return isSubagentSession(JSON.parse(header), JSON.parse(first));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
 /** 移到 `<sessionsRoot>/.trash/<删除时间毫秒>__<编码目录>__<文件名>`，返回新路径。 */
 export function trashSession(file, sessionsRoot, now = Date.now()) {
     const trash = join(sessionsRoot, TRASH_DIR_NAME);

package/dist/session/types.d.ts

@@ -172,6 +172,8 @@ export interface SessionListItem {
     modifiedAt: string;
     firstPrompt?: string;
     messageCount: number;
+    /** 子 Agent（task）会话：继续 / 恢复选择器缺省跳过。 */
+    subagent?: true;
 }
 export interface SessionManagerApi {
     readonly id: string;

package/dist/skills/builtin.js

@@ -93,7 +93,8 @@ export async function withBuiltinSkills(skills, dataDir, builtins = BUILTIN_SKIL
             await ensureFile(location, builtinSkillText(builtin));
         }
         catch (error) {
-            warnings.push(`内置 Skill ${builtin.name} 写入失败：${error.message}`);
+            // 与 skills/ 其它加载告警一样固定英文（模型侧模块不 import i18n，见 docs/i18n.md）
+            warnings.push(`built-in skill ${builtin.name} could not be written: ${error.message}`);
             continue;
         }
         out.push({

package/dist/tools/image-file.d.ts

@@ -61,6 +61,31 @@ export type ImageFit = {
  */
 export declare function fitImage(buf: Buffer, mimeType: string, options?: ImageFitOptions, path?: string): Promise<ImageFit>;
 /**
- * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ * [W6-C0] 读图失败的结构化说明：`AmaError.detail`。本模块属模型侧（不 import i18n），`message` 固定英文；
+ * 界面层（`modes/image-input.ts`）按 `reason` 渲染本地化文案。
+ */
+export type ImageFileErrorDetail = {
+    reason: "missing" | "not_file" | "unsupported";
+    path: string;
+} | {
+    reason: "too_large";
+    path: string;
+    limitMb: string;
+    sizeMb: string;
+    hint?: ImageFitHint;
+} | {
+    reason: "too_wide";
+    path: string;
+    maxEdge: number;
+    size?: ImageSize;
+    hint?: ImageFitHint;
+};
+/** 超限时为什么没缩放：配置关闭 / 没有缩放工具 / 缩放后仍超限。 */
+export type ImageFitHint = "resize_off" | "no_tool" | "still_too_large";
+/** `AmaError.detail` 是否是读图失败的说明。 */
+export declare function isImageFileErrorDetail(detail: unknown): detail is ImageFileErrorDetail;
+/**
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`，英文 message，
+ * `detail` 为 `ImageFileErrorDetail`，界面层据此本地化）。
  */
 export declare function loadImageFile(path: string, options?: ImageFitOptions): Promise<LoadedImage>;