@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/dist/ui/chat-thread.js

@@ -8,6 +8,7 @@
 // Unrelated updates (a new message, another message's tick) stop nothing (#1306 §6.2, #1408 §4).
 import "./chat-render.js";
 import "./preview.js";
+import { loadHtmlAttachment } from "./html-attachment.js";
 
 const R = () => globalThis.AgendChatRender;
 const P = () => globalThis.AgendPreview;
@@ -19,12 +20,19 @@ export const msgKey = (x) => `${x.boot}-${x.id}`;
 
 /**
  * Bind a renderer to `list` (the thread element) inside `scroller`. opts: { t, tf, isUser(x), onJump({show, unseen}),
- * setPreviewOptIn(on), copyText(text) → Promise<boolean>, download(code) }.
+ * setPreviewOptIn(on), copyText(text) → Promise<boolean>, download(code), panel? }. panel (#1481): { shown() → the card
+ * key the side panel shows, or null; open(spec, { run }) } — without it a card has no "Open in panel".
  */
 export function createThread(list, scroller, opts) {
   const nodes = new Map();          // key → { html, node }
   let msgs = [];
   let unseen = 0;
+  // The reader is at the newest message. While pinned, content that grows after it was drawn — an image loading, a
+  // preview card, the composer growing — keeps the view at the bottom (#1269); a reader who scrolled up is never moved.
+  // Only a move UP unpins: the browser's own scroll anchoring also fires scroll events when content grows (the view
+  // moves down or stays), and those must not count as the reader leaving the bottom. Reaching the bottom pins again.
+  let pinned = true;
+  let lastTop = 0;
   const cardRefresh = new WeakMap(); // card node → re-read availability (weak: a card that left takes its source with it)
   const tr = opts.t, trf = opts.tf;
   const stopIn = (node) => (P() ? P().stopIn(node) : []);
@@ -37,7 +45,23 @@ export function createThread(list, scroller, opts) {
     // renderMarkdown escapes the whole text before it adds any tag of its own (chat-render.js).
     const ticks = u && x.delivery ? R().deliveryHtml(x.delivery, TICKS()) : "";
     const tools = u ? "" : `<div class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
-    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments)}</div>${tools}</div>`;
+    const buttons = x.role === "agent" ? replyButtonsHtml(x.buttons) : "";
+    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments, x.role === "agent" ? { htmlCards: true } : undefined)}${buttons}</div>${tools}</div>`;
+  }
+  /**
+   * #1266: an agent reply's buttons. Labels are text (escaped, never Markdown); the click names the set and the index,
+   * nothing else. Ended (chosen / expired) or a click in flight: every button off; the chosen one marked, and who.
+   */
+  function replyButtonsHtml(b) {
+    if (!b || typeof b.id !== "string" || !Array.isArray(b.labels) || !b.labels.length) return "";
+    const busy = !!(opts.replyButtonBusy && opts.replyButtonBusy(b.id));
+    const off = b.state !== "open" || busy;
+    const items = b.labels.map((label, i) => {
+      const chosen = b.state === "chosen" && b.chosen === i;
+      return `<button type="button" class="btn btn-sm rb-btn${chosen ? " chosen" : ""}" data-act="replyButton" data-arg="${escAttr(`${b.id}:${i}`)}"${off ? " disabled" : ""}>${escAttr(chosen ? `✓ ${label}` : label)}</button>`;
+    }).join("");
+    const note = b.state === "chosen" ? trf("chat.rbChosen", b.by || "") : b.state === "expired" ? tr("chat.rbExpired") : "";
+    return `<div class="rb-row" role="group" aria-label="${escAttr(tr("chat.rbGroup"))}">${items}${note ? `<span class="rb-note">${escAttr(note)}</span>` : ""}</div>`;
   }
   function msgNode(html, x, stoppedKeys) {
     const tpl = list.ownerDocument.createElement("template");
@@ -69,68 +93,121 @@ export function createThread(list, scroller, opts) {
     }
   }
 
-  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block. Building
-  // a card makes no frame; Preview does (AgendPreview.start → mountPreview).
+  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block, and each
+  // .html/.htm file it attached gets one under its files (§6.1, Q4). Building a card makes no frame and fetches
+  // nothing; Preview does (AgendPreview.start → mountPreview), after reading an attachment's HTML on that click.
   function decorateHtmlCards(node, x, stoppedKeys) {
     const doc = list.ownerDocument;
     const fences = R().htmlFences(x.text);
     for (const ph of node.querySelectorAll(".html-card[data-card]")) {
       const n = Number(ph.dataset.card), fence = fences[n];
       if (!fence) continue;
-      const key = `${msgKey(x)}:f${n}`;
       ph.textContent = "";
       if (ph.classList.contains("truncated") || !fence.terminated) {
         const note = doc.createElement("div"); note.className = "pv-note"; note.textContent = tr("chat.pvTruncated"); ph.append(note);
         continue;
       }
-      const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
-      const head = el("div", "pv-head");
-      const label = el("span", "pv-label", tr("chat.pvHtml"));
-      const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
-      const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
-      const dl = el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload")); dl.type = "button";
-      const menu = el("details", "pv-menu");
-      const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
-      const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
-      const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
-      menu.append(sum, optB, neverB);
-      head.append(label, run, stopB, dl, menu);
-      const note = el("div", "pv-note");
-      const banner = el("div", "pv-banner", P().BANNER); banner.hidden = true;
-      const holder = el("div", "pv-holder");
-      ph.append(head, note, banner, holder);
-      let state = "idle";
-      const refresh = (reason) => {
-        const a = P().availability();
-        const going = state === "starting" || state === "running";
-        run.hidden = !a.ok || going;
-        stopB.hidden = !going;
-        banner.hidden = !going;
-        note.textContent = reason != null ? reason : going ? (state === "starting" ? tr("chat.pvStarting") : "") : a.ok ? "" : a.reason;
-        optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
-        neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
-      };
-      const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
-      run.onclick = () => P().start(key, holder, fence.code, ui);
-      stopB.onclick = () => P().stop(key, "stopped", "");
-      dl.onclick = () => opts.download(fence.code);
-      optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
-      neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
-      cardRefresh.set(ph, refresh);
-      refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+      buildCard(ph, x, `${msgKey(x)}:f${n}`, { n, code: fence.code }, stoppedKeys);
+    }
+    const atts = Array.isArray(x.attachments) ? x.attachments : [];
+    for (const ph of node.querySelectorAll(".html-card[data-att]")) {
+      const att = atts.find(a => a && a.id === ph.dataset.att);
+      if (!att || !R().isHtmlAttachment(att)) continue;
+      ph.textContent = "";
+      buildCard(ph, x, `${msgKey(x)}:a${att.id}`, { att: { id: att.id, name: att.name, size: att.size } }, stoppedKeys);
     }
   }
+  /** Why an attachment's HTML could not be read, for the card's note. */
+  const attReason = (reason) => tr(reason === "over" ? "chat.pvAttOver" : reason === "gone" ? "chat.pvAttGone" : "chat.pvAttFailed");
+  /** One card: `source` is { n, code } for a fence or { att } for an attachment (its HTML read on the first click). */
+  function buildCard(ph, x, key, source, stoppedKeys) {
+    const doc = list.ownerDocument;
+    const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+    const att = source.att || null;
+    let code = att ? null : source.code;
+    const head = el("div", "pv-head");
+    const label = el("span", "pv-label", att ? `${tr("chat.pvHtml")} · ${att.name}` : tr("chat.pvHtml"));
+    const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
+    const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
+    // An attachment already has its download link (the file itself) right above the card.
+    const dl = att ? null : el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload"));
+    if (dl) dl.type = "button";
+    const panel = opts.panel || null;
+    const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
+    if (toPanel) toPanel.type = "button";
+    const menu = el("details", "pv-menu");
+    const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
+    const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
+    const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
+    menu.append(sum, optB, neverB);
+    head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), ...(dl ? [dl] : []), menu);
+    const note = el("div", "pv-note");
+    const banner = el("div", "pv-banner", P().BANNER); banner.hidden = true;
+    const holder = el("div", "pv-holder");
+    ph.append(head, note, banner, holder);
+    let state = "idle";
+    // Reading an attachment: one read per card at a time (a second click while it reads does nothing), and a read
+    // whose card was stopped, replaced or left meanwhile is dropped (`reading` moved on, or the card left the page).
+    let reading = 0, reads = 0;
+    const refresh = (reason) => {
+      const a = P().availability();
+      const going = state === "starting" || state === "running";
+      const inPanel = !!panel && panel.shown() === key;   // #1481: the panel shows this block; the card points there
+      run.hidden = !a.ok || going || inPanel || !!reading;
+      if (toPanel) toPanel.hidden = inPanel || !!reading;
+      stopB.hidden = !going && !reading;
+      banner.hidden = !going;
+      note.textContent = reason != null ? reason : reading ? tr("chat.pvLoading") : going ? (state === "starting" ? tr("chat.pvStarting") : "") : inPanel ? tr("chat.pvInPanel") : a.ok ? "" : a.reason;
+      optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
+      neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
+    };
+    /** The HTML, then `then(code)`: at once for a fence or an attachment already read; otherwise read it first. */
+    const withCode = async (then) => {
+      if (code != null) { then(code); return; }
+      if (reading) return;
+      const mine = reading = ++reads;
+      refresh();
+      const r = await loadHtmlAttachment(att);
+      if (reading !== mine || !ph.isConnected) return;
+      reading = 0;
+      if (!r.ok) { refresh(attReason(r.reason)); return; }
+      code = r.code;
+      refresh();
+      then(code);
+    };
+    const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
+    // Nothing is read for Preview on a device that does not allow previews: the button is not even shown there.
+    run.onclick = () => { if (P().availability().ok) withCode((c) => P().start(key, holder, c, ui)); };
+    stopB.onclick = () => { if (reading) { reading = 0; refresh(); } else P().stop(key, "stopped", ""); };
+    // A running preview moves: it stops here and starts in the panel (the click that ran it). An idle one opens the
+    // panel with its own Preview to click.
+    if (toPanel) toPanel.onclick = () => {
+      const moving = P().running(key);
+      if (moving) P().stop(key, "stopped", "");
+      withCode((c) => panel.open({ key, instance: x.instance, msgKey: msgKey(x), ...(att ? { att } : { n: source.n }), code: c, sender: x.sender, ts: x.ts }, { run: moving }));
+    };
+    if (dl) dl.onclick = () => opts.download(code);
+    optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
+    neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
+    cardRefresh.set(ph, refresh);
+    refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+  }
   /** Re-read this device's preview choice on every card in this thread. */
   function refreshCards() {
-    for (const node of list.querySelectorAll(".html-card[data-card]")) { const f = cardRefresh.get(node); if (f) f(); }
+    for (const node of list.querySelectorAll(".html-card[data-card], .html-card[data-att]")) { const f = cardRefresh.get(node); if (f) f(); }
   }
 
   const nearBottom = () => R().isNearBottom(scroller.scrollTop, scroller.clientHeight, scroller.scrollHeight);
   function reportJump() { opts.onJump({ show: !nearBottom(), unseen }); }
+  function toBottom() { scroller.scrollTop = scroller.scrollHeight; pinned = true; lastTop = scroller.scrollTop; }
+  // Sizes change without a scroll event (layout after the render): follow them while pinned.
+  const resized = () => { if (pinned && !nearBottom()) toBottom(); reportJump(); };
+  const ro = typeof ResizeObserver === "function" ? new ResizeObserver(resized) : null;
+  if (ro) { ro.observe(list); ro.observe(scroller); }
 
   /** Draw `next` (this instance's messages). `restore`: the scroll position to return to (null = the bottom). */
   function render(next, renderOpts = {}) {
-    const stick = nearBottom();
+    const stick = pinned || nearBottom();
     msgs = next || [];
     if (!msgs.length) {
       for (const v of nodes.values()) stopIn(v.node);
@@ -159,19 +236,31 @@ export function createThread(list, scroller, opts) {
     }
     if ("restore" in renderOpts) {
       unseen = 0;
-      scroller.scrollTop = renderOpts.restore == null ? scroller.scrollHeight : renderOpts.restore;
-    } else if (stick) scroller.scrollTop = scroller.scrollHeight;
+      if (renderOpts.restore == null) toBottom();
+      else { scroller.scrollTop = renderOpts.restore; pinned = nearBottom(); lastTop = scroller.scrollTop; }
+    } else if (stick) toBottom();
     else unseen += added;
     reportJump();
   }
 
   function onScroll() {
-    const bottom = nearBottom();
+    const bottom = nearBottom(), top = scroller.scrollTop;
+    if (bottom) pinned = true;
+    else if (top < lastTop) pinned = false;
+    lastTop = top;
     if (bottom) unseen = 0;
     reportJump();
     return bottom ? null : scroller.scrollTop;
   }
-  function jumpLatest() { scroller.scrollTop = scroller.scrollHeight; unseen = 0; reportJump(); }
+  function jumpLatest() { toBottom(); unseen = 0; reportJump(); }
+  /** Show one message (the panel's "from …" link, #1481): scrolled into view and briefly marked. */
+  function reveal(key) {
+    const have = nodes.get(key); if (!have) return false;
+    if (typeof have.node.scrollIntoView === "function") have.node.scrollIntoView({ block: "center" });
+    have.node.classList.add("flash");
+    setTimeout(() => { have.node.classList.remove("flash"); }, 1600);
+    return true;
+  }
 
   async function copyFrom(button, text) {
     const ok = await opts.copyText(text);
@@ -197,13 +286,18 @@ export function createThread(list, scroller, opts) {
       const folded = box.classList.toggle("folded");
       el.textContent = folded ? trf("chat.showAll", el.dataset.lines) : tr("chat.showLess");
     } else if (act === "toggleWrap") opts.toggleWrap();
+    else if (act === "replyButton") {
+      const m = /^([0-9a-f]{32}):(\d{1,2})$/.exec(el.dataset.arg || "");
+      if (m && opts.clickReplyButton) opts.clickReplyButton(m[1], Number(m[2]));
+    }
   }
 
   /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */
   function dispose() {
+    if (ro) ro.disconnect();
     if (P()) P().stopAll("leave");
     nodes.clear();
   }
 
-  return { render, onScroll, onClick, jumpLatest, refreshCards, dispose, nodes, get unseen() { return unseen; } };
+  return { render, onScroll, onClick, jumpLatest, reveal, refreshCards, dispose, nodes, get unseen() { return unseen; } };
 }

package/dist/ui/first-run.js

@@ -0,0 +1,64 @@
+// #1519 P7 (docs/design/ux-onboarding-walkthrough.md §5.1): the first-run card. A fleet with no chat connection (a
+// web-only fleet) opens Chat and Settings with it: "Connect a chat app" opens the setup wizard (in Settings, where its
+// progress is shown), "Use the web only" hides it in this browser. It stays until a connection exists or it is dismissed.
+import { html } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+import { appStore, createStore, useStore } from "/assets/app-store.js";
+import { navigate } from "/assets/app-nav.js";
+import { settingsPath } from "/assets/app-route.js";
+import { Icon } from "/assets/ui-icons.js";
+
+register("firstRun", {
+  en: {
+    title: "Connect a chat app",
+    body: "AgEnD works in this browser on its own. To talk to your agents from Telegram or Discord too, add a bot: the setup wizard checks its token and connects it to an agent.",
+    connect: "Connect a chat app", webOnly: "Use the web only",
+  },
+  "zh-TW": {
+    title: "連接聊天應用程式",
+    body: "AgEnD 只用這個瀏覽器也能運作。想同時從 Telegram 或 Discord 跟你的 agent 對話，就加一個機器人：設定精靈會檢查它的 token，並把它接到一個 agent。",
+    connect: "連接聊天應用程式", webOnly: "只用網頁",
+  },
+});
+
+export const DISMISS_KEY = "agend_firstrun_dismissed";
+function readDismissed() { try { return localStorage.getItem(DISMISS_KEY) === "1"; } catch { return false; } }
+// `dismissed`: this page's own answer (it holds even when the browser keeps no storage); a stored one is read each time.
+const local = createStore({ dismissed: false, wizard: false });
+
+export function dismissFirstRun() {
+  try { localStorage.setItem(DISMISS_KEY, "1"); } catch { /* this page only */ }
+  local.set({ dismissed: true });
+}
+
+/** For the tests: a fresh page's state. */
+export function resetFirstRun() { local.set({ dismissed: false, wizard: false }); }
+
+/** Settings asks once, when it has its data: was it opened by "Connect a chat app" (open the wizard)? */
+export function takeWizardRequest() {
+  if (!local.get().wizard) return false;
+  local.set({ wizard: false });
+  return true;
+}
+
+/** Shown on a known web-only fleet (no connection) until dismissed. */
+export function useFirstRun() {
+  const app = useStore(appStore);
+  const { dismissed } = useStore(local);
+  return app.ready && app.connections === 0 && !dismissed && !readDismissed();
+}
+
+/** onConnect: Settings opens its wizard in place; elsewhere the card goes to Settings, which opens it. */
+export function FirstRunCard({ onConnect }) {
+  const shown = useFirstRun();
+  if (!shown) return null;
+  const connect = onConnect || (() => { local.set({ wizard: true }); navigate(settingsPath("bots")); });
+  return html`<section class="card first-run" aria-labelledby="first-run-title">
+    <h3 id="first-run-title"><${Icon} name="plug" size=${14} /> ${t("firstRun.title")}</h3>
+    <p>${t("firstRun.body")}</p>
+    <div class="dlg-inline-actions">
+      <button type="button" class="btn btn-primary" onClick=${connect}>${t("firstRun.connect")}</button>
+      <button type="button" class="btn btn-ghost" onClick=${dismissFirstRun}>${t("firstRun.webOnly")}</button>
+    </div>
+  </section>`;
+}

package/dist/ui/fleet-cache.js

@@ -0,0 +1,168 @@
+// #1468: Fleet → Cache (/ui/fleet/cache) — how often each instance's prompt cache expires between requests, what
+// that costs, and whether keeping it warm would pay off. Behind the session gate (/ui/js/), imported by the Fleet
+// panel. Read-only (Discord-first): it recommends, it changes nothing.
+//
+// One GET /ui/cache?window=… per opening or per choice of window (a person's navigation); no timer re-reads it
+// (#1374). While the server is still reading transcripts the page says so and offers Refresh.
+import { html } from "/assets/app-html.js";
+import { t, register } from "/assets/app-i18n.js";
+import { Empty } from "/assets/ui-states.js";
+import { Icon } from "/assets/ui-icons.js";
+
+register("cache", {
+  en: {
+    title: "Cache", w24h: "24 h", w7d: "7 days", w30d: "30 days", window: "Window",
+    fleetExpiry: "Expiry cost", fleetSaving: "Keep-warm would save", fleetRecommended: "Recommended", ofN: "{0} of {1}",
+    pricesNote: "List prices checked {0}.", quotaNote: "Subscriptions: Anthropic and OpenAI do not publish how cache reads weigh against a plan's quota, so savings are exact at list price and an estimate in quota terms.",
+    estimateNote: "Estimate: Codex does not record cache writes, so a write is taken as the request's uncached input.",
+    notPricedNote: "Some models are not in the price table; those instances are compared in input-price units.",
+    scanning: "Still reading transcripts — {0} left. Refresh to see more.", scanningFirst: "Reading transcripts for the first time — Refresh to see more.", refresh: "Refresh",
+    keepWarm: "Keep warm", leaveOff: "Leave off", estimate: "estimate", notPriced: "not priced",
+    requests: "Requests", pastTtl: "Past the TTL ({0})", expired: "Expired (rewrote)", rewritten: "Tokens rewritten",
+    expiryCost: "Expiry cost", share: "{0} of its cost", pings: "Keep-warm pings", pingsAfter: "{0} after its last request",
+    pingCost: "Ping cost", net: "Net with keep-warm", gaps: "Gaps between requests", ttlLine: "TTL {0}",
+    quiet: "Too little activity in this window to tell.",
+    neverExpired: "No gap outlasted the {0} cache.", survived: "{0} gaps outlasted the {1} TTL, but the cache was still there.",
+    onlyIdle: "No request ever came back to an expired cache: each session went quiet for good. Keep-warm would only send {0} pings nobody reads.",
+    saves: "Often idle past the {0} TTL and then used again: keep-warm would save {1} ({2} of the expiry cost).",
+    costsMore: "Keep-warm would send about {0} pings per expired request — it would cost {1} more than it saves.",
+    costsMoreUnits: "Keep-warm would send about {0} pings per expired request — it would cost more than it saves.",
+    unavailable: "Not available", creditBilled: "credit-billed; no cache data", unsupported: "no cache data from this CLI", noData: "no requests read yet",
+    shared: "shares its working directory with {0}; their transcripts cannot be told apart",
+    empty: "No instances", emptyHint: "Instances show here once the fleet has them.",
+    b0: "≤5m", b1: "≤30m", b2: "≤1h", b3: "≤2h", b4: "≤6h", b5: "≤24h", b6: ">24h", tokensUnit: "input-token equivalents",
+  },
+  "zh-TW": {
+    title: "快取", w24h: "24 小時", w7d: "7 天", w30d: "30 天", window: "期間",
+    fleetExpiry: "過期成本", fleetSaving: "保溫可省", fleetRecommended: "建議保溫", ofN: "{1} 個中的 {0} 個",
+    pricesNote: "牌價查證日期：{0}。", quotaNote: "訂閱方案：Anthropic 與 OpenAI 未公布快取讀取如何計入方案額度，因此節省金額以牌價計算為準，換算成額度則是估算。",
+    estimateNote: "估算：Codex 不記錄快取寫入，寫入量以該次請求未命中快取的輸入估算。",
+    notPricedNote: "有些模型不在價目表中，這些 instance 以「輸入價格單位」比較。",
+    scanning: "仍在讀取 transcript——還剩 {0}。重新整理可看到更多。", scanningFirst: "第一次讀取 transcript 中——重新整理可看到更多。", refresh: "重新整理",
+    keepWarm: "建議保溫", leaveOff: "不需保溫", estimate: "估算", notPriced: "未定價",
+    requests: "請求數", pastTtl: "超過 TTL（{0}）", expired: "已過期（重寫）", rewritten: "重寫的 token",
+    expiryCost: "過期成本", share: "占其成本 {0}", pings: "保溫 ping 次數", pingsAfter: "其中 {0} 次在最後一次請求之後",
+    pingCost: "ping 成本", net: "保溫後淨額", gaps: "請求間隔", ttlLine: "TTL {0}",
+    quiet: "這段期間活動太少，無法判斷。",
+    neverExpired: "沒有任何間隔超過 {0} 的快取時效。", survived: "有 {0} 個間隔超過 {1} TTL，但快取仍在。",
+    onlyIdle: "沒有任何請求在快取過期後回來使用：每個 session 閒置後就不再使用。保溫只會送出 {0} 次沒人讀的 ping。",
+    saves: "常閒置超過 {0} TTL 後又再使用：保溫可省 {1}（過期成本的 {2}）。",
+    costsMore: "每次過期約需送 {0} 次 ping——保溫的花費比省下的多 {1}。",
+    costsMoreUnits: "每次過期約需送 {0} 次 ping——保溫的花費比省下的多。",
+    unavailable: "不提供", creditBilled: "以 credit 計費，沒有快取資料", unsupported: "這個 CLI 沒有快取資料", noData: "尚未讀到任何請求",
+    shared: "與 {0} 共用工作目錄，無法分辨各自的 transcript",
+    empty: "沒有 instance", emptyHint: "fleet 有 instance 後會顯示在這裡。",
+    b0: "≤5分", b1: "≤30分", b2: "≤1時", b3: "≤2時", b4: "≤6時", b5: "≤24時", b6: ">24時", tokensUnit: "輸入 token 當量",
+  },
+});
+const tc = (k, ...v) => t(`cache.${k}`, ...v);
+
+export const CACHE_WINDOWS = ["24h", "7d", "30d"];
+const EDGES = [300, 1800, 3600, 7200, 21600, 86400];
+
+export function money(usd) {
+  if (!(usd > 0)) return "$0";
+  if (usd < 0.01) return "<$0.01";
+  return usd >= 100 ? `$${Math.round(usd).toLocaleString("en-US")}` : `$${usd.toFixed(2)}`;
+}
+export function tokens(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
+  return String(Math.round(n));
+}
+export function bytes(n) { return n >= 1e9 ? `${(n / 1e9).toFixed(1)} GB` : n >= 1e6 ? `${Math.round(n / 1e6)} MB` : `${Math.max(1, Math.round(n / 1e3))} KB`; }
+export function ttlText(sec) { return sec >= 3600 ? `${sec / 3600} h` : `${Math.round(sec / 60)} min`; }
+const pct = (x) => `${x >= 0.1 ? Math.round(x * 100) : (x * 100).toFixed(1)}%`;
+
+/** The one line under an instance's recommendation. */
+export function reasonText(a) {
+  const r = a.recommendation, ttl = ttlText(a.ttlSec);
+  if (r.reason === "quiet") return tc("quiet");
+  if (r.reason === "never_expired") {
+    if (a.sim.pastTtl) return tc("survived", a.sim.pastTtl, ttl);
+    return a.sim.tailPings ? tc("onlyIdle", a.sim.tailPings.toLocaleString("en-US")) : tc("neverExpired", ttl);
+  }
+  if (r.reason === "saves") return tc("saves", ttl, a.priced ? money(a.sim.net) : `${tokens(a.sim.net * 1e6)} ${tc("tokensUnit")}`, a.sim.expiryCost > 0 ? pct(a.sim.net / a.sim.expiryCost) : "—");
+  return a.priced ? tc("costsMore", r.pingsPerExpiry ?? 0, money(-a.sim.net)) : tc("costsMoreUnits", r.pingsPerExpiry ?? 0);
+}
+
+/** Gap histogram: one bar per bucket (square-root scale: a thousand short gaps must not flatten the few long ones). */
+function Histogram({ buckets, ttlSec }) {
+  const W = 280, H = 84, top = 14, base = 66, slot = W / buckets.length, bw = slot - 8;
+  const max = Math.max(1, ...buckets);
+  const ttlAt = EDGES.indexOf(ttlSec);
+  const label = `${tc("gaps")}: ${buckets.map((n, i) => `${tc(`b${i}`)} ${n}`).join(", ")}`;
+  return html`<svg class="ch-hist" viewBox=${`0 0 ${W} ${H}`} role="img" aria-label=${label} preserveAspectRatio="none">
+    ${buckets.map((n, i) => {
+      const h = n ? Math.max(2, Math.round((base - top) * Math.sqrt(n / max))) : 0;
+      const x = i * slot + 4;
+      return html`<g key=${i} class=${ttlAt >= 0 && i > ttlAt ? "ch-col past" : "ch-col"}>
+        <rect x=${x} y=${base - h} width=${bw} height=${h} rx="2" />
+        <text class="ch-n" x=${x + bw / 2} y=${base - h - 3} text-anchor="middle">${n || ""}</text>
+        <text class="ch-l" x=${x + bw / 2} y=${H - 4} text-anchor="middle">${tc(`b${i}`)}</text></g>`;
+    })}
+    ${ttlAt >= 0 ? html`<g class="ch-ttl"><line x1=${(ttlAt + 1) * slot} x2=${(ttlAt + 1) * slot} y1="4" y2=${base} />
+      <text x=${(ttlAt + 1) * slot + 3} y="11">${tc("ttlLine", ttlText(ttlSec))}</text></g>` : null}
+  </svg>`;
+}
+
+function Metric({ label, value, sub }) {
+  return html`<div class="ch-metric"><dt>${label}</dt><dd>${value}${sub ? html`<span class="ch-sub">${sub}</span>` : null}</dd></div>`;
+}
+
+function InstanceCard({ r }) {
+  const a = r.analysis, s = a.sim, $ = (v) => (a.priced ? money(v) : "—");
+  const on = a.recommendation.on;
+  return html`<article class=${`ch-card${on ? " on" : ""}`} aria-labelledby=${`ch-${r.name}`}>
+    <header class="ch-head">
+      <div class="ch-id"><h3 id=${`ch-${r.name}`} class="mono">${r.name}</h3>
+        <span class="ch-models">${r.backend}${a.models.length ? ` · ${a.models.join(", ")}` : ""}</span></div>
+      <span class=${`ch-rec${on ? " on" : ""}`}>${on ? tc("keepWarm") : tc("leaveOff")}</span>
+    </header>
+    <p class="ch-reason">${reasonText(a)}${a.estimate ? html` <span class="ch-tag">${tc("estimate")}</span>` : null}${a.priced ? null : html` <span class="ch-tag">${tc("notPriced")}</span>`}</p>
+    <dl class="ch-metrics">
+      <${Metric} label=${tc("requests")} value=${a.requests.toLocaleString("en-US")} />
+      <${Metric} label=${tc("pastTtl", ttlText(a.ttlSec))} value=${s.pastTtl} />
+      <${Metric} label=${tc("expired")} value=${s.expired} />
+      <${Metric} label=${tc("rewritten")} value=${tokens(s.rewriteTokens)} />
+      <${Metric} label=${tc("expiryCost")} value=${$(s.expiryCost)} sub=${a.share != null && a.priced && s.expiryCost > 0 ? tc("share", pct(a.share)) : null} />
+      <${Metric} label=${tc("pings")} value=${(s.pings + s.tailPings).toLocaleString("en-US")} sub=${s.tailPings ? tc("pingsAfter", s.tailPings) : null} />
+      <${Metric} label=${tc("pingCost")} value=${$(s.pingCost + s.tailCost)} />
+      <${Metric} label=${tc("net")} value=${a.priced ? `${s.net >= 0 ? "+" : "−"}${money(Math.abs(s.net))}` : "—"} />
+    </dl>
+    <${Histogram} buckets=${a.gapBuckets} ttlSec=${a.ttlSec} />
+  </article>`;
+}
+
+/** The tab's body. `report`: GET /ui/cache's answer; `win`/`setWin`: the window; `refresh`: read again. */
+export function CacheReport({ report, win, setWin, refresh }) {
+  const ok = report.instances.filter((r) => r.status === "ok")
+    .sort((x, y) => (y.analysis.priced - x.analysis.priced) || (y.analysis.sim.expiryCost - x.analysis.sim.expiryCost));
+  const rest = report.instances.filter((r) => r.status !== "ok");
+  const f = report.fleet;
+  const anyEstimate = ok.some((r) => r.analysis.estimate);
+  return html`<div class="ch">
+    <div class="ch-bar">
+      <div class="seg-inline" role="group" aria-label=${tc("window")}>${CACHE_WINDOWS.map((w) => html`<button key=${w} type="button"
+        class=${`btn btn-sm${w === win ? " btn-primary" : ""}`} aria-pressed=${w === win ? "true" : "false"} onClick=${() => setWin(w)}>${tc(`w${w}`)}</button>`)}</div>
+      ${!report.scanning.caughtUp || report.scanning.pendingBytes > 0 ? html`<div class="ch-scan" role="status"><span>${report.scanning.pendingBytes > 0
+        ? tc("scanning", bytes(report.scanning.pendingBytes)) : tc("scanningFirst")}</span>
+        <button type="button" class="btn btn-sm" onClick=${refresh}><${Icon} name="restart" size=${14} />${tc("refresh")}</button></div>` : null}
+    </div>
+    ${report.instances.length ? html`<section class="ch-fleet card">
+      <${Metric} label=${tc("fleetExpiry")} value=${money(f.expiryCost)} />
+      <${Metric} label=${tc("fleetSaving")} value=${money(f.saving)} />
+      <${Metric} label=${tc("fleetRecommended")} value=${tc("ofN", f.recommended, f.analysed)} />
+    </section>` : html`<${Empty} icon="chart" title=${tc("empty")} hint=${tc("emptyHint")} />`}
+    <div class="ch-notes note">
+      <p>${tc("pricesNote", report.pricesChecked)} ${tc("quotaNote")}</p>
+      ${anyEstimate ? html`<p>${tc("estimateNote")}</p>` : null}
+      ${f.priced ? null : html`<p>${tc("notPricedNote")}</p>`}
+    </div>
+    <div class="ch-cards">${ok.map((r) => html`<${InstanceCard} key=${r.name} r=${r} />`)}</div>
+    ${rest.length ? html`<ul class="rows ch-rest">${rest.map((r) => html`<li key=${r.name} class="row-item">
+      <span class="grow strong mono">${r.name}</span><span class="muted">${r.backend} · ${r.status === "no_data" ? tc("noData")
+        : `${tc("unavailable")} (${r.status === "credit_billed" ? tc("creditBilled") : r.status === "shared" ? tc("shared", (r.with || []).join(", ")) : tc("unsupported")})`}</span></li>`)}</ul>` : null}
+  </div>`;
+}

package/dist/ui/html-attachment.js

@@ -0,0 +1,26 @@
+// #1306 §6.1 (Q4): an agent's .html / .htm attachment gets the same preview card as a ```html block. Its HTML is read
+// from /ui/file/<id> — same origin, this session's cookie — only on a click (Preview, Open in panel), never to show a
+// card. What runs is then handed to the preview frame exactly like a block's (AgendPreview.start): the file URL itself
+// is never opened or framed on the dashboard's origin.
+
+/** The same cap as a block's (preview.js LIMITS.maxBytes): UTF-8 bytes of the HTML. */
+export const HTML_ATTACHMENT_MAX = 1024 * 1024;
+
+/**
+ * Read an attachment's HTML: { ok: true, code } or { ok: false, reason } with reason "over" (the file is over the
+ * cap: its listed size is checked before anything is fetched, the bytes again after), "gone" (the fleet no longer
+ * serves that id — the file changed, or the fleet restarted), or "failed".
+ */
+export async function loadHtmlAttachment(att, fetchImpl = globalThis.fetch) {
+  if (!att || typeof att.id !== "string" || !/^[0-9a-f]{32}$/.test(att.id)) return { ok: false, reason: "failed" };
+  if (typeof att.size === "number" && att.size > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  let res;
+  try { res = await fetchImpl(`/ui/file/${att.id}`, { credentials: "same-origin", cache: "no-store" }); }
+  catch { return { ok: false, reason: "failed" }; }
+  if (!res || !res.ok) return { ok: false, reason: res && res.status === 404 ? "gone" : "failed" };
+  let bytes;
+  try { bytes = await res.arrayBuffer(); } catch { return { ok: false, reason: "failed" }; }
+  if (bytes.byteLength > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  // UTF-8, as a block's text is; a BOM is dropped.
+  return { ok: true, code: new TextDecoder("utf-8").decode(bytes) };
+}