@armadra/agent 0.5.0 → 0.6.0

package/dist/trace/html-template.js

@@ -0,0 +1,150 @@
+/**
+ * 轨迹 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 const CSP = "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'";
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+const STYLE = `
+:root{--bg:#fff;--fg:#1f2328;--mut:#656d76;--line:#d8dee4;--alt:#f6f8fa;--sel:#ddf4ff;--hit:#fff8c5;
+--ttft:#bf8700;--dec:#0969da;--tool:#1a7f37;--agent:#8250df;--wait:#8c959f;--oth:#1b7c83;--turn:#d0d7de;
+--err:#cf222e;--warn:#9a6700;--run:#0969da;--lw:420px;font:13px/1.4 ui-sans-serif,system-ui,sans-serif}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--mut:#8d96a0;--line:#30363d;--alt:#161b22;
+--sel:#1f3a5f;--hit:#3b2e00;--ttft:#d29922;--dec:#4493f8;--tool:#3fb950;--agent:#ab7df8;--wait:#6e7681;
+--oth:#39c5cf;--turn:#30363d;--err:#f85149;--warn:#d29922;--run:#4493f8}}
+*{box-sizing:border-box}html,body{margin:0;height:100%;background:var(--bg);color:var(--fg)}
+body{display:flex;flex-direction:column}
+header{padding:8px 12px;border-bottom:1px solid var(--line)}
+h1{font-size:15px;margin:0 0 2px}.sum{font-variant-numeric:tabular-nums}.mut{color:var(--mut)}
+.bar{display:flex;flex-wrap:wrap;gap:6px;align-items:center;margin-top:6px}
+input,select,button{font:inherit;color:inherit;background:var(--alt);border:1px solid var(--line);border-radius:4px;padding:2px 6px}
+button{cursor:pointer}input{width:200px}
+.lg{display:inline-flex;align-items:center;gap:4px;margin-left:6px;color:var(--mut)}
+.sw{display:inline-block;width:10px;height:10px;border-radius:2px}
+#sc{flex:1;overflow:auto;position:relative}
+#ru{position:sticky;top:0;z-index:3;height:20px;display:flex;background:var(--bg);border-bottom:1px solid var(--line)}
+#ru .lc{background:var(--bg)}#tk{position:relative;flex:none;height:20px}
+.tick{position:absolute;top:0;height:20px;border-left:1px solid var(--line);padding-left:3px;font-size:11px;color:var(--mut);white-space:nowrap}
+#bd{position:relative}
+.row{position:absolute;left:0;height:22px;display:flex;cursor:default}
+.row.odd .lc,.row.odd .wf{background:var(--alt)}
+.row.sel .lc,.row.sel .wf{background:var(--sel)}.row.hit .lc{background:var(--hit)}
+.lc{position:sticky;left:0;z-index:2;flex:none;width:var(--lw);display:flex;align-items:center;gap:4px;
+padding-right:6px;background:var(--bg);border-right:1px solid var(--line);overflow:hidden;white-space:nowrap}
+.tg{flex:none;width:14px;text-align:center;color:var(--mut);cursor:pointer}
+.lb{flex:1;overflow:hidden;text-overflow:ellipsis}.k-turn .lb{font-weight:600}
+.cols{flex:none;color:var(--mut);font-size:12px;font-variant-numeric:tabular-nums}
+.st{flex:none;font-size:11px;padding:0 4px;border-radius:3px;color:var(--bg);background:var(--mut)}
+.st.error,.st.denied{background:var(--err)}.st.aborted,.st.interrupted,.st.retried{background:var(--warn)}.st.running{background:var(--run)}
+.wf{position:relative;flex:none;height:22px}
+.sg{position:absolute;top:6px;height:10px;min-width:2px;border-radius:2px}
+.sg.turn{top:9px;height:4px;background:var(--turn)}.sg.ttft{background:var(--ttft)}.sg.dec{background:var(--dec)}
+.sg.tool{background:var(--tool)}.sg.agent{background:var(--agent)}.sg.oth{background:var(--oth)}
+.sg.wait{background:repeating-linear-gradient(45deg,var(--wait) 0 3px,transparent 3px 6px)}
+.sg.run{width:2px;top:3px;height:16px;background:var(--run)}
+#dt{height:32vh;overflow:auto;border-top:1px solid var(--line);padding:8px 12px}
+#dt h2{font-size:14px;margin:0 0 6px}#dt h3{font-size:12px;margin:10px 0 4px;color:var(--mut)}
+#dt table{border-collapse:collapse}#dt td{padding:1px 12px 1px 0;vertical-align:top}#dt td:first-child{color:var(--mut);white-space:nowrap}
+pre{margin:0;padding:6px 8px;background:var(--alt);border:1px solid var(--line);border-radius:4px;white-space:pre-wrap;word-break:break-word;max-height:40vh;overflow:auto}
+footer{padding:4px 12px;border-top:1px solid var(--line);font-size:11px;color:var(--mut)}
+`;
+const SCRIPT = `
+(function(){"use strict";
+var D=JSON.parse(document.getElementById("data").textContent),R=D.rows,I=D.i18n,N=R.length;
+var RH=22,OV=50,LW=420,AX=D.axis,SPAN=D.span;
+function lw(){LW=Math.max(200,Math.min(420,Math.floor($("sc").clientWidth*0.45)));document.documentElement.style.setProperty("--lw",LW+"px")}
+var $=function(id){return document.getElementById(id)};
+function el(tag,cls,text){var e=document.createElement(tag);if(cls)e.className=cls;if(text!=null)e.textContent=text;return e}
+var kids=new Uint8Array(N),open=new Uint8Array(N),vis=[],sel=-1,hits=[],hit=-1,hitSet={},scale=1,W=0,fitted=1;
+for(var i=0;i<N;i++){if(R[i].p>=0)kids[R[i].p]=1;if(R[i].e)open[i]=1}
+function rebuild(){vis=[];var skip=1e9;for(var i=0;i<N;i++){var r=R[i];if(r.d>skip)continue;skip=1e9;vis.push(i);if(kids[i]&&!open[i])skip=r.d}
+$("bd").style.height=(vis.length*RH)+"px";draw()}
+function width(){return Math.max(SPAN*scale,$("sc").clientWidth-LW-2)}
+function fit(){fitted=1;scale=Math.max(1e-6,($("sc").clientWidth-LW-24)/SPAN);rebuild()}
+function inv(m){var p=AX[0]||[0,0];for(var k=0;k<AX.length;k++){var q=AX[k];if(m<=q[1]){return q[1]===p[1]?q[0]:p[0]+(m-p[1])*(q[0]-p[0])/(q[1]-p[1])}p=q}return p[0]+(m-p[1])}
+function fmt(ms){ms=Math.max(0,Math.round(ms));if(ms<1000)return ms+"ms";var s=ms/1000;if(s<60)return(s<10?s.toFixed(1):Math.floor(s))+"s";s=Math.floor(s);return Math.floor(s/60)+"m"+String(s%60).padStart(2,"0")+"s"}
+function ticks(){var t=$("tk"),sc=$("sc");t.style.width=W+"px";t.textContent="";
+var a=Math.max(0,sc.scrollLeft-LW),b=a+sc.clientWidth,raw=90/scale,step=1;
+while(step<raw){step*=(String(step).charAt(0)==="2"?2.5:2)}
+for(var x=Math.floor(a/scale/step)*step;x*scale<=b;x+=step){if(x<0)continue;var e=el("div","tick",fmt(inv(x)));e.style.left=(x*scale)+"px";t.appendChild(e)}}
+function row(idx,top){var i=vis[idx],r=R[i],e=el("div","row k-"+r.k+(idx%2?" odd":"")+(i===sel?" sel":"")+(hitSet[i]?" hit":""));
+e.style.top=top+"px";e.dataset.i=i;var lc=el("div","lc");lc.style.paddingLeft=(4+Math.min(r.d,12)*14)+"px";
+var tg=el("span","tg",kids[i]?(open[i]?"\\u25BE":"\\u25B8"):"");tg.dataset.t="1";lc.appendChild(tg);
+if(r.s){lc.appendChild(el("span","st "+(r.sc||""),r.s))}
+var lb=el("span","lb",r.l);lb.title=r.l;lc.appendChild(lb);
+var cols=[r.du,r.tk,r.ca].filter(Boolean).join("  ");if(cols)lc.appendChild(el("span","cols",cols));
+e.appendChild(lc);var wf=el("div","wf");wf.style.width=W+"px";
+(r.g||[]).forEach(function(g){var s=el("div","sg "+g[2]);s.style.left=(g[0]*scale)+"px";if(g[2]!=="run")s.style.width=Math.max(2,(g[1]-g[0])*scale)+"px";wf.appendChild(s)});
+e.appendChild(wf);e.style.width=(LW+W)+"px";return e}
+var pend=0;function draw(){if(pend)return;pend=1;requestAnimationFrame(function(){pend=0;paint()})}
+function paint(){var sc=$("sc"),bd=$("bd"),h=sc.clientHeight,first=Math.max(0,Math.floor(sc.scrollTop/RH)-OV),last=Math.min(vis.length,Math.ceil((sc.scrollTop+h)/RH)+OV);
+W=width();bd.textContent="";if(N===0){bd.appendChild(el("div","mut",I.empty));return}
+for(var k=first;k<last;k++)bd.appendChild(row(k,k*RH));ticks()}
+function select(i,scroll){sel=i;var at=vis.indexOf(i);if(scroll&&at>=0){var sc=$("sc"),top=at*RH;if(top<sc.scrollTop+20||top>sc.scrollTop+sc.clientHeight-RH*2)sc.scrollTop=Math.max(0,top-sc.clientHeight/3)}detail(i);draw()}
+function reveal(i){for(var p=R[i].p;p>=0;p=R[p].p)open[p]=1;rebuild();select(i,true)}
+function toggle(i,v){if(!kids[i])return;open[i]=v==null?(open[i]?0:1):v;rebuild()}
+function detail(i){var d=$("dt");d.textContent="";if(i<0){d.appendChild(el("div","mut",I.detailEmpty));return}var r=R[i];
+d.appendChild(el("h2",null,r.l));if(r.kv.length){var t=el("table");r.kv.forEach(function(kv){var tr=el("tr");tr.appendChild(el("td",null,kv[0]));tr.appendChild(el("td",null,kv[1]));t.appendChild(tr)});d.appendChild(t)}
+(r.pv||[]).forEach(function(p){d.appendChild(el("h3",null,p[0]));d.appendChild(el("pre",null,p[1]))});
+var note=!D.content?I.noContent:r.pd?I.previewDropped:r.pc?I.childPreviewOff:"";if(note)d.appendChild(el("p","mut",note))}
+function search(q){q=q.trim().toLowerCase();hits=[];hitSet={};hit=-1;if(q){for(var i=0;i<N;i++){var r=R[i],s=r.l+" "+(r.pv||[]).map(function(p){return p[1]}).join(" ");if(s.toLowerCase().indexOf(q)>=0){hits.push(i);hitSet[i]=1}}}
+$("cnt").textContent=q?(hits.length?"0/"+hits.length:I.noMatch):"";draw()}
+function next(dir){if(!hits.length)return;hit=(hit+dir+hits.length)%hits.length;$("cnt").textContent=(hit+1)+"/"+hits.length;reveal(hits[hit])}
+function init(){document.title=D.title;$("h").textContent=D.title;$("sum").textContent=D.summary;$("meta").textContent=D.meta;$("ft").textContent=D.footer;
+var q=$("q");q.placeholder=I.search;q.addEventListener("input",function(){search(q.value)});
+q.addEventListener("keydown",function(e){if(e.key==="Enter"){next(e.shiftKey?-1:1);e.preventDefault()}else if(e.key==="Escape")q.blur()});
+var j=$("jump");j.appendChild(el("option",null,I.jump)).value="";
+R.forEach(function(r,i){if(r.t){var o=el("option",null,r.l.length>60?r.l.slice(0,59)+"\\u2026":r.l);o.value=String(i);j.appendChild(o)}});
+j.addEventListener("change",function(){if(j.value!==""){var i=+j.value;open[i]=1;reveal(i);j.value=""}});
+[["zo",I.zoomOut,function(){zoom(0.5)}],["zi",I.zoomIn,function(){zoom(2)}],["zf",I.zoomFit,fit],
+["ea",I.expandAll,function(){open.fill(1);rebuild()}],["ca",I.collapseAll,function(){open.fill(0);rebuild()}]].forEach(function(b){var e=$(b[0]);e.textContent=b[1];e.addEventListener("click",b[2])});
+["ttft","dec","tool","agent","wait","oth"].forEach(function(c){var s=el("span","lg");s.appendChild(el("span","sw sg "+c)).style.position="static";s.appendChild(document.createTextNode(I[c]));$("lg").appendChild(s)});
+$("note").textContent=I.axisNote+" \\u00B7 "+I.keys;
+var sc=$("sc");sc.addEventListener("scroll",draw);window.addEventListener("resize",function(){lw();if(fitted)fit();else draw()});
+sc.addEventListener("wheel",function(e){if(!e.ctrlKey&&!e.metaKey)return;e.preventDefault();var x=e.clientX-sc.getBoundingClientRect().left-LW;zoom(e.deltaY<0?1.25:0.8,x)},{passive:false});
+$("bd").addEventListener("click",function(e){var r=e.target.closest(".row");if(!r)return;var i=+r.dataset.i;if(e.target.dataset.t)toggle(i);select(i,false)});
+$("bd").addEventListener("dblclick",function(e){var r=e.target.closest(".row");if(r)toggle(+r.dataset.i)});
+document.addEventListener("keydown",function(e){if(e.target===q||e.target===j||!vis.length)return;var at=vis.indexOf(sel);
+if(e.key==="/"){q.focus();e.preventDefault()}else if(e.key==="ArrowDown"){select(vis[Math.min(vis.length-1,at+1)],true);e.preventDefault()}
+else if(e.key==="ArrowUp"){select(vis[Math.max(0,at-1)],true);e.preventDefault()}
+else if(e.key==="ArrowRight"&&sel>=0){toggle(sel,1);e.preventDefault()}
+else if(e.key==="ArrowLeft"&&sel>=0){if(kids[sel]&&open[sel])toggle(sel,0);else if(R[sel].p>=0)select(R[sel].p,true);e.preventDefault()}});
+detail(-1);lw();fit()}
+function zoom(f,x){fitted=0;var sc=$("sc");if(x==null)x=(sc.clientWidth-LW)/2;var t=(sc.scrollLeft+x)/scale;scale=Math.min(1e3,Math.max(1e-7,scale*f));rebuild();sc.scrollLeft=Math.max(0,t*scale-x)}
+init()})();
+`;
+/** 页面骨架。`json` 必须已经过 `scriptSafeJson`。 */
+export function renderPage(parts) {
+    return `<!doctype html>
+<html lang="${escapeHtml(parts.lang)}">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${CSP}">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>${escapeHtml(parts.title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header><h1 id="h"></h1><div class="sum" id="sum"></div><div class="mut" id="meta"></div>
+<div class="bar"><input id="q" type="search" autocomplete="off"><span class="mut" id="cnt"></span>
+<select id="jump"></select><button id="zo"></button><button id="zi"></button><button id="zf"></button>
+<button id="ea"></button><button id="ca"></button><span id="lg"></span></div>
+<div class="mut" id="note"></div></header>
+<div id="sc"><div id="ru"><div class="lc"></div><div id="tk"></div></div><div id="bd"></div></div>
+<section id="dt"></section>
+<footer id="ft"></footer>
+<script type="application/json" id="data">${parts.json}</script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}

package/dist/trace/html.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ *
+ * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
+ * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，
+ * 不拼 HTML。
+ *
+ * 这里把 `Trace` 摊成「行」（全部展开的扁平树：深度、父行、标签、耗时 / token / 缓存列、瀑布分段、详情键值、
+ * 预览），页面只做折叠、虚拟滚动、搜索、缩放与详情。
+ *
+ * - **双重脱敏**：整棵轨迹先 `redactValue`；正文经「先 redactValue 再读」的条目查找表取（标签里的提示预览、
+ *   工具参数摘要、详情预览都来自脱敏后的条目），预览自身再 `redactSecrets`（`preview.ts`）；序列化时
+ *   `<`、`>`、`&`、U+2028 / U+2029 全部转成 `\uXXXX`，数据里不可能出现 `</script>` 或 `<!--`。
+ * - `content: false`（`--no-content`）：不读条目，标签只剩结构，详情去掉错误 / 原因两行，没有预览。
+ * - `children: false`：子会话的结构照样嵌（行与数字），预览只给本会话的节点。
+ * - 预览总预算（缺省 4 MB 字符）：从最后一行往前计，超出后更早的预览置空并标注。
+ * - 横轴：会话时间，回合之间超过 2 秒的空闲压缩成 2 秒（页面标注）；`axis` 给出原始 → 轴上的折点，
+ *   刻度按原始时间标注。
+ * - 确定性：不读时钟；生成时间与版本由调用方传入，写进页脚。
+ */
+import { type TraceEntryLookup } from "./detail.js";
+import type { Trace } from "./types.js";
+/** 预览总预算（字符）。 */
+export declare const PREVIEW_BUDGET: number;
+/** 回合之间的空闲在轴上最多占这么长（ms）。 */
+export declare const IDLE_CAP_MS = 2000;
+export interface TraceHtmlOptions {
+    /** 是否带正文（标签里的提示 / 参数摘要、详情预览）。 */
+    content: boolean;
+    /** 是否内嵌子会话节点的预览。 */
+    children: boolean;
+    /** 生成时间（epoch ms），写页脚。 */
+    generatedAt: number;
+    /** 正文来源（含已加载子会话的条目）；`content` 为 false 时不用。 */
+    lookup?: TraceEntryLookup;
+    /** 写页脚的 ama 版本。 */
+    version: string;
+    /** 测试用：覆盖预览总预算。 */
+    previewBudget?: number;
+}
+/** 瀑布分段：`[轴上起点, 轴上终点, 类别]`；起点 = 终点表示进行中的起点标记。 */
+type Seg = [number, number, SegClass];
+type SegClass = "turn" | "ttft" | "dec" | "tool" | "agent" | "wait" | "oth" | "run";
+/** 页面里的一行。键名短，数据量大时省体积。 */
+export interface HtmlRow {
+    /** 深度。 */
+    d: number;
+    /** 父行下标（-1 = 顶层）。 */
+    p: number;
+    /** 节点种类。 */
+    k: string;
+    /** 状态（i18n 后）；完成时省略。 */
+    s?: string;
+    /** 状态码（样式用）。 */
+    sc?: string;
+    l: string;
+    /** 耗时 / token / 缓存列。 */
+    du?: string;
+    tk?: string;
+    ca?: string;
+    /** 缺省展开。 */
+    e?: 1;
+    /** 回合序号（顶层回合行，跳转用）。 */
+    t?: number;
+    g?: Seg[];
+    /** 详情键值。 */
+    kv: [string, string][];
+    /** 预览（标题 → 正文）。 */
+    pv?: [string, string][];
+    /** 预览因预算被省略。 */
+    pd?: 1;
+    /** 在子会话里且没有 `--children`（预览未内嵌）。 */
+    pc?: 1;
+}
+export interface HtmlData {
+    lang: string;
+    title: string;
+    summary: string;
+    meta: string;
+    footer: string;
+    /** 原始时间 → 轴上时间的折点（相对会话开始，ms）。 */
+    axis: [number, number][];
+    /** 轴总长（ms）。 */
+    span: number;
+    content: boolean;
+    rows: HtmlRow[];
+    i18n: Record<string, string>;
+}
+/** 正文查找表：条目先整条 `redactValue` 再给 describe / preview 用。 */
+export declare function redactedLookup(lookup: TraceEntryLookup): TraceEntryLookup;
+/** 原始时间 → 轴：合并回合时间窗，窗口之间的空闲压到 `IDLE_CAP_MS`。 */
+export declare function axisPoints(trace: Trace): [number, number][];
+/** 按折点映射（折点之外按 1:1 外推）。 */
+export declare function mapTime(points: readonly [number, number][], raw: number): number;
+/** 轨迹 → 页面数据（已脱敏；纯函数）。 */
+export declare function traceHtmlData(source: Trace, opts: TraceHtmlOptions): HtmlData;
+/**
+ * 嵌进 `<script type="application/json">` 的 JSON：`<`、`>`、`&` 与 U+2028 / U+2029 转成 `\uXXXX`。
+ * 结果仍是合法 JSON（`JSON.parse` 还原原值），且不含 `</script>`、`<!--` 等能截断或改变脚本块的序列。
+ */
+export declare function scriptSafeJson(value: unknown): string;
+/** 渲染整页 HTML。 */
+export declare function renderTraceHtml(trace: Trace, opts: TraceHtmlOptions): string;
+export {};

package/dist/trace/html.js

@@ -0,0 +1,292 @@
+/**
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ *
+ * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
+ * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，
+ * 不拼 HTML。
+ *
+ * 这里把 `Trace` 摊成「行」（全部展开的扁平树：深度、父行、标签、耗时 / token / 缓存列、瀑布分段、详情键值、
+ * 预览），页面只做折叠、虚拟滚动、搜索、缩放与详情。
+ *
+ * - **双重脱敏**：整棵轨迹先 `redactValue`；正文经「先 redactValue 再读」的条目查找表取（标签里的提示预览、
+ *   工具参数摘要、详情预览都来自脱敏后的条目），预览自身再 `redactSecrets`（`preview.ts`）；序列化时
+ *   `<`、`>`、`&`、U+2028 / U+2029 全部转成 `\uXXXX`，数据里不可能出现 `</script>` 或 `<!--`。
+ * - `content: false`（`--no-content`）：不读条目，标签只剩结构，详情去掉错误 / 原因两行，没有预览。
+ * - `children: false`：子会话的结构照样嵌（行与数字），预览只给本会话的节点。
+ * - 预览总预算（缺省 4 MB 字符）：从最后一行往前计，超出后更早的预览置空并标注。
+ * - 横轴：会话时间，回合之间超过 2 秒的空闲压缩成 2 秒（页面标注）；`axis` 给出原始 → 轴上的折点，
+ *   刻度按原始时间标注。
+ * - 确定性：不读时钟；生成时间与版本由调用方传入，写进页脚。
+ */
+import { getLocale, msg } from "../i18n/index.js";
+import { formatUsd } from "../modes/session-report.js";
+import { redactSecrets, redactValue } from "../session/redact.js";
+import { plainTheme } from "../tui/theme.js";
+import { describeNode, summaryRows } from "./detail.js";
+import { defaultExpanded, flattenTrace, turnSpan } from "./flatten.js";
+import { cacheText, durationText, rowLabel, summaryText, tokensText } from "./format.js";
+import { renderPage } from "./html-template.js";
+import { previewOf, previewSize } from "./preview.js";
+/** 预览总预算（字符）。 */
+export const PREVIEW_BUDGET = 4 * 1024 * 1024;
+/** 回合之间的空闲在轴上最多占这么长（ms）。 */
+export const IDLE_CAP_MS = 2000;
+/** 全部展开（任何 key 都展开）。 */
+const EXPAND_ALL = {
+    get: () => true,
+};
+/** 正文查找表：条目先整条 `redactValue` 再给 describe / preview 用。 */
+export function redactedLookup(lookup) {
+    const cache = new Map();
+    return {
+        ...(lookup.cwd !== undefined ? { cwd: lookup.cwd } : {}),
+        entry(id) {
+            if (!cache.has(id)) {
+                const raw = lookup.entry(id);
+                cache.set(id, raw === undefined ? undefined : redactValue(raw));
+            }
+            return cache.get(id);
+        },
+    };
+}
+/** 原始时间 → 轴：合并回合时间窗，窗口之间的空闲压到 `IDLE_CAP_MS`。 */
+export function axisPoints(trace) {
+    const t0 = trace.startedAt;
+    const windows = [];
+    for (const turn of trace.turns) {
+        const span = turnSpan(turn);
+        if (span !== undefined)
+            windows.push([span.start - t0, span.end - t0]);
+    }
+    for (const aux of trace.aux)
+        if (aux.startedAt !== undefined)
+            windows.push([aux.startedAt - t0, (aux.endedAt ?? aux.startedAt) - t0]);
+    windows.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const points = [[0, 0]];
+    let raw = 0;
+    let mapped = 0;
+    for (const [start, end] of windows) {
+        if (end <= raw)
+            continue;
+        const from = Math.max(start, raw);
+        if (from > raw) {
+            mapped += Math.min(from - raw, IDLE_CAP_MS);
+            raw = from;
+            points.push([raw, mapped]);
+        }
+        mapped += end - raw;
+        raw = end;
+        points.push([raw, mapped]);
+    }
+    return points;
+}
+/** 按折点映射（折点之外按 1:1 外推）。 */
+export function mapTime(points, raw) {
+    let prev = points[0] ?? [0, 0];
+    for (const point of points) {
+        if (raw <= point[0]) {
+            const [r0, m0] = prev;
+            const [r1, m1] = point;
+            return r1 === r0 ? m1 : m0 + ((raw - r0) * (m1 - m0)) / (r1 - r0);
+        }
+        prev = point;
+    }
+    return prev[1] + (raw - prev[0]);
+}
+function segments(row, at) {
+    const node = row.node;
+    if (node.kind === "more" || node.kind === "aux_group")
+        return [];
+    const out = [];
+    const running = node.status === "running" && node.endedAt === undefined;
+    const bar = (from, to, cls) => {
+        if (from === undefined)
+            return;
+        if (to === undefined) {
+            if (running)
+                out.push([at(from), at(from), "run"]);
+            return;
+        }
+        out.push([at(from), at(Math.max(from, to)), cls]);
+    };
+    switch (node.kind) {
+        case "turn":
+            if (node.startedAt !== undefined) {
+                const span = turnSpan(node);
+                bar(node.startedAt, running ? undefined : span?.end, "turn");
+            }
+            break;
+        case "step": {
+            const start = node.requestAt ?? node.startedAt;
+            if (node.firstTokenAt !== undefined) {
+                bar(start, node.firstTokenAt, "ttft");
+                bar(node.firstTokenAt, node.doneAt, "dec");
+            }
+            else
+                bar(start, node.doneAt ?? node.endedAt, "dec");
+            break;
+        }
+        case "retry_wait":
+            bar(node.startedAt, node.startedAt === undefined ? undefined : node.startedAt + node.delayMs, "wait");
+            break;
+        case "compaction":
+        case "aux":
+            bar(node.startedAt, node.endedAt, "oth");
+            break;
+        case "subagent":
+            bar(node.startedAt, node.endedAt, "agent");
+            break;
+        default:
+            bar(node.startedAt, node.endedAt, "tool");
+    }
+    return out;
+}
+const PREVIEW_ORDER = ["input", "output", "args", "result"];
+function previewPairs(p) {
+    const d = msg().trace.detail;
+    return PREVIEW_ORDER.flatMap((key) => {
+        const text = p[key];
+        return text === undefined ? [] : [[d[key], text]];
+    });
+}
+/** 轨迹 → 页面数据（已脱敏；纯函数）。 */
+export function traceHtmlData(source, opts) {
+    const m = msg().trace;
+    const theme = plainTheme();
+    const trace = redactValue(source);
+    const lookup = opts.content && opts.lookup !== undefined ? redactedLookup(opts.lookup) : undefined;
+    const describe = lookup === undefined
+        ? undefined
+        : (node) => describeNode(node, lookup);
+    const t0 = trace.startedAt;
+    const axis = axisPoints(trace);
+    const at = (t) => Math.round(mapTime(axis, t - t0));
+    const dropKeys = new Set([m.detail.error, m.detail.reason]);
+    const flat = flattenTrace(trace, { expanded: EXPAND_ALL });
+    const rows = [];
+    const parents = [];
+    /** 各深度上的行是否在子 Agent 的子树里（不含子 Agent 行本身）。 */
+    const under = [];
+    let span = axis.at(-1)?.[1] ?? 0;
+    flat.forEach((row, i) => {
+        parents.length = row.depth;
+        const node = row.node;
+        const out = {
+            d: row.depth,
+            p: row.depth === 0 ? -1 : (parents[row.depth - 1] ?? -1),
+            k: node.kind,
+            l: redactSecrets(rowLabel(row, describe === undefined ? {} : { describe })),
+            kv: [],
+        };
+        const parent = out.p < 0 ? undefined : rows[out.p];
+        const inChild = row.depth > 0 && ((under[row.depth - 1] ?? false) || parent?.k === "subagent");
+        under[row.depth] = inChild;
+        parents[row.depth] = i;
+        if (node.kind !== "more" && node.kind !== "aux_group") {
+            if (node.status !== "ok") {
+                out.s = m.status[node.status];
+                out.sc = node.status;
+            }
+            const du = durationText(node, theme);
+            if (du !== "")
+                out.du = du;
+            const tk = tokensText(node, theme);
+            if (tk !== "")
+                out.tk = tk;
+            const ca = cacheText(node);
+            if (ca !== "")
+                out.ca = ca;
+            out.kv = summaryRows(node, theme, t0)
+                .filter(([label]) => opts.content || !dropKeys.has(label))
+                .map(([label, value]) => [label, redactSecrets(value)]);
+            const g = segments(row, at);
+            if (g.length > 0) {
+                out.g = g;
+                for (const seg of g)
+                    span = Math.max(span, seg[1]);
+            }
+            if (lookup !== undefined) {
+                if (inChild && !opts.children)
+                    out.pc = 1;
+                else {
+                    const p = previewOf(node, lookup);
+                    if (p !== undefined && previewSize(p) > 0)
+                        out.pv = previewPairs(p);
+                }
+            }
+        }
+        if (row.expandable && defaultExpanded(node))
+            out.e = 1;
+        if (node.kind === "turn" && row.depth === 0)
+            out.t = row.turn;
+        rows.push(out);
+    });
+    // 预览总预算：从后往前
+    let budget = opts.previewBudget ?? PREVIEW_BUDGET;
+    for (let i = rows.length - 1; i >= 0; i--) {
+        const row = rows[i];
+        if (row.pv === undefined)
+            continue;
+        const size = row.pv.reduce((n, [, text]) => n + text.length, 0);
+        if (size <= budget)
+            budget -= size;
+        else {
+            budget = 0;
+            delete row.pv;
+            row.pd = 1;
+        }
+    }
+    const h = m.html;
+    const generated = new Date(opts.generatedAt).toISOString();
+    const cost = trace.totals.cost !== undefined ? ` · ${formatUsd(trace.totals.cost)}` : "";
+    const started = new Date(t0).toISOString();
+    return {
+        lang: getLocale() === "zh" ? "zh-CN" : "en",
+        title: h.docTitle(trace.sessionId),
+        summary: `${summaryText(trace, theme)}${cost}`,
+        meta: `${trace.cwd} · ${started}${trace.partial ? ` · ${m.status.running}` : ""}`,
+        footer: h.footer(opts.version, generated),
+        axis,
+        span: Math.max(1, span),
+        content: opts.content,
+        rows,
+        i18n: {
+            search: h.search,
+            noMatch: h.noMatch,
+            jump: h.jump,
+            zoomIn: h.zoomIn,
+            zoomOut: h.zoomOut,
+            zoomFit: h.zoomFit,
+            expandAll: h.expandAll,
+            collapseAll: h.collapseAll,
+            ttft: h.legendTtft,
+            dec: h.legendDecode,
+            tool: h.legendTool,
+            agent: h.legendAgent,
+            wait: h.legendWait,
+            oth: h.legendOther,
+            axisNote: h.axisNote,
+            detailEmpty: h.detailEmpty,
+            noContent: h.noContent,
+            previewDropped: h.previewDropped,
+            childPreviewOff: h.childPreviewOff,
+            keys: h.keys,
+            empty: m.empty,
+        },
+    };
+}
+/**
+ * 嵌进 `<script type="application/json">` 的 JSON：`<`、`>`、`&` 与 U+2028 / U+2029 转成 `\uXXXX`。
+ * 结果仍是合法 JSON（`JSON.parse` 还原原值），且不含 `</script>`、`<!--` 等能截断或改变脚本块的序列。
+ */
+export function scriptSafeJson(value) {
+    return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (c) => {
+        const code = c.charCodeAt(0).toString(16).padStart(4, "0");
+        return `\\u${code}`;
+    });
+}
+/** 渲染整页 HTML。 */
+export function renderTraceHtml(trace, opts) {
+    const data = traceHtmlData(trace, opts);
+    return renderPage({ lang: data.lang, title: data.title, json: scriptSafeJson(data) });
+}

package/dist/trace/preview.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 轨迹节点的正文预览（脱敏版）：HTML 导出与 RPC `get_trace{content:"preview"}` 共用。[W6-T2]
+ *
+ * 与 `detail.ts` 的 `nodePreviews`（只给本机 TUI 用、未脱敏）同一截断口径：参数 JSON 500 字符、提示 / 输出 /
+ * 结果 2000 字符。顺序很重要：**先脱敏整段原文，再截断**——反过来截断会把密钥截成不再匹配形态的残片。
+ * 参数先 `redactValue`（键名像机密的值整段遮掉）再序列化，序列化后再过一遍 `redactSecrets`。
+ */
+import { type TraceEntryLookup } from "./detail.js";
+import type { TraceNode } from "./flatten.js";
+/** 一个节点的预览；每段都已脱敏与截断（被截断的以 `…` 结尾）。 */
+export interface TracePreview {
+    /** 回合：用户提示。 */
+    input?: string;
+    /** 请求：助手文字。 */
+    output?: string;
+    /** 工具：参数 JSON。 */
+    args?: string;
+    /** 工具：结果文本。 */
+    result?: string;
+}
+/** 节点 → 预览；没有正文返回 undefined。 */
+export declare function previewOf(node: TraceNode, lookup: TraceEntryLookup): TracePreview | undefined;
+/** 预览的字符数（总预算用）。 */
+export declare function previewSize(p: TracePreview): number;
+/** 预览表的 key：`<kind>:<id>`（同一轨迹内唯一；子轨迹的节点 id 来自子会话条目）。 */
+export declare function previewKey(node: {
+    kind: string;
+    id: string;
+}): string;

package/dist/trace/preview.js

@@ -0,0 +1,59 @@
+/**
+ * 轨迹节点的正文预览（脱敏版）：HTML 导出与 RPC `get_trace{content:"preview"}` 共用。[W6-T2]
+ *
+ * 与 `detail.ts` 的 `nodePreviews`（只给本机 TUI 用、未脱敏）同一截断口径：参数 JSON 500 字符、提示 / 输出 /
+ * 结果 2000 字符。顺序很重要：**先脱敏整段原文，再截断**——反过来截断会把密钥截成不再匹配形态的残片。
+ * 参数先 `redactValue`（键名像机密的值整段遮掉）再序列化，序列化后再过一遍 `redactSecrets`。
+ */
+import { contentText } from "../session/reuse.js";
+import { redactSecrets, redactValue } from "../session/redact.js";
+import { ARGS_PREVIEW_MAX, RESULT_PREVIEW_MAX } from "./detail.js";
+function clip(text, max) {
+    const clean = redactSecrets(text);
+    return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+function messageOf(lookup, id) {
+    const entry = id === undefined ? undefined : lookup.entry(id);
+    return entry?.type === "message" ? entry.message : undefined;
+}
+/** 节点 → 预览；没有正文返回 undefined。 */
+export function previewOf(node, lookup) {
+    const out = {};
+    if (node.kind === "turn") {
+        const m = messageOf(lookup, node.id);
+        if (m?.role === "user")
+            out.input = clip(contentText(m.content), RESULT_PREVIEW_MAX);
+    }
+    else if (node.kind === "step") {
+        const m = messageOf(lookup, node.id);
+        if (m?.role === "assistant") {
+            const text = m.content
+                .flatMap((b) => (b.type === "text" && b.text.trim() !== "" ? [b.text] : []))
+                .join("\n");
+            if (text !== "")
+                out.output = clip(text, RESULT_PREVIEW_MAX);
+        }
+    }
+    else if (node.kind === "tool") {
+        const m = messageOf(lookup, node.entryIds[0]);
+        if (m?.role === "assistant")
+            for (const block of m.content)
+                if (block.type === "toolCall" && block.id === node.id)
+                    out.args = clip(JSON.stringify(redactValue(block.arguments), null, 2), ARGS_PREVIEW_MAX);
+        const r = messageOf(lookup, node.entryIds[1]);
+        if (r?.role === "toolResult")
+            out.result = clip(contentText(r.content), RESULT_PREVIEW_MAX);
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/** 预览的字符数（总预算用）。 */
+export function previewSize(p) {
+    return ((p.input?.length ?? 0) +
+        (p.output?.length ?? 0) +
+        (p.args?.length ?? 0) +
+        (p.result?.length ?? 0));
+}
+/** 预览表的 key：`<kind>:<id>`（同一轨迹内唯一；子轨迹的节点 id 来自子会话条目）。 */
+export function previewKey(node) {
+    return `${node.kind}:${node.id}`;
+}

package/dist/trace/query-session.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ *
+ * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
+ * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。
+ */
+import type { AgentSession } from "../agent/types.js";
+import type { RpcGetTraceParams } from "../rpc.js";
+import { type TraceQueryResult } from "./query.js";
+import type { Trace, TraceOptions } from "./types.js";
+/** RPC `get_trace`。参数不合法抛 `invalid_arguments`，任务不存在抛 `task_not_found`。 */
+export declare function sessionTrace(session: AgentSession, params: RpcGetTraceParams): TraceQueryResult;
+/** SDK `session.trace(options?)`：缺省全部回合；`turnLimit` 取尾部若干回合；`taskId` 取子轨迹。 */
+export declare function sdkSessionTrace(session: AgentSession, options?: TraceOptions): Trace;