@armadra/agent 0.5.0 → 0.6.0

package/dist/tools/image-file.js

@@ -138,22 +138,53 @@ export async function fitImage(buf, mimeType, options = {}, path) {
         resized: { tool: resized.tool, ...(fit.size !== undefined ? { from: fit.size } : {}) },
     };
 }
+const HINT_TEXT = {
+    resize_off: " (images.resize is off)",
+    no_tool: " (no resize tool found: install ImageMagick, or sips on macOS)",
+    still_too_large: " (resizing did not bring it under the limit)",
+};
+function imageError(message, detail) {
+    return new AmaError("invalid_arguments", message, { detail });
+}
+/** `AmaError.detail` 是否是读图失败的说明。 */
+export function isImageFileErrorDetail(detail) {
+    return (typeof detail === "object" &&
+        detail !== null &&
+        typeof detail.path === "string" &&
+        ["missing", "not_file", "unsupported", "too_large", "too_wide"].includes(String(detail.reason)));
+}
 function fitError(path, fit, limit, bytes, resizeOff) {
     const hint = resizeOff
-        ? "（images.resize 为 off）"
+        ? "resize_off"
         : fit.note.includes("no resize tool")
-            ? "（没找到缩放工具：装 ImageMagick，macOS 自带 sips）"
+            ? "no_tool"
             : fit.note.includes("resizing did not")
-                ? "（缩放后仍超限）"
-                : "";
+                ? "still_too_large"
+                : undefined;
+    const hintText = hint === undefined ? "" : HINT_TEXT[hint];
     if (fit.reason === "too_wide") {
-        const dims = fit.size !== undefined ? `（${fit.size.width}×${fit.size.height}）` : "";
-        return new AmaError("invalid_arguments", `图片任一边超过 ${MAX_IMAGE_EDGE} px：${path}${dims}${hint}`);
+        const dims = fit.size !== undefined ? ` (${fit.size.width}x${fit.size.height})` : "";
+        return imageError(`Image edge exceeds ${MAX_IMAGE_EDGE} px: ${path}${dims}${hintText}`, {
+            reason: "too_wide",
+            path,
+            maxEdge: MAX_IMAGE_EDGE,
+            ...(fit.size !== undefined ? { size: fit.size } : {}),
+            ...(hint !== undefined ? { hint } : {}),
+        });
     }
-    return new AmaError("invalid_arguments", `图片超过 ${formatMb(limit)} 上限（按 base64 后计算）：${path}（${formatMb(base64Size(bytes))}）${hint}`);
+    const limitMb = formatMb(limit);
+    const sizeMb = formatMb(base64Size(bytes));
+    return imageError(`Image exceeds the ${limitMb} limit (base64): ${path} (${sizeMb})${hintText}`, {
+        reason: "too_large",
+        path,
+        limitMb,
+        sizeMb,
+        ...(hint !== undefined ? { hint } : {}),
+    });
 }
 /**
- * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`，英文 message，
+ * `detail` 为 `ImageFileErrorDetail`，界面层据此本地化）。
  */
 export async function loadImageFile(path, options = {}) {
     let info;
@@ -161,17 +192,28 @@ export async function loadImageFile(path, options = {}) {
         info = await stat(path);
     }
     catch {
-        throw new AmaError("invalid_arguments", `图片不存在：${path}`);
+        throw imageError(`Image not found: ${path}`, { reason: "missing", path });
     }
     if (!info.isFile())
-        throw new AmaError("invalid_arguments", `不是文件：${path}`);
+        throw imageError(`Not a file: ${path}`, { reason: "not_file", path });
     const limit = options.maxBase64Bytes ?? DEFAULT_IMAGE_BASE64_LIMIT;
-    if (info.size > MAX_IMAGE_FILE_BYTES)
-        throw new AmaError("invalid_arguments", `图片超过 ${formatMb(limit)} 上限（按 base64 后计算）：${path}（${formatMb(base64Size(info.size))}）`);
+    if (info.size > MAX_IMAGE_FILE_BYTES) {
+        const limitMb = formatMb(limit);
+        const sizeMb = formatMb(base64Size(info.size));
+        throw imageError(`Image exceeds the ${limitMb} limit (base64): ${path} (${sizeMb})`, {
+            reason: "too_large",
+            path,
+            limitMb,
+            sizeMb,
+        });
+    }
     const buf = await readFile(path);
     const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(path);
     if (mimeType === undefined)
-        throw new AmaError("invalid_arguments", `不是支持的图片（PNG / JPEG / GIF / WebP）：${path}`);
+        throw imageError(`Unsupported image (PNG / JPEG / GIF / WebP): ${path}`, {
+            reason: "unsupported",
+            path,
+        });
     const fit = await fitImage(buf, mimeType, options, path);
     if (!fit.ok)
         throw fitError(path, fit, limit, buf.length, options.resize === "off");

package/dist/tools/presets.d.ts

@@ -61,13 +61,26 @@ export declare function codemodeCallableFilter(config: Pick<AmaConfig, "tools">)
  * 返回去重后的名字（保持首次出现顺序）。
  */
 export declare function applyToolAdjustments(base: readonly string[], adjustments: readonly string[] | undefined): string[];
+/**
+ * [W6-I3] 预设解析的警告（给人看）：本模块在模型侧目录里、不 import i18n，返回结构，
+ * 由调用方经 `msg().session.codemode.presetWarning()` 渲染。
+ */
+export type PresetWarning = {
+    kind: "codemode_only_fallback";
+} | {
+    kind: "codemode_unavailable";
+    mode: CodemodeMode;
+} | {
+    kind: "unknown_tool";
+    name: string;
+};
 export interface PresetResolution {
     /** 生效的预设（codemode 工具缺失时回退为 default）。 */
     preset: ToolsPreset;
     codemode: CodemodeMode;
     /** 活动的内置工具名（按名排序）。 */
     builtin: string[];
-    warnings: string[];
+    warnings: PresetWarning[];
 }
 export declare function resolvePreset(input: {
     config: Pick<AmaConfig, "tools" | "codemode">;

package/dist/tools/presets.js

@@ -104,8 +104,8 @@ export function resolvePreset(input) {
     }
     if (codemode !== "off" && !input.available(CODEMODE_TOOL)) {
         warnings.push(preset === "codemode-only"
-            ? "工具预设 codemode-only 需要 codemode 工具（不可用），已回退到 default"
-            : `codemode.mode ${codemode} 需要 codemode 工具（不可用），已忽略`);
+            ? { kind: "codemode_only_fallback" }
+            : { kind: "codemode_unavailable", mode: codemode });
         if (preset === "codemode-only")
             preset = "default";
         codemode = "off";
@@ -124,7 +124,7 @@ export function resolvePreset(input) {
         if (input.available(name))
             names.push(name);
         else
-            warnings.push(`tools.default：未知工具 ${name}，已忽略`);
+            warnings.push({ kind: "unknown_tool", name });
     }
     return { preset, codemode, builtin: names.sort(), warnings };
 }

package/dist/tools/registry.js

@@ -49,7 +49,7 @@ export function validateToolDefinition(tool) {
     if (typeof tool.name !== "string" || !TOOL_NAME_RE.test(tool.name)) {
         throw new AmaError("invalid_arguments", `Invalid tool name "${String(tool.name)}"`);
     }
-    if (!["read", "write", "execute"].includes(tool.permission)) {
+    if (!["read", "write", "execute", "memory"].includes(tool.permission)) {
         throw new AmaError("invalid_arguments", `Tool ${tool.name}: invalid permission`);
     }
     if (typeof tool.execute !== "function") {

package/dist/tools/truncate.d.ts

@@ -45,7 +45,7 @@ export interface MiddleTruncation {
 }
 /**
  * 头 + 尾截断（[W5-H2] §8.3 H5）：超过 `maxChars` 时保留前 70% 与后 30%，中间换成
- * `marker(省略字符数)` 的文本（缺省 `[… N 字符已省略]`）。
+ * `marker(省略字符数)` 的文本（缺省 `[… N chars omitted]`；[W6-C0] 进模型的标记固定英文）。
  */
 export declare function truncateMiddle(text: string, maxChars: number, marker?: (omitted: number) => string): MiddleTruncation;
 /** 单行按字符截断，附省略提示。 */

package/dist/tools/truncate.js

@@ -155,9 +155,9 @@ function charBoundary(text, index) {
 }
 /**
  * 头 + 尾截断（[W5-H2] §8.3 H5）：超过 `maxChars` 时保留前 70% 与后 30%，中间换成
- * `marker(省略字符数)` 的文本（缺省 `[… N 字符已省略]`）。
+ * `marker(省略字符数)` 的文本（缺省 `[… N chars omitted]`；[W6-C0] 进模型的标记固定英文）。
  */
-export function truncateMiddle(text, maxChars, marker = (omitted) => `[… ${omitted} 字符已省略]`) {
+export function truncateMiddle(text, maxChars, marker = (omitted) => `[… ${omitted} chars omitted]`) {
     if (text.length <= maxChars)
         return { content: text, omitted: 0 };
     const limit = Math.max(0, Math.floor(maxChars));

package/dist/tools/types.d.ts

@@ -21,9 +21,13 @@
 import type { ContentBlock, JsonSchema, ModelRef, ModelThinkingLevel, Usage } from "../ai/types.js";
 import type { CheckpointHooks } from "../checkpoints/types.js";
 import type { PermissionMode } from "../permissions/types.js";
+import type { TraceExternalTurnData } from "../trace/types.js";
 export type { JsonSchema } from "../ai/types.js";
 /** 权限管线的粗分类（§7）。 */
-export type ToolPermission = "read" | "write" | "execute";
+/**
+ * [W6-C0] `memory`：记忆工具专用（`permissions/memory-class.ts`）——`view` 按 read、写命令按 execute 判定。
+ */
+export type ToolPermission = "read" | "write" | "execute" | "memory";
 export type ToolExecutionMode = "sequential" | "parallel";
 export interface ToolAnnotations {
     readOnly?: boolean;
@@ -130,9 +134,21 @@ export type SubagentEvent = {
     type: "tool";
     toolName: string;
     status: "started" | "completed" | "failed";
+    /** [W6-C0] runner 内的调用 id（外部 Agent 的 tool_call id；配对 started / 结束）。 */
+    id?: string;
+    /** [W6-C0] 事件时刻（epoch ms）。 */
+    at?: number;
 } | {
     type: "turn";
     turn: number;
+}
+/**
+ * [W6-C0] 外部 Agent 一个回合结束时的骨架（docs/wave6-plan.md §2.2）：任务注册表写成父会话的
+ * `ama.trace{kind:"external_turn"}`。只有种类、状态、时间与计数——不含工具标题、命令行、路径。
+ */
+ | {
+    type: "turn_trace";
+    trace: Omit<TraceExternalTurnData, "kind" | "taskId" | "agent">;
 } | {
     type: "usage";
     usage?: Usage;

package/dist/trace/build-index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 轨迹构建器的索引与扫描状态（`build.ts` 用）。[W6-T1]
+ *
+ * 预建索引：`ama.trace` 按 assistant / toolCall / compaction / usage 条目 id，`ama.task` 按父 toolCallId（同一
+ * taskId 取分支上最后一条），`external_turn` 按 taskId，`context_edit{retry|overflow}` 的目标。
+ */
+import type { Usage } from "../ai/types.js";
+import type { SessionEntry } from "../session/types.js";
+import { type TraceAuxData, type TraceAuxNode, type TraceCompactionData, type TraceEntryData, type TraceExternalTurnData, type TraceStepData, type TraceSubcallTiming, type TraceToolNode, type TraceToolTiming, type TraceTurnNode } from "./types.js";
+/** 父会话 `ama.task` 的 customType（与 agents/task-record.ts 相同；这里不 import 运行时模块）。 */
+export declare const TASK_CUSTOM_TYPE = "ama.task";
+/** 父会话里一个任务的最后一条快照（`TaskInfo + parentToolCallId`）。 */
+export interface TaskData {
+    taskId: string;
+    agent?: string;
+    runner?: string;
+    background?: boolean;
+    status?: string;
+    startedAt?: number;
+    endedAt?: number;
+    turns?: number;
+    usage?: Usage;
+    costUsd?: number;
+    parentToolCallId?: string;
+    sessionRef?: {
+        runner?: string;
+        sessionId?: string;
+        sessionFile?: string;
+    };
+}
+export interface Index {
+    stepByAssistant: Map<string, {
+        data: TraceStepData;
+        entryId: string;
+    }>;
+    toolTiming: Map<string, TraceToolTiming>;
+    subcalls: Map<string, {
+        data: TraceSubcallTiming;
+        entryId: string;
+    }[]>;
+    compactionByEntry: Map<string, {
+        data: TraceCompactionData;
+        entryId: string;
+    }>;
+    auxByUsage: Map<string, {
+        data: TraceAuxData;
+        entryId: string;
+    }>;
+    external: Map<string, {
+        data: TraceExternalTurnData;
+        entryId: string;
+    }[]>;
+    /** 父 toolCallId → taskId → 最后一条快照。 */
+    tasks: Map<string, Map<string, {
+        data: TaskData;
+        entryId: string;
+    }>>;
+    /** 被 context_edit{retry|overflow} 剔除的 assistant。 */
+    retried: Set<string>;
+}
+export interface ScanState {
+    turns: TraceTurnNode[];
+    aux: TraceAuxNode[];
+    turn: TraceTurnNode | undefined;
+    /** 回合开始时的模型（推算回退用）。 */
+    turnModel: string | undefined;
+    model: string | undefined;
+    tools: Map<string, TraceToolNode>;
+    /** 有 toolResult 的调用。 */
+    resolved: Set<string>;
+    /** 回合 id → 压缩 / 分支摘要等不属于 step 的用量。 */
+    extraUsage: Map<string, Usage[]>;
+}
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** ISO 时间 → epoch ms；不合法返回 undefined。 */
+export declare function entryTime(entry: {
+    timestamp: string;
+}): number | undefined;
+export declare function num(value: unknown): number | undefined;
+/** 是有限数字时写入 `target[key]`。 */
+export declare function putNum<T extends object>(target: T, key: keyof T, value: unknown): void;
+/** `ama.trace` 的 data（形状不对返回 undefined）。 */
+export declare function traceData(entry: SessionEntry): TraceEntryData | undefined;
+export declare function buildIndex(entries: readonly SessionEntry[]): Index;
+export declare function zeroUsage(): Usage;
+/** cacheRead / (input + cacheRead + cacheWrite)；分母为 0 时 undefined。 */
+export declare function cacheHitRatio(usage: Usage | undefined): number | undefined;
+export declare function splitRef(ref: string | undefined): {
+    provider: string;
+    model: string;
+};

package/dist/trace/build-index.js

@@ -0,0 +1,127 @@
+/**
+ * 轨迹构建器的索引与扫描状态（`build.ts` 用）。[W6-T1]
+ *
+ * 预建索引：`ama.trace` 按 assistant / toolCall / compaction / usage 条目 id，`ama.task` 按父 toolCallId（同一
+ * taskId 取分支上最后一条），`external_turn` 按 taskId，`context_edit{retry|overflow}` 的目标。
+ */
+import { TRACE_CUSTOM_TYPE, } from "./types.js";
+/** 父会话 `ama.task` 的 customType（与 agents/task-record.ts 相同；这里不 import 运行时模块）。 */
+export const TASK_CUSTOM_TYPE = "ama.task";
+export function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/** ISO 时间 → epoch ms；不合法返回 undefined。 */
+export function entryTime(entry) {
+    const t = Date.parse(entry.timestamp);
+    return Number.isFinite(t) ? t : undefined;
+}
+export function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** 是有限数字时写入 `target[key]`。 */
+export function putNum(target, key, value) {
+    const v = num(value);
+    if (v !== undefined)
+        target[key] = v;
+}
+/** `ama.trace` 的 data（形状不对返回 undefined）。 */
+export function traceData(entry) {
+    if (entry.type !== "custom" || entry.customType !== TRACE_CUSTOM_TYPE)
+        return undefined;
+    const data = entry.data;
+    return isObject(data) && typeof data["kind"] === "string"
+        ? data
+        : undefined;
+}
+export function buildIndex(entries) {
+    const index = {
+        stepByAssistant: new Map(),
+        toolTiming: new Map(),
+        subcalls: new Map(),
+        compactionByEntry: new Map(),
+        auxByUsage: new Map(),
+        external: new Map(),
+        tasks: new Map(),
+        retried: new Set(),
+    };
+    for (const entry of entries) {
+        if (entry.type === "context_edit") {
+            if (entry.reason === "retry" || entry.reason === "overflow")
+                index.retried.add(entry.targetId);
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === TASK_CUSTOM_TYPE) {
+            const data = entry.data;
+            // 子会话自己的首条没有 status，不是父会话的快照
+            if (!isObject(data) || typeof data["taskId"] !== "string" || data["status"] === undefined)
+                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 });
+            index.tasks.set(parent, byTask);
+            continue;
+        }
+        const data = traceData(entry);
+        if (data === undefined)
+            continue;
+        switch (data.kind) {
+            case "step": {
+                if (typeof data.assistantEntryId === "string")
+                    index.stepByAssistant.set(data.assistantEntryId, { data, entryId: entry.id });
+                for (const tool of Array.isArray(data.tools) ? data.tools : []) {
+                    if (!isObject(tool) || typeof tool.id !== "string")
+                        continue;
+                    const known = index.toolTiming.get(tool.id);
+                    // 同一调用出现两次（中断兜底 + 正常）时留有结束时间的那条
+                    if (known === undefined || (known.endedAt === undefined && tool.endedAt !== undefined))
+                        index.toolTiming.set(tool.id, tool);
+                }
+                for (const sub of Array.isArray(data.subcalls) ? data.subcalls : []) {
+                    if (!isObject(sub) || typeof sub.id !== "string" || typeof sub.parentId !== "string")
+                        continue;
+                    const list = index.subcalls.get(sub.parentId) ?? [];
+                    if (!list.some((s) => s.data.id === sub.id))
+                        list.push({ data: sub, entryId: entry.id });
+                    index.subcalls.set(sub.parentId, list);
+                }
+                break;
+            }
+            case "compaction":
+                if (typeof data.compactionEntryId === "string")
+                    index.compactionByEntry.set(data.compactionEntryId, { data, entryId: entry.id });
+                break;
+            case "aux":
+                if (typeof data.usageEntryId === "string")
+                    index.auxByUsage.set(data.usageEntryId, { data, entryId: entry.id });
+                break;
+            case "external_turn":
+                if (typeof data.taskId === "string") {
+                    const list = index.external.get(data.taskId) ?? [];
+                    list.push({ data, entryId: entry.id });
+                    index.external.set(data.taskId, list);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return index;
+}
+export function zeroUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+}
+/** cacheRead / (input + cacheRead + cacheWrite)；分母为 0 时 undefined。 */
+export function cacheHitRatio(usage) {
+    if (usage === undefined)
+        return undefined;
+    const prompt = usage.input + usage.cacheRead + usage.cacheWrite;
+    return prompt > 0 ? usage.cacheRead / prompt : undefined;
+}
+export function splitRef(ref) {
+    if (ref === undefined)
+        return { provider: "", model: "" };
+    const at = ref.indexOf("/");
+    return at < 0
+        ? { provider: "", model: ref }
+        : { provider: ref.slice(0, at), model: ref.slice(at + 1) };
+}

package/dist/trace/build-nodes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 轨迹构建器的节点构造（`build.ts` 用）：step / tool / subcall / compaction / retry_wait / subagent /
+ * external_turn。精确时间来自 `ama.trace`，缺失时按条目时间推算并标 `approx`。[W6-T1]
+ */
+import type { AssistantMessage, Usage } from "../ai/types.js";
+import { type Index, type ScanState, type TaskData } from "./build-index.js";
+import { type TraceAuxNode, type TraceCompactionData, type TraceCompactionNode, type TraceExternalTurnData, type TraceExternalTurnNode, type TraceNodeStatus, type TraceRetryWaitData, type TraceRetryWaitNode, type TraceStepData, type TraceStepNode, type TraceSubagentNode, type TraceToolNode, type TraceTurnNode } from "./types.js";
+export declare function stepStatus(message: AssistantMessage, retried: boolean, data: TraceStepData | undefined): TraceNodeStatus;
+export declare function pushUsage(state: ScanState, turnId: string, usage: Usage): void;
+export declare function assistantStep(entryId: string, m: AssistantMessage, at: number | undefined, turn: TraceTurnNode, state: ScanState, index: Index): TraceStepNode;
+export declare function toolNode(id: string, name: string, assistantEntryId: string, step: TraceStepNode, index: Index): TraceToolNode;
+export declare function compactionNode(id: string, at: number | undefined, trace: {
+    data: TraceCompactionData;
+    entryId: string;
+} | undefined): TraceCompactionNode;
+export declare function compactionAsAux(node: TraceCompactionNode, usage: Usage | undefined): TraceAuxNode;
+export declare function retryNode(id: string, data: TraceRetryWaitData): TraceRetryWaitNode;
+/** 中断兜底的 step（没有 assistant 条目）：请求在途时补一个 aborted 的 step。 */
+export declare function abortedRequest(entryId: string, data: TraceStepData, state: ScanState): void;
+export declare function externalNodes(taskId: string, list: readonly {
+    data: TraceExternalTurnData;
+    entryId: string;
+}[]): TraceExternalTurnNode[];
+export declare function subagentNode(data: TaskData, entryId: string, live: boolean): TraceSubagentNode;