@armadra/agent 0.5.1 → 0.6.0

package/dist/trace/flatten.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
+ * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，
+ *   展开状态与光标都按 key 记。
+ * - 缺省展开：回合与请求展开、工具 / 子 Agent / 子调用折叠（子 Agent 展开即懒加载子轨迹，见 `needsChild`）。
+ * - 分页：`fromTurn` 之前的回合折成一行「更早的 N 个回合」（尾部优先）；辅助请求（保温 / 分类器 / 回合外的
+ *   压缩）在末尾收成一组，缺省折叠。
+ * - 每行带所在回合的时间窗 `span`，格式化时据此画条形（同一回合的行共用一个时间轴）。
+ */
+import type { Trace, TraceAuxNode, TraceCompactionNode, TraceExternalTurnNode, TraceRetryWaitNode, TraceStepNode, TraceSubagentNode, TraceSubcallNode, TraceToolNode, TraceTurnNode } from "./types.js";
+/** 轨迹树里的任一节点。 */
+export type TraceNode = TraceTurnNode | TraceStepNode | TraceCompactionNode | TraceRetryWaitNode | TraceToolNode | TraceSubcallNode | TraceSubagentNode | TraceExternalTurnNode | TraceAuxNode;
+/** 分页行：更早的回合。 */
+export interface TraceMoreNode {
+    kind: "more";
+    id: "more";
+    hidden: number;
+}
+/** 末尾的辅助请求组。 */
+export interface TraceAuxGroupNode {
+    kind: "aux_group";
+    id: "aux";
+    nodes: readonly TraceAuxNode[];
+}
+export type TraceRowNode = TraceNode | TraceMoreNode | TraceAuxGroupNode;
+export interface TraceSpan {
+    start: number;
+    end: number;
+}
+export interface TraceRow {
+    /** 路径 key（稳定）。 */
+    key: string;
+    depth: number;
+    node: TraceRowNode;
+    /** 所属回合的序号（1 起，按根轨迹计；子轨迹里的行按子轨迹计）；分页 / 辅助组为 0。 */
+    turn: number;
+    /** 条形的时间窗（所属回合的起止）；没有可用时间时缺省。 */
+    span?: TraceSpan;
+    expandable: boolean;
+    expanded: boolean;
+}
+export interface FlattenOptions {
+    /** 展开状态覆盖（key → 是否展开）；没有的按缺省。 */
+    expanded?: ReadonlyMap<string, boolean>;
+    /** 从第几个回合开始显示（0 起）；之前的折成一行。缺省 0。 */
+    fromTurn?: number;
+}
+export declare function rowKey(prefix: string, node: TraceNode): string;
+/** 子节点（子 Agent：已加载的子轨迹的回合，或外部骨架）。 */
+export declare function childrenOf(node: TraceRowNode): readonly TraceNode[];
+/** ama 子 Agent 有子会话文件但还没加载（展开时由调用方 `loadSubagentTrace`）。 */
+export declare function needsChild(node: TraceRowNode): node is TraceSubagentNode;
+export declare function isExpandable(node: TraceRowNode): boolean;
+/** 缺省展开：回合与请求。 */
+export declare function defaultExpanded(node: TraceRowNode): boolean;
+/** 回合的时间窗：起点 = 回合开始，终点 = 回合结束或已知的最晚时刻（进行中）。 */
+export declare function turnSpan(turn: TraceTurnNode): TraceSpan | undefined;
+/** 尾部优先分页的起始回合：最后 `page` 个回合。 */
+export declare function tailStart(trace: Trace, page: number): number;
+/** 摊平整棵轨迹（分页 + 展开状态）。 */
+export declare function flattenTrace(trace: Trace, opts?: FlattenOptions): TraceRow[];
+/** 摊平单个节点的子树（`/trace <任务 id>` 以子 Agent 为根）。 */
+export declare function flattenNode(node: TraceNode, opts?: FlattenOptions): TraceRow[];
+/** 按 key 找行下标（没有返回 -1）。 */
+export declare function rowIndex(rows: readonly TraceRow[], key: string): number;
+/** 节点计数（性能测试与 `--format json` 的规模提示用）。 */
+export declare function countNodes(trace: Trace): number;

package/dist/trace/flatten.js

@@ -0,0 +1,173 @@
+/**
+ * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
+ * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，
+ *   展开状态与光标都按 key 记。
+ * - 缺省展开：回合与请求展开、工具 / 子 Agent / 子调用折叠（子 Agent 展开即懒加载子轨迹，见 `needsChild`）。
+ * - 分页：`fromTurn` 之前的回合折成一行「更早的 N 个回合」（尾部优先）；辅助请求（保温 / 分类器 / 回合外的
+ *   压缩）在末尾收成一组，缺省折叠。
+ * - 每行带所在回合的时间窗 `span`，格式化时据此画条形（同一回合的行共用一个时间轴）。
+ */
+const KEY_CODE = {
+    turn: "t",
+    step: "s",
+    compaction: "c",
+    retry_wait: "w",
+    tool: "x",
+    subcall: "n",
+    subagent: "a",
+    external_turn: "e",
+    aux: "u",
+};
+export function rowKey(prefix, node) {
+    return `${prefix}${KEY_CODE[node.kind]}:${node.id}`;
+}
+/** 子节点（子 Agent：已加载的子轨迹的回合，或外部骨架）。 */
+export function childrenOf(node) {
+    switch (node.kind) {
+        case "turn":
+            return node.steps;
+        case "step":
+            return node.tools;
+        case "tool":
+            return node.children;
+        case "subagent":
+            return node.child?.turns ?? node.external ?? [];
+        case "aux_group":
+            return node.nodes;
+        default:
+            return [];
+    }
+}
+/** ama 子 Agent 有子会话文件但还没加载（展开时由调用方 `loadSubagentTrace`）。 */
+export function needsChild(node) {
+    return (node.kind === "subagent" &&
+        node.runner === "ama" &&
+        node.child === undefined &&
+        node.childMissing !== true &&
+        node.childRef?.sessionFile !== undefined);
+}
+export function isExpandable(node) {
+    return childrenOf(node).length > 0 || needsChild(node);
+}
+/** 缺省展开：回合与请求。 */
+export function defaultExpanded(node) {
+    return node.kind === "turn" || node.kind === "step";
+}
+/** 回合的时间窗：起点 = 回合开始，终点 = 回合结束或已知的最晚时刻（进行中）。 */
+export function turnSpan(turn) {
+    const start = turn.startedAt;
+    if (start === undefined)
+        return undefined;
+    let end = turn.endedAt ?? start;
+    const see = (t) => {
+        if (t !== undefined && t > end)
+            end = t;
+    };
+    for (const node of turn.steps) {
+        see(node.startedAt);
+        see(node.endedAt);
+        if (node.kind !== "step")
+            continue;
+        see(node.firstTokenAt);
+        for (const tool of node.tools) {
+            see(tool.startedAt);
+            see(tool.endedAt);
+        }
+    }
+    return { start, end };
+}
+/** 节点自身的时间窗（子 Agent / 外部回合的子行用）。 */
+function nodeSpan(node) {
+    if (node.startedAt === undefined)
+        return undefined;
+    return { start: node.startedAt, end: node.endedAt ?? node.startedAt };
+}
+/** 尾部优先分页的起始回合：最后 `page` 个回合。 */
+export function tailStart(trace, page) {
+    return Math.max(0, trace.turns.length - page);
+}
+function walk(w, node, prefix, depth, turn, span) {
+    const key = rowKey(prefix, node);
+    const expandable = isExpandable(node);
+    const expanded = expandable && (w.expanded.get(key) ?? defaultExpanded(node));
+    const row = { key, depth, node, turn, expandable, expanded };
+    if (span !== undefined)
+        row.span = span;
+    w.rows.push(row);
+    if (!expanded)
+        return;
+    const childPrefix = `${key}/`;
+    if (node.kind === "subagent") {
+        // 子轨迹的回合各用自己的时间窗；外部骨架用子 Agent 的时间窗
+        if (node.child !== undefined) {
+            node.child.turns.forEach((child, i) => walk(w, child, childPrefix, depth + 1, i + 1, turnSpan(child)));
+            return;
+        }
+        const own = nodeSpan(node) ?? span;
+        for (const child of node.external ?? [])
+            walk(w, child, childPrefix, depth + 1, turn, own);
+        return;
+    }
+    for (const child of childrenOf(node))
+        walk(w, child, childPrefix, depth + 1, turn, span);
+}
+/** 摊平整棵轨迹（分页 + 展开状态）。 */
+export function flattenTrace(trace, opts = {}) {
+    const w = { rows: [], expanded: opts.expanded ?? new Map() };
+    const from = Math.max(0, Math.min(opts.fromTurn ?? 0, trace.turns.length));
+    if (from > 0)
+        w.rows.push({
+            key: "more",
+            depth: 0,
+            node: { kind: "more", id: "more", hidden: from },
+            turn: 0,
+            expandable: false,
+            expanded: false,
+        });
+    for (let i = from; i < trace.turns.length; i++) {
+        const turn = trace.turns[i];
+        walk(w, turn, "", 0, i + 1, turnSpan(turn));
+    }
+    if (trace.aux.length > 0) {
+        const group = { kind: "aux_group", id: "aux", nodes: trace.aux };
+        const expanded = w.expanded.get("aux") ?? false;
+        w.rows.push({ key: "aux", depth: 0, node: group, turn: 0, expandable: true, expanded });
+        if (expanded)
+            for (const aux of trace.aux)
+                walk(w, aux, "aux/", 1, 0, nodeSpan(aux));
+    }
+    return w.rows;
+}
+/** 摊平单个节点的子树（`/trace <任务 id>` 以子 Agent 为根）。 */
+export function flattenNode(node, opts = {}) {
+    const w = { rows: [], expanded: opts.expanded ?? new Map() };
+    walk(w, node, "", 0, 0, nodeSpan(node));
+    return w.rows;
+}
+/** 按 key 找行下标（没有返回 -1）。 */
+export function rowIndex(rows, key) {
+    return rows.findIndex((row) => row.key === key);
+}
+/** 节点计数（性能测试与 `--format json` 的规模提示用）。 */
+export function countNodes(trace) {
+    let n = trace.aux.length;
+    const visit = (node) => {
+        n++;
+        if (node.kind === "subagent") {
+            if (node.child !== undefined)
+                for (const t of node.child.turns)
+                    visit(t);
+            else
+                for (const e of node.external ?? [])
+                    visit(e);
+            return;
+        }
+        for (const child of childrenOf(node))
+            visit(child);
+    };
+    for (const turn of trace.turns)
+        visit(turn);
+    return n;
+}

package/dist/trace/format.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
+ * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；
+ *   ASCII 或无色（`NO_COLOR`）降级为 `[==..--]`（`.` = TTFT、`=` = 解码、`-` = 工具、`|` = 起点）。
+ * - 宽 ≥ 60 显示条形与 token 列；宽 < 60 只留「标签 · 耗时」；40 列可用。
+ * - 耗时：精确时间 `2.1s`，推算的加 `≈`（ASCII `~`），进行中 `…`。
+ * - ↑ = 提示 token（input + cacheRead + cacheWrite），↓ = 输出 token，缓存% = cacheRead / 提示 token。
+ *
+ * `formatTraceText` 是 line 模式 `/trace` 的整表输出（无条形、不截断）。标签里来自正文的部分（用户提示预览、
+ * 工具参数摘要）由调用方经 `describe` 提供——轨迹本身不含正文。
+ */
+import type { Theme } from "../tui/component.js";
+import { type TraceRow, type TraceRowNode } from "./flatten.js";
+import type { Trace } from "./types.js";
+export interface TraceFormatContext {
+    theme: Theme;
+    /** 来自正文的标签部分：回合 → 用户提示预览，工具 → 参数摘要；没有返回 undefined。 */
+    describe?(node: TraceRowNode): string | undefined;
+}
+/** 宽度低于它时去掉条形与 token 列。 */
+export declare const NARROW_WIDTH = 60;
+export declare function barWidth(width: number): number;
+/** 节点耗时文字：精确 `2.1s`、推算 `≈2.1s`、进行中 `…`、没有时间为空。 */
+export declare function durationText(node: TraceRowNode, theme: Theme): string;
+/** 状态记号（完成时为空）。 */
+export declare function statusMark(node: TraceRowNode, theme: Theme): string;
+/** token 列：`↑12k ↓980`（没有用量为空）。 */
+export declare function tokensText(node: TraceRowNode, theme: Theme): string;
+/** 缓存命中列。 */
+export declare function cacheText(node: TraceRowNode): string;
+/** 行标签（不含缩进、折叠符与状态记号）。 */
+export declare function rowLabel(row: TraceRow, ctx: Pick<TraceFormatContext, "describe">): string;
+/** 条形（含两侧括号，共 `width` 列）；没有时间窗时为空白。 */
+export declare function barText(row: TraceRow, width: number, theme: Theme): string;
+/** 一行（可见宽恰为 `width`）。`selected` 时行首画光标。 */
+export declare function formatRow(row: TraceRow, width: number, ctx: TraceFormatContext, selected?: boolean): string;
+/** 顶部汇总：回合 · 请求 · 工具 · 总耗时 · ↑↓ · 缓存 · ttft 分位 · 平均吞吐。 */
+export declare function summaryText(trace: Trace, theme: Theme): string;
+/** 整表展开（line 模式与测试）：全部节点展开，子调用与子 Agent 也展开。 */
+export declare function expandAll(rows: (expanded: Map<string, boolean>) => TraceRow[]): TraceRow[];
+/**
+ * line 模式 `/trace` 的文本：标题 + 汇总 + 全部节点（缩进树），每行「标签  耗时  ↑in ↓out  缓存%」，
+ * 不画条形、不截断。
+ */
+export declare function formatTraceText(trace: Trace, ctx: TraceFormatContext, rows?: TraceRow[], title?: string): string;

package/dist/trace/format.js

@@ -0,0 +1,329 @@
+/**
+ * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
+ * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；
+ *   ASCII 或无色（`NO_COLOR`）降级为 `[==..--]`（`.` = TTFT、`=` = 解码、`-` = 工具、`|` = 起点）。
+ * - 宽 ≥ 60 显示条形与 token 列；宽 < 60 只留「标签 · 耗时」；40 列可用。
+ * - 耗时：精确时间 `2.1s`，推算的加 `≈`（ASCII `~`），进行中 `…`。
+ * - ↑ = 提示 token（input + cacheRead + cacheWrite），↓ = 输出 token，缓存% = cacheRead / 提示 token。
+ *
+ * `formatTraceText` 是 line 模式 `/trace` 的整表输出（无条形、不截断）。标签里来自正文的部分（用户提示预览、
+ * 工具参数摘要）由调用方经 `describe` 提供——轨迹本身不含正文。
+ */
+import { formatDuration, msg } from "../i18n/index.js";
+import { formatPercent, formatTokenCount } from "../modes/session-report.js";
+import { padToWidth, truncateToWidth, visibleWidth } from "../tui/ansi.js";
+import { cacheHitRatio } from "./build-index.js";
+import { flattenTrace, } from "./flatten.js";
+/** 宽度低于它时去掉条形与 token 列。 */
+export const NARROW_WIDTH = 60;
+const DURATION_WIDTH = 7;
+const TOKENS_WIDTH = 13;
+const CACHE_WIDTH = 4;
+/** 缩进上限（深层子 Agent 不把标签挤没）。 */
+const MAX_INDENT = 10;
+export function barWidth(width) {
+    return width >= 100 ? 26 : width >= 80 ? 14 : 10;
+}
+function plainBars(theme) {
+    return theme.glyphs.ascii || theme.caps.colors === 0;
+}
+/** 节点耗时文字：精确 `2.1s`、推算 `≈2.1s`、进行中 `…`、没有时间为空。 */
+export function durationText(node, theme) {
+    if (node.kind === "more" || node.kind === "aux_group")
+        return "";
+    if (node.status === "running")
+        return theme.glyphs.ellipsis;
+    if (node.startedAt === undefined || node.endedAt === undefined)
+        return "";
+    const text = formatDuration(node.endedAt - node.startedAt, "precise");
+    return node.approx === true ? `${theme.glyphs.ascii ? "~" : "≈"}${text}` : text;
+}
+const STATUS_COLOR = {
+    error: "error",
+    denied: "error",
+    aborted: "warning",
+    interrupted: "warning",
+    retried: "warning",
+    running: "accent",
+};
+/** 状态记号（完成时为空）。 */
+export function statusMark(node, theme) {
+    if (node.kind === "more" || node.kind === "aux_group")
+        return "";
+    const g = theme.glyphs;
+    const mark = {
+        error: g.fail,
+        denied: g.blocked,
+        aborted: g.warn,
+        interrupted: g.warn,
+        retried: g.retry,
+        running: g.spinnerStatic,
+    };
+    const text = mark[node.status];
+    const color = STATUS_COLOR[node.status];
+    return text === undefined || color === undefined ? "" : theme.fg(color, text);
+}
+function usageOf(node) {
+    switch (node.kind) {
+        case "step":
+        case "aux":
+        case "subagent":
+            return node.usage;
+        default:
+            return undefined;
+    }
+}
+/** token 列：`↑12k ↓980`（没有用量为空）。 */
+export function tokensText(node, theme) {
+    const { arrowUp, arrowDown } = theme.glyphs;
+    if (node.kind === "turn") {
+        const u = node.usage;
+        if (u.requests === 0)
+            return "";
+        const prompt = u.input + u.cacheRead + u.cacheWrite;
+        return `${arrowUp}${formatTokenCount(prompt)} ${arrowDown}${formatTokenCount(u.output)}`;
+    }
+    const usage = usageOf(node);
+    if (usage === undefined)
+        return "";
+    const prompt = usage.input + usage.cacheRead + usage.cacheWrite;
+    if (prompt === 0 && usage.output === 0)
+        return "";
+    return `${arrowUp}${formatTokenCount(prompt)} ${arrowDown}${formatTokenCount(usage.output)}`;
+}
+/** 缓存命中列。 */
+export function cacheText(node) {
+    const ratio = node.kind === "turn" ? node.usage.cacheHitRatio : cacheHitRatio(usageOf(node));
+    return ratio === undefined ? "" : formatPercent(ratio);
+}
+function auxLabel(purpose) {
+    const aux = msg().trace.row.aux;
+    return purpose === "cache_warm"
+        ? aux.cache_warm
+        : purpose === "permission_classify"
+            ? aux.permission_classify
+            : purpose === "compaction"
+                ? msg().trace.row.compactionPlain
+                : purpose;
+}
+/** 行标签（不含缩进、折叠符与状态记号）。 */
+export function rowLabel(row, ctx) {
+    const m = msg().trace.row;
+    const node = row.node;
+    const described = ctx.describe?.(node);
+    switch (node.kind) {
+        case "more":
+            return m.more(node.hidden);
+        case "aux_group":
+            return m.auxGroup(node.nodes.length);
+        case "turn": {
+            const text = described ?? "";
+            const origin = node.origin;
+            return origin === undefined || origin === "followUp"
+                ? m.turn(row.turn, text).trimEnd()
+                : m.turnOrigin(row.turn, origin, text).trimEnd();
+        }
+        case "step": {
+            const base = node.attempt > 1 ? m.stepAttempt(node.model, node.attempt) : m.step(node.model);
+            const parts = [base];
+            if (node.fallbackFrom !== undefined)
+                parts.push(m.fallback(node.fallbackFrom));
+            if (node.ttftMs !== undefined)
+                parts.push(`ttft ${formatDuration(node.ttftMs, "precise")}`);
+            if (node.tps !== undefined)
+                parts.push(`${Math.round(node.tps)} tok/s`);
+            return parts.join(" · ");
+        }
+        case "tool":
+            return described !== undefined && described !== "" ? `${node.name} ${described}` : node.name;
+        case "subcall":
+            return described !== undefined && described !== "" ? `${node.name} ${described}` : node.name;
+        case "subagent": {
+            const base = node.runner === "ama" || node.runner === node.agent
+                ? m.subagent(node.taskId, node.agent)
+                : m.subagentExternal(node.taskId, node.agent, node.runner);
+            const parts = [base];
+            if (node.background)
+                parts.push(m.background);
+            if (node.childMissing === true)
+                parts.push(m.childMissing);
+            return parts.join(" · ");
+        }
+        case "external_turn":
+            return m.externalTurn(node.turn, node.toolCount, node.filesTouched);
+        case "compaction":
+            return node.trigger === undefined ? m.compactionPlain : m.compaction(node.trigger);
+        case "retry_wait":
+            return m.retryWait(formatDuration(node.delayMs, "precise"), node.attempt);
+        case "aux":
+            return auxLabel(node.purpose);
+    }
+}
+const DECODE = 3;
+const TTFT = 2;
+const TOOL = 1;
+const MARK = 4;
+function pushSegments(node, out, deep) {
+    const running = node.status === "running" && node.endedAt === undefined;
+    switch (node.kind) {
+        case "step": {
+            const start = node.requestAt ?? node.startedAt;
+            if (start !== undefined) {
+                if (node.firstTokenAt !== undefined) {
+                    out.push({ from: start, to: node.firstTokenAt, rank: TTFT });
+                    if (node.doneAt !== undefined)
+                        out.push({ from: node.firstTokenAt, to: node.doneAt, rank: DECODE });
+                }
+                else if (node.doneAt !== undefined)
+                    out.push({ from: start, to: node.doneAt, rank: DECODE });
+                if (running)
+                    out.push({ from: start, to: start, rank: MARK });
+            }
+            for (const tool of node.tools)
+                pushSegments(tool, out, false);
+            return;
+        }
+        case "turn":
+            for (const child of node.steps)
+                pushSegments(child, out, true);
+            return;
+        case "retry_wait":
+            return;
+        default: {
+            const start = node.startedAt;
+            if (start === undefined)
+                return;
+            const rank = node.kind === "compaction" || node.kind === "aux" ? DECODE : TOOL;
+            if (running)
+                out.push({ from: start, to: start, rank: MARK });
+            else if (node.endedAt !== undefined)
+                out.push({ from: start, to: node.endedAt, rank });
+            if (deep && node.kind === "tool")
+                for (const child of node.children)
+                    pushSegments(child, out, false);
+        }
+    }
+}
+/** 条形（含两侧括号，共 `width` 列）；没有时间窗时为空白。 */
+export function barText(row, width, theme) {
+    const plain = plainBars(theme);
+    const cells = Math.max(1, width - 2);
+    const ranks = new Array(cells).fill(0);
+    const span = row.span;
+    const node = row.node;
+    if (span !== undefined && node.kind !== "more" && node.kind !== "aux_group") {
+        const segs = [];
+        pushSegments(node, segs, true);
+        const total = Math.max(1, span.end - span.start);
+        const cellOf = (t) => Math.min(cells - 1, Math.max(0, Math.floor(((t - span.start) / total) * cells)));
+        for (const seg of segs) {
+            const a = cellOf(seg.from);
+            const b = seg.to > seg.from ? cellOf(seg.to - 1e-6) : a;
+            for (let i = a; i <= b; i++)
+                ranks[i] = Math.max(ranks[i], seg.rank);
+        }
+    }
+    const chars = plain ? [" ", "-", ".", "=", "|"] : [" ", "░", "▒", "█", "│"];
+    const colors = [undefined, "tool", "muted", "accent", "warning"];
+    let body = "";
+    for (const rank of ranks) {
+        const ch = chars[rank];
+        const color = colors[rank];
+        body += color === undefined || plain ? ch : theme.fg(color, ch);
+    }
+    const [open, close] = plain ? ["[", "]"] : ["▕", "▏"];
+    return theme.fg("border", open) + body + theme.fg("border", close);
+}
+function labelPart(row, ctx) {
+    const g = ctx.theme.glyphs;
+    const indent = " ".repeat(Math.min(row.depth * 2, MAX_INDENT));
+    const fold = row.expandable ? (row.expanded ? g.collapse : g.expand) : " ";
+    const mark = statusMark(row.node, ctx.theme);
+    const label = rowLabel(row, ctx);
+    const styled = row.node.kind === "turn"
+        ? ctx.theme.bold(label)
+        : row.node.kind === "more" || row.node.kind === "aux_group"
+            ? ctx.theme.dim(label)
+            : label;
+    return `${indent}${ctx.theme.fg("dim", fold)} ${mark === "" ? "" : `${mark} `}${styled}`;
+}
+/** 一行（可见宽恰为 `width`）。`selected` 时行首画光标。 */
+export function formatRow(row, width, ctx, selected = false) {
+    const theme = ctx.theme;
+    const cursor = selected ? theme.fg("accent", theme.glyphs.prompt) : " ";
+    const inner = Math.max(1, width - 1);
+    const duration = durationText(row.node, theme).padStart(DURATION_WIDTH);
+    let right;
+    if (width < NARROW_WIDTH)
+        right = ` ${duration}`;
+    else {
+        const bar = barText(row, barWidth(width), theme);
+        const tokens = padToWidth(tokensText(row.node, theme), TOKENS_WIDTH);
+        const cache = cacheText(row.node).padStart(CACHE_WIDTH);
+        right = ` ${duration} ${bar} ${tokens} ${cache}`;
+    }
+    const labelWidth = Math.max(1, inner - visibleWidth(right));
+    const label = padToWidth(truncateToWidth(labelPart(row, ctx), labelWidth, theme.glyphs.ellipsis), labelWidth);
+    const line = `${cursor}${label}${theme.fg("muted", right)}`;
+    return selected && theme.caps.colors >= 256 ? theme.bg("selection", line) : line;
+}
+/** 顶部汇总：回合 · 请求 · 工具 · 总耗时 · ↑↓ · 缓存 · ttft 分位 · 平均吞吐。 */
+export function summaryText(trace, theme) {
+    const m = msg().trace;
+    const t = trace.totals;
+    const parts = [m.summary(trace.turns.length, t.requests, t.toolCalls)];
+    if (t.durationMs !== undefined)
+        parts.push(formatDuration(t.durationMs, "precise"));
+    if (t.requests > 0) {
+        const prompt = t.input + t.cacheRead + t.cacheWrite;
+        const { arrowUp, arrowDown } = theme.glyphs;
+        parts.push(`${arrowUp}${formatTokenCount(prompt)} ${arrowDown}${formatTokenCount(t.output)}`);
+    }
+    if (t.cacheHitRatio !== undefined)
+        parts.push(m.cache(formatPercent(t.cacheHitRatio)));
+    if (t.ttftP50 !== undefined) {
+        const p50 = formatDuration(t.ttftP50, "precise");
+        const p90 = t.ttftP90 !== undefined ? ` / p90 ${formatDuration(t.ttftP90, "precise")}` : "";
+        parts.push(`ttft p50 ${p50}${p90}`);
+    }
+    if (t.avgTps !== undefined)
+        parts.push(`${Math.round(t.avgTps)} tok/s`);
+    return parts.join(" · ");
+}
+/** 整表展开（line 模式与测试）：全部节点展开，子调用与子 Agent 也展开。 */
+export function expandAll(rows) {
+    const expanded = new Map();
+    for (let guard = 0; guard < 8; guard++) {
+        let changed = false;
+        for (const row of rows(expanded))
+            if (row.expandable && !row.expanded && row.node.kind !== "more") {
+                expanded.set(row.key, true);
+                changed = true;
+            }
+        if (!changed)
+            break;
+    }
+    return rows(expanded);
+}
+/**
+ * line 模式 `/trace` 的文本：标题 + 汇总 + 全部节点（缩进树），每行「标签  耗时  ↑in ↓out  缓存%」，
+ * 不画条形、不截断。
+ */
+export function formatTraceText(trace, ctx, rows = expandAll((expanded) => flattenTrace(trace, { expanded })), title = `${msg().trace.title} · ${summaryText(trace, ctx.theme)}`) {
+    const theme = ctx.theme;
+    const lines = [title];
+    if (rows.length === 0)
+        lines.push(msg().trace.empty);
+    for (const row of rows) {
+        const indent = "  ".repeat(row.depth);
+        const mark = statusMark(row.node, theme);
+        const cols = [durationText(row.node, theme), tokensText(row.node, theme), cacheText(row.node)]
+            .filter((c) => c !== "")
+            .join("  ");
+        const label = `${indent}${mark === "" ? "" : `${mark} `}${rowLabel(row, ctx)}`;
+        lines.push(cols === "" ? label : `${label}  ${cols}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/trace/html-template.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 轨迹 HTML 的页面骨架、样式与脚本（docs/wave6-plan.md §2.5）。[W6-T2]
+ *
+ * 全部静态：页面只插入三样东西——`lang`、转义过的 `<title>`、已做脚本安全转义的 JSON（`html.ts`）。
+ * 脚本只用 `textContent` / `createElement` 写 DOM，不用 `innerHTML`；没有任何外部资源（CSP 见 `CSP`）。
+ *
+ * 页面：顶部标题 / 汇总 / 工具栏（搜索、跳到回合、缩放、全部展开 / 折叠、图例）；中间是一张表——左列树
+ * （sticky）+ 右侧瀑布（横轴 = 会话时间，回合间空闲已压缩，刻度标原始时间）；底部详情。行高固定、只建
+ * 可见 ±50 行的 DOM（虚拟列表），10k 行也流畅。键：↑↓ 选择、←→ 折叠 / 展开、`/` 搜索、Enter / Shift+Enter
+ * 在匹配间跳转、Ctrl + 滚轮缩放。深浅色跟随系统。
+ */
+export declare const CSP = "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'";
+export declare function escapeHtml(text: string): string;
+/** 页面骨架。`json` 必须已经过 `scriptSafeJson`。 */
+export declare function renderPage(parts: {
+    lang: string;
+    title: string;
+    json: string;
+}): string;