@songsid/agend 2.1.12-beta.9 → 2.2.0-alpha.1

package/dist/ui/chat-store.js

@@ -0,0 +1,289 @@
+// #1408 §5: the web chat's state, for the life of the page — every instance's messages, drafts, files waiting to go,
+// failed sends, prompts and turn state. It is fed by the app's one stream from the first frame, whatever panel is on
+// screen, so leaving the chat and coming back loses nothing (draft, scroll, files) and re-reads nothing.
+//
+// What it does is what the dashboard did (#1307, #1306, #1313, #1316, #1317); only where it lives changed. No DOM:
+// the chat panel renders it; tests drive it directly.
+//
+// Requests and #1374: the history of an instance is read once per page, when a person first opens its chat (a
+// navigation — it counts as use, as the old click did). Coming back to it reads nothing; the stream keeps it current.
+import "./chat-render.js";
+
+const R = () => globalThis.AgendChatRender;
+
+/** Build a store. `deps` (fetch, toast, announce, t, now) are injected so tests can drive every path. */
+export function createChatStore(deps) {
+  const s = {
+    msgs: {}, drafts: {}, failedSends: {}, pendingFiles: {}, sending: {}, inFlightFiles: {},
+    prompts: {}, workingSince: {}, stopping: {}, cancelling: {}, scrollMemo: {}, historyRead: new Set(),
+    exec: {}, awaiting: {}, current: null,
+  };
+  const subs = new Set();
+  const pastedTexts = new WeakMap();
+  const now = deps.now || (() => (typeof performance !== "undefined" ? performance.now() : Date.now()));
+  const t = deps.t, tf = deps.t;
+
+  /** Tell subscribers what changed: `kind` "msgs" (the thread redraws) or "state" (everything else). */
+  function changed(instance, kind = "state") { for (const fn of [...subs]) fn(instance, kind); }
+  async function api(method, path, body) {
+    const o = { method, headers: { "Content-Type": "application/json" } };
+    if (body) o.body = JSON.stringify(body);
+    const r = await deps.fetch(path, o);
+    return r.json();
+  }
+  const isUser = (x, instance) => x.sender === "web-user" || (!x.sender.startsWith("agend") && x.sender !== instance && x.sender !== "general");
+
+  // ── The turn (#1307): when this page saw the agent start working (its own monotonic clock, so approximate), a Stop
+  // on its way, and an instance waiting on a terminal prompt.
+  function noteExec(name, state) {
+    const was = R().isBusy(s.exec[name]), busy = R().isBusy(state);
+    const known = Object.prototype.hasOwnProperty.call(s.exec, name);
+    s.exec[name] = state;
+    if (busy && !was) s.workingSince[name] = now();
+    if (!busy) { delete s.workingSince[name]; delete s.stopping[name]; }
+    if (known && name === s.current && busy !== was) deps.announce(tf(busy ? "chat.a11yWorking" : "chat.a11yIdle", name));
+  }
+  function applyStatus(d) {
+    if (!d || !Array.isArray(d.instances)) return;
+    for (const i of d.instances) {
+      noteExec(i.name, (i.execution_state !== undefined ? i.execution_state : i.state) ?? null);
+      const waits = i.state === "awaiting_input" ? (typeof i.interaction_summary === "string" ? i.interaction_summary : "") : null;
+      if (i.name === s.current && waits != null && s.awaiting[i.name] == null) deps.announce(tf("chat.awaiting", i.name));
+      s.awaiting[i.name] = waits;
+    }
+    changed(null);
+  }
+  function applyActivity(d) {
+    if (!d || typeof d.instance !== "string") return;
+    noteExec(d.instance, d.state ?? null);
+    changed(d.instance);
+  }
+
+  // ── Messages: one way in, from the stream, a poll or the history; one entry per boot+id.
+  function ingest(m) {
+    if (!m || typeof m.instance !== "string") return;
+    const before = s.msgs[m.instance];
+    s.msgs[m.instance] = R().mergeMessages(before, [m], 500);
+    if (m.instance === s.current && s.msgs[m.instance] !== before && !isUser(m, m.instance) && (s.msgs[m.instance] || []).length > (before || []).length) deps.announce(tf("chat.a11yReplied", m.sender));
+    if (s.msgs[m.instance] !== before) changed(m.instance, "msgs");
+  }
+  function applyDeliveries(list) {
+    if (!Array.isArray(list)) return;
+    const touched = new Set();
+    for (const d of list) {
+      if (!d || typeof d.instance !== "string") continue;
+      const before = s.msgs[d.instance];
+      s.msgs[d.instance] = R().applyDelivery(before, d.messageId, d.delivery);
+      if (s.msgs[d.instance] !== before) touched.add(d.instance);
+    }
+    for (const i of touched) changed(i, "msgs");
+  }
+  /** Read an instance's history once per page (the first time a person opens its chat). */
+  async function openHistory(name, lease) {
+    if (s.historyRead.has(name)) return false;
+    s.historyRead.add(name);
+    try {
+      const r = await api("GET", `/ui/history?instance=${encodeURIComponent(name)}&limit=200`);
+      if (!r || !Array.isArray(r.messages)) { s.historyRead.delete(name); return true; }
+      // Kept even when the person has moved on: the store is page-lived, and the answer belongs to `name`.
+      s.msgs[name] = R().mergeMessages(s.msgs[name], r.messages, 500);
+      changed(name, "msgs");
+    } catch { s.historyRead.delete(name); /* the live stream still works; the next visit tries again */ }
+    void lease;
+    return true;
+  }
+
+  // ── Prompts the fleet has open (hang / clean exit / interactive input): the same buttons the platform shows.
+  function onPrompt(p) {
+    if (!p || typeof p.nonce !== "string") return;
+    const had = s.prompts[p.nonce];
+    const fresh = !had;
+    // A prompt already held (being answered, or claimed from Needs you) keeps its busy/answered state: a repeat of it
+    // only refreshes its text and buttons (#1463 review).
+    if (!had) s.prompts[p.nonce] = { ...p, resolved: false, busy: false };
+    else if (!had.resolved) Object.assign(had, { text: p.text, actions: p.actions, expiresAt: p.expiresAt });
+    if (p.instance === s.current) changed(p.instance);
+    else if (fresh) deps.toast(tf("chat.promptFor", p.instance, p.text), false);
+  }
+  /** The open prompts, on every stream (re)connect and with every poll: a prompt answered or expired while this page
+   *  was not listening is caught up here, and no timer ever re-reads anything. */
+  function applyPrompts(list) {
+    if (!Array.isArray(list)) return;
+    const open = new Set(list.map(p => p.nonce));
+    for (const p of list) {
+      const had = s.prompts[p.nonce];
+      if (!had) s.prompts[p.nonce] = { ...p, resolved: false, busy: false };
+      else if (!had.resolved) Object.assign(had, { text: p.text, actions: p.actions, expiresAt: p.expiresAt });
+    }
+    for (const n of Object.keys(s.prompts)) if (!s.prompts[n].resolved && !open.has(n)) s.prompts[n].resolved = true;
+    changed(null);
+  }
+  function resolvePrompt(d) {
+    const p = d && s.prompts[d.nonce];
+    if (!p) return;
+    p.resolved = true; p.busy = false;
+    if (d.outcome) p.outcome = d.outcome;
+    deps.setTimeout(() => { if (s.prompts[d.nonce] === p) { delete s.prompts[d.nonce]; changed(p.instance); } }, 60000);
+    changed(p.instance);
+  }
+  async function answerPrompt(p, action) {
+    if (p.busy || p.resolved) return;
+    p.busy = true; changed(p.instance);
+    let r;
+    try { r = await api("POST", "/ui/prompt", { instance: p.instance, nonce: p.nonce, action }); }
+    catch (err) { r = { error: err && err.message ? err.message : t("chat.disconnected") }; }
+    if (r && r.answered) return;   // the outcome arrives as prompt_resolved
+    const latest = s.prompts[p.nonce];
+    for (const q of latest && latest !== p ? [p, latest] : [p]) { q.busy = false; if (r && r.gone) q.resolved = true; }
+    changed(p.instance);
+    deps.toast(r && r.error ? r.error : t("chat.disconnected"), false);
+  }
+  /**
+   * Answer a prompt known only by its nonce (Needs you, #1386): the page's one claim on it. A prompt this store does not
+   * hold yet is entered now, busy, so the chat, a second click and a later hydration all see the same claim; the next
+   * prompts list or prompt_resolved settles it, as for any prompt.
+   */
+  function answerByNonce(item, action) {
+    if (!item || typeof item.nonce !== "string") return Promise.resolve();
+    let p = s.prompts[item.nonce];
+    if (!p) p = s.prompts[item.nonce] = { instance: item.instance, nonce: item.nonce, text: item.text || item.detail || "", actions: item.actions || [], resolved: false, busy: false };
+    return answerPrompt(p, action);
+  }
+  /** A claim taken elsewhere before this store existed (Needs you, before Chat booted): held here from now on. */
+  function holdPrompt(item) {
+    if (!item || typeof item.nonce !== "string") return;
+    let p = s.prompts[item.nonce];
+    if (!p) p = s.prompts[item.nonce] = { instance: item.instance, nonce: item.nonce, text: item.text || item.detail || "", actions: item.actions || [], resolved: false, busy: false };
+    if (!p.resolved) { p.busy = true; changed(p.instance); }
+  }
+  /** That claim's answer was refused: the prompt can be answered again (unless it was settled meanwhile). */
+  function releasePrompt(nonce) {
+    const p = s.prompts[nonce];
+    if (p && !p.resolved) { p.busy = false; changed(p.instance); }
+  }
+  const promptsFor = (instance) => Object.values(s.prompts).filter(p => p.instance === instance);
+
+  // ── Sending. Never lose anything: a failed send's files go back to that chat's list and its text back into its own
+  // composer when that is empty, otherwise it is kept for its chat and offered back (Put back).
+  async function uploadFile(target, file) {
+    const r = await deps.fetch(`/ui/upload?instance=${encodeURIComponent(target)}`, {
+      method: "POST",
+      headers: { "Content-Type": file.type || "application/octet-stream", "X-Agend-Filename": encodeURIComponent(file.name || "file") },
+      body: file,
+    });
+    let body = {};
+    try { body = await r.json(); } catch { /* not JSON */ }
+    if (!r.ok || !body || typeof body.id !== "string") throw new Error(body && body.error ? `${file.name}: ${body.error}` : `${file.name}: upload failed (${r.status})`);
+    return body;
+  }
+  async function send(target) {
+    const txt = (s.drafts[target] || "").trim();
+    const files = (s.pendingFiles[target] || []).slice();
+    if ((!txt && !files.length) || !target || s.sending[target]) return;
+    s.sending[target] = true;
+    s.drafts[target] = "";
+    s.pendingFiles[target] = []; s.inFlightFiles[target] = files;
+    changed(target);
+    changed(target, "sent");          // your own message: the thread goes to the bottom
+    let r;
+    try {
+      const ids = [];
+      for (const f of files) ids.push((await uploadFile(target, f)).id);
+      r = await api("POST", "/ui/send", ids.length ? { instance: target, message: txt, attachments: ids } : { instance: target, message: txt });
+    } catch (err) { r = { error: err && err.message ? err.message : t("chat.disconnected") }; }
+    s.sending[target] = false;
+    delete s.inFlightFiles[target];
+    if (r && !r.error) { changed(target); return; }
+    if (files.length) s.pendingFiles[target] = R().checkFiles(files, s.pendingFiles[target] || []).kept;
+    if (txt) {
+      const shown = s.current === target;
+      if (R().settleFailedSend(target, s.current, shown, shown ? (s.drafts[target] || "") : "") === "restore") s.drafts[target] = txt;
+      else s.failedSends[target] = s.failedSends[target] ? `${s.failedSends[target]}\n${txt}` : txt;
+    }
+    changed(target);
+    deps.toast(r && r.error ? r.error : t("chat.disconnected"), false);
+  }
+  function addFiles(target, list) {
+    if (!target) return;
+    const inFlight = s.inFlightFiles[target] || [];
+    const res = R().checkFiles(inFlight.concat(s.pendingFiles[target] || []), [...(list || [])]);
+    s.pendingFiles[target] = res.kept.slice(inFlight.length);
+    for (const x of res.rejected) deps.toast(`${x.name}: ${t(`chat.file_${x.reason.replace(/-/g, "_")}`)}`, false);
+    changed(target);
+  }
+  function removeFile(target, index) { (s.pendingFiles[target] || []).splice(index, 1); changed(target); }
+  /** A long paste as a .txt file when it fits beside what is attached; true when it was attached. */
+  function attachPastedText(target, text) {
+    if (!target) return false;
+    const stamp = new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "");
+    const f = new File([text], `pasted-${stamp}.txt`, { type: "text/plain" });
+    const taken = (s.inFlightFiles[target] || []).concat(s.pendingFiles[target] || []);
+    if (R().checkFiles(taken, [f]).rejected.length) { deps.toast(t("chat.pasteKeptAsText")); return false; }
+    pastedTexts.set(f, text);
+    addFiles(target, [f]);
+    deps.toast(tf("chat.pasteAttached", text.length.toLocaleString()));
+    return true;
+  }
+  /** A pasted file back into the composer as text. */
+  function fileBackAsText(target, index) {
+    const f = (s.pendingFiles[target] || [])[index];
+    if (!f || !pastedTexts.has(f)) return;
+    s.pendingFiles[target].splice(index, 1);
+    const draft = s.drafts[target] || "";
+    s.drafts[target] = draft ? `${draft}\n${pastedTexts.get(f)}` : pastedTexts.get(f);
+    changed(target);
+  }
+  const isPasted = (f) => pastedTexts.has(f);
+  function putBack(target) {
+    const kept = s.failedSends[target];
+    if (!kept) return;
+    s.drafts[target] = R().putBack(kept, s.drafts[target] || "");
+    delete s.failedSends[target];
+    changed(target);
+  }
+  function discardFailed(target) { delete s.failedSends[target]; changed(target); }
+  /** Typing: kept for its chat, no redraw (the composer already shows it). */
+  function setDraft(target, value) { s.drafts[target] = value; }
+
+  // ── Stop the reply under way (the composer's Stop, or Esc). Set before the request goes, so a held Esc or a second
+  // click sends nothing more (#1317); "Stopping…" until the agent goes idle, or a minute passes.
+  async function cancelReply(target) {
+    if (!target || s.cancelling[target]) return;
+    s.cancelling[target] = true;
+    changed(target);
+    let r;
+    try { r = await api("POST", `/ui/cancel/${encodeURIComponent(target)}`); }
+    catch (err) { r = { error: err && err.message ? err.message : t("chat.disconnected") }; }
+    delete s.cancelling[target];
+    if (r && !r.error) {
+      if (R().isBusy(s.exec[target])) {
+        s.stopping[target] = true;
+        deps.setTimeout(() => { if (s.stopping[target]) { delete s.stopping[target]; changed(target); } }, 60000);
+      }
+      deps.toast(`${target}: ${t("chat.stopSent")}`);
+    } else deps.toast(r && r.error ? r.error : t("chat.disconnected"), false);
+    changed(target);
+  }
+
+  /** Wire the store to the app's stream, for the life of the page. */
+  function attach(stream) {
+    stream.on("status", applyStatus);
+    stream.on("activity", applyActivity);
+    stream.on("message", ingest);
+    stream.on("delivery", (d) => applyDeliveries([d]));
+    stream.on("deliveries", applyDeliveries);
+    stream.on("prompt", onPrompt);
+    stream.on("prompts", applyPrompts);
+    stream.on("prompt_resolved", resolvePrompt);
+  }
+
+  return {
+    state: s,
+    subscribe(fn) { subs.add(fn); return () => subs.delete(fn); },
+    setCurrent(name) { s.current = name; },
+    attach, applyStatus, applyActivity, ingest, applyDeliveries, openHistory,
+    onPrompt, applyPrompts, resolvePrompt, answerPrompt, answerByNonce, holdPrompt, releasePrompt, promptsFor,
+    uploadFile, send, addFiles, removeFile, attachPastedText, fileBackAsText, isPasted, putBack, discardFailed, setDraft,
+    cancelReply, isUser,
+  };
+}

package/dist/ui/chat-strings.js

@@ -0,0 +1,69 @@
+// The chat's words (the chat.* namespace of the app's one dictionary, #1408 §4), in English and zh-TW.
+import { register } from "/assets/app-i18n.js";
+
+register("chat", {
+  en: {
+    tourTitle: "Welcome to web chat", tourStep: "{0} of {1}", tourBack: "Back", tourNext: "Next", tourDone: "Got it", tourSkip: "Skip",
+    tour1: "Pick an instance in the list to chat with it. On a phone, ☰ opens the list.",
+    tour2: "It is the same conversation as its Telegram or Discord chat: what you send here shows up there too, and the agent's replies show up in both.",
+    tour3: "Attach files and images with 📎, or paste or drop them on the chat.",
+    tour4: "While the agent works, Stop reply appears in the message box: it interrupts the current reply. The instance itself keeps running.",
+    tour5: "A “needs you” badge means the agent is waiting on its terminal, for example a permission question. Answer it from the buttons in its chat.",
+    a11yWorking: "{0} started working", a11yIdle: "{0} finished", a11yReplied: "{0} replied", conversationWith: "Conversation with {0}",
+    stopping: "Stopping {0}…", awaiting: "{0} is waiting for your input", approxNote: "Read from the terminal, so approximate", elapsedTitle: "Time since this page saw it start (approximate)",
+    dropHere: "Drop files to attach them", asText: "As text", pasteAttached: "A long paste ({0} characters) was attached as a text file", pasteKeptAsText: "No room for another attachment: the long paste stays as text",
+    send: "Send", composerPlaceholder: "Message {0}…", composerHint: "Enter to send · Shift+Enter for a new line · Esc stops the reply", attachTitle: "Attach files (images, PDF, text — or paste / drop them)",
+    pvPreview: "Preview", pvStop: "Stop", pvDownload: "Download", pvMenu: "Preview options", pvHtml: "HTML",
+    pvAllowButton: "Allow previews", pvAllow: "Allow HTML previews on this device — they may be able to send data out", pvDisallow: "Stop allowing HTML previews on this device",
+    pvConfirm: "Allow HTML previews on this device?\n\nA preview runs the agent's HTML in an isolated frame. It cannot use your login, but it may be able to send data out, and it can slow or freeze this tab. You still click Preview each time.",
+    pvNever: "Never preview HTML on this device", pvNeverUndo: "Let this device preview HTML again", pvStarting: "Starting the preview…",
+    pvChanged: "Preview stopped — the message changed. Preview again.", pvTruncated: "Truncated — ask the agent to send it as a .html file.",
+    previews: "Allow HTML previews on this device",
+    copy: "Copy", copyMessage: "Copy this reply", copied: "Copied", copyFailed: "Copy failed", wrap: "Wrap", showAll: "Show all {0} lines", showLess: "Show less", jumpLatest: "Latest", newBelow: "{0} new",
+    disconnected: "disconnected", tick_queued: "Waiting behind another message", tick_processing: "Handed to the agent", tick_delivered: "The agent has it", tick_failed: "Not delivered", tick_cancelled: "Dropped by Stop",
+    promptAnswering: "Answering…", promptGone: "This prompt is no longer open", promptFor: "{0}: {1}",
+    working: "{0} is working…", stuck: "{0} looks stuck", stopReply: "Stop reply", stopReplyTitle: "Stop the current reply (like Esc) and drop the messages still waiting. The instance keeps running.", stopSent: "Stopped",
+    file_empty: "empty file", file_too_large: "over 10 MB", file_too_many: "at most 5 files per message", file_too_much: "the files together would be over 25 MB", removeFile: "Remove", notSent: "Not sent:", putBack: "Put back", discard: "Discard",
+    noMessages: "No messages yet", sendFirst: "Send a message to start the conversation",
+    pick: "Pick an instance to start", pickHint: "Choose one in the list, or create a new one.", notFound: "No instance called “{0}”", notFoundHint: "It may have been deleted or renamed.", backToList: "Open the instance list",
+    details: "Instance details", start: "Start instance", stopInstance: "Stop instance", restart: "Restart instance", delete: "Delete instance…",
+    started: "{0} started", stoppedInst: "{0} stopped", restarted: "{0} restarted", instanceDeleted: "{0} was deleted",
+    deleteTitle: "Delete {0}?", deleteHelp: "This removes the instance from the fleet and stops it. Its working directory is kept. Type “delete {0}” to confirm.", deleteGo: "Delete", cancel: "Cancel",
+    loadFailed: "Failed to load", tour: "Tour", tourBtnTitle: "Show the web chat tour again",
+    dName: "Name", dStatus: "Status", dDisplay: "Display name", dDescription: "Description", dDirectory: "Directory", dBackend: "Backend", dModel: "Model", dEffort: "Effort",
+    dCost: "Cost", dCostNote: "(session accumulated)", dContext: "Context", dRate5: "Rate 5h", dRate7: "Rate 7d", dActivity: "Recent activity", dInstance: "Instance", dRuntime: "Runtime",
+    configured: "(configured)", fleetDefault: "(fleet default)",
+  },
+  "zh-TW": {
+    tourTitle: "歡迎使用網頁聊天", tourStep: "{0} / {1}", tourBack: "上一步", tourNext: "下一步", tourDone: "知道了", tourSkip: "略過",
+    tour1: "在清單裡選一個 instance，就能跟它對話。手機上請按 ☰ 打開清單。",
+    tour2: "這和它在 Telegram 或 Discord 上的是同一段對話：在這裡送出的訊息那邊也看得到，Agent 的回覆兩邊都會出現。",
+    tour3: "按 📎 附上檔案和圖片，也可以直接貼上或拖到聊天裡。",
+    tour4: "Agent 工作時，輸入框會出現「中止回覆」：中斷目前的回覆，instance 本身會繼續運行。",
+    tour5: "看到「等你回應」標記，表示 Agent 在終端機上等你，例如權限詢問。到它的聊天裡按按鈕回應即可。",
+    a11yWorking: "{0} 開始工作", a11yIdle: "{0} 已完成", a11yReplied: "{0} 已回覆", conversationWith: "與 {0} 的對話",
+    stopping: "正在中止 {0}…", awaiting: "{0} 正在等你回應", approxNote: "從終端畫面判讀，僅供參考", elapsedTitle: "從這個頁面看到它開始工作起算（約略）",
+    dropHere: "放開即可附加檔案", asText: "改為文字", pasteAttached: "貼上的長文字（{0} 個字元）已改為文字檔附加", pasteKeptAsText: "附件已滿，貼上的長文字保留為一般文字",
+    send: "送出", composerPlaceholder: "傳訊息給 {0}…", composerHint: "Enter 送出 · Shift+Enter 換行 · Esc 中止回覆", attachTitle: "附加檔案（圖片、PDF、文字檔，也可以貼上或拖曳）",
+    pvPreview: "預覽", pvStop: "停止", pvDownload: "下載", pvMenu: "預覽選項", pvHtml: "HTML",
+    pvAllowButton: "允許預覽", pvAllow: "允許這台裝置預覽 HTML（預覽可能把資料傳出去）", pvDisallow: "不再允許這台裝置預覽 HTML",
+    pvConfirm: "要允許這台裝置預覽 HTML 嗎？\n\n預覽會在隔離的框架裡執行 agent 的 HTML。它無法使用你的登入，但可能把資料傳出去，也可能讓這個分頁變慢或卡住。每次仍需要你按「預覽」。",
+    pvNever: "這台裝置永不預覽 HTML", pvNeverUndo: "讓這台裝置再次可以預覽 HTML", pvStarting: "正在啟動預覽…",
+    pvChanged: "預覽已停止——訊息內容變了。請再預覽一次。", pvTruncated: "內容被截斷——請 agent 改用 .html 檔案傳送。",
+    previews: "允許這台裝置預覽 HTML",
+    copy: "複製", copyMessage: "複製這則回覆", copied: "已複製", copyFailed: "複製失敗", wrap: "換行", showAll: "展開全部 {0} 行", showLess: "收合", jumpLatest: "最新", newBelow: "{0} 則新訊息",
+    disconnected: "已斷線", tick_queued: "排在前一則訊息之後", tick_processing: "已交給 agent", tick_delivered: "agent 已收到", tick_failed: "未送達", tick_cancelled: "已被中止取消",
+    promptAnswering: "回覆中…", promptGone: "這個提示已經結束", promptFor: "{0}：{1}",
+    working: "{0} 處理中…", stuck: "{0} 似乎卡住了", stopReply: "中止回覆", stopReplyTitle: "中止目前的回覆（同 Esc），並取消還在排隊的訊息。instance 會繼續運行。", stopSent: "已中止",
+    file_empty: "空檔案", file_too_large: "超過 10 MB", file_too_many: "每則訊息最多 5 個檔案", file_too_much: "檔案合計會超過 25 MB", removeFile: "移除", notSent: "未送出：", putBack: "放回輸入框", discard: "捨棄",
+    noMessages: "尚無訊息", sendFirst: "傳送訊息以開始對話",
+    pick: "選一個 instance 開始", pickHint: "在清單裡選一個，或建立新的。", notFound: "沒有叫「{0}」的 instance", notFoundHint: "它可能已被刪除或改名。", backToList: "打開 instance 清單",
+    details: "Instance 詳細資料", start: "啟動 instance", stopInstance: "停止 instance", restart: "重新啟動 instance", delete: "刪除 instance…",
+    started: "{0} 已啟動", stoppedInst: "{0} 已停止", restarted: "{0} 已重新啟動", instanceDeleted: "{0} 已刪除",
+    deleteTitle: "要刪除 {0} 嗎？", deleteHelp: "這會把 instance 從 fleet 移除並停止它，工作目錄會保留。請輸入「delete {0}」確認。", deleteGo: "刪除", cancel: "取消",
+    loadFailed: "載入失敗", tour: "導覽", tourBtnTitle: "再看一次網頁聊天導覽",
+    dName: "名稱", dStatus: "狀態", dDisplay: "顯示名稱", dDescription: "說明", dDirectory: "目錄", dBackend: "Backend", dModel: "模型", dEffort: "Effort",
+    dCost: "花費", dCostNote: "（本次 session 累計）", dContext: "Context", dRate5: "5 小時額度", dRate7: "7 天額度", dActivity: "最近活動", dInstance: "Instance", dRuntime: "執行環境",
+    configured: "（設定值）", fleetDefault: "（fleet 預設）",
+  },
+});

package/dist/ui/chat-thread.js

@@ -0,0 +1,209 @@
+// #1408 §0/§4: the conversation thread — the keyed DOM renderer #1307 and #1306 reviewed, now owned by the chat panel
+// through a ref. Preact never manages these children: a node here may hold a live preview iframe, and an iframe that
+// is moved or re-parented reloads. So:
+// - a new message is appended; a changed one (its ticks) is replaced; the rest are left alone — an opened code block
+//   stays open, a selection survives, where the reader scrolled stays theirs;
+// - before ONE node is replaced, moved or removed: AgendPreview.stopIn(that node) — frames elsewhere keep running;
+// - when the whole thread goes (the chat left, another instance opened): AgendPreview.stopAll("leave").
+// Unrelated updates (a new message, another message's tick) stop nothing (#1306 §6.2, #1408 §4).
+import "./chat-render.js";
+import "./preview.js";
+
+const R = () => globalThis.AgendChatRender;
+const P = () => globalThis.AgendPreview;
+const COPY = '<svg class="icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
+
+/** Escapes & " ' < >: safe for text and inside a quoted attribute. */
+export function escAttr(s) { return String(s == null ? "" : s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); }
+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) }.
+ */
+export function createThread(list, scroller, opts) {
+  const nodes = new Map();          // key → { html, node }
+  let msgs = [];
+  let unseen = 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) : []);
+
+  const TICKS = () => ({ queued: tr("chat.tick_queued"), processing: tr("chat.tick_processing"), delivered: tr("chat.tick_delivered"), failed: tr("chat.tick_failed"), cancelled: tr("chat.tick_cancelled") });
+
+  function msgHtml(x) {
+    const u = opts.isUser(x);
+    const time = x.ts ? new Date(x.ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "";
+    // 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>`;
+  }
+  function msgNode(html, x, stoppedKeys) {
+    const tpl = list.ownerDocument.createElement("template");
+    tpl.innerHTML = html;
+    const node = tpl.content.firstElementChild;
+    decorateCode(node);
+    if (x) decorateHtmlCards(node, x, stoppedKeys || []);
+    return node;
+  }
+
+  // Code blocks: a header (language, Wrap, Copy); a long one is folded until opened. Built from nodes.
+  function decorateCode(root) {
+    const doc = list.ownerDocument;
+    for (const pre of root.querySelectorAll(".md pre")) {
+      const box = doc.createElement("div"); box.className = "codeblock";
+      const head = doc.createElement("div"); head.className = "cb-head";
+      const lang = doc.createElement("span"); lang.className = "cb-lang"; lang.textContent = pre.dataset.lang || "text";
+      const wrap = doc.createElement("button"); wrap.type = "button"; wrap.className = "chip-btn"; wrap.dataset.act = "toggleWrap"; wrap.textContent = tr("chat.wrap");
+      const copy = doc.createElement("button"); copy.type = "button"; copy.className = "chip-btn"; copy.dataset.act = "copyCode"; copy.textContent = tr("chat.copy");
+      head.append(lang, wrap, copy);
+      pre.replaceWith(box); box.append(head, pre);
+      const lines = R().lineCount(pre.textContent);
+      if (lines > R().CODE_FOLD_LINES) {
+        box.classList.add("folded");
+        const more = doc.createElement("button"); more.type = "button"; more.className = "cb-more"; more.dataset.act = "toggleFold";
+        more.dataset.lines = String(lines); more.textContent = trf("chat.showAll", lines);
+        box.append(more);
+      }
+    }
+  }
+
+  // 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).
+  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);
+    }
+  }
+  /** 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(); }
+  }
+
+  const nearBottom = () => R().isNearBottom(scroller.scrollTop, scroller.clientHeight, scroller.scrollHeight);
+  function reportJump() { opts.onJump({ show: !nearBottom(), unseen }); }
+
+  /** Draw `next` (this instance's messages). `restore`: the scroll position to return to (null = the bottom). */
+  function render(next, renderOpts = {}) {
+    const stick = nearBottom();
+    msgs = next || [];
+    if (!msgs.length) {
+      for (const v of nodes.values()) stopIn(v.node);
+      nodes.clear();
+      list.textContent = "";
+      opts.onEmpty(true);
+      return;
+    }
+    opts.onEmpty(false);
+    const keep = new Set(msgs.map(msgKey));
+    for (const [k, v] of nodes) if (!keep.has(k)) { stopIn(v.node); v.node.remove(); nodes.delete(k); }
+    let prev = null, added = 0;
+    for (const x of msgs) {
+      const key = msgKey(x), html = msgHtml(x);
+      let have = nodes.get(key);
+      if (!have || have.html !== html) {
+        const stopped = have ? stopIn(have.node) : [];
+        const node = msgNode(html, x, stopped);
+        if (have) have.node.replaceWith(node); else added++;
+        have = { html, node }; nodes.set(key, have);
+      }
+      const want = prev ? prev.nextSibling : list.firstChild;
+      // A node already in the list is being moved: its preview stops first. A new node (still in its template) has none.
+      if (have.node !== want) { if (have.node.parentNode === list) stopIn(have.node); list.insertBefore(have.node, want); }
+      prev = have.node;
+    }
+    if ("restore" in renderOpts) {
+      unseen = 0;
+      scroller.scrollTop = renderOpts.restore == null ? scroller.scrollHeight : renderOpts.restore;
+    } else if (stick) scroller.scrollTop = scroller.scrollHeight;
+    else unseen += added;
+    reportJump();
+  }
+
+  function onScroll() {
+    const bottom = nearBottom();
+    if (bottom) unseen = 0;
+    reportJump();
+    return bottom ? null : scroller.scrollTop;
+  }
+  function jumpLatest() { scroller.scrollTop = scroller.scrollHeight; unseen = 0; reportJump(); }
+
+  async function copyFrom(button, text) {
+    const ok = await opts.copyText(text);
+    if (button.classList.contains("icon-only")) {
+      button.classList.add(ok ? "done" : "fail");
+      button.title = ok ? tr("chat.copied") : tr("chat.copyFailed"); button.setAttribute("aria-label", button.title);
+      setTimeout(() => { button.classList.remove("done", "fail"); button.title = tr("chat.copyMessage"); button.setAttribute("aria-label", button.title); }, 1200);
+      return;
+    }
+    const was = button.dataset.label || button.textContent; button.dataset.label = was;
+    button.textContent = ok ? tr("chat.copied") : tr("chat.copyFailed");
+    setTimeout(() => { button.textContent = was; }, 1200);
+  }
+  /** The thread's own buttons (Copy, Wrap, fold), delegated from the thread element. */
+  function onClick(e) {
+    const el = e.target && e.target.closest ? e.target.closest("[data-act]") : null;
+    if (!el || !list.contains(el)) return;
+    const act = el.dataset.act;
+    if (act === "copyMsg") { const x = msgs.find(y => msgKey(y) === el.dataset.arg); if (x) copyFrom(el, x.text); }
+    else if (act === "copyCode") { const pre = el.closest(".codeblock")?.querySelector("pre"); if (pre) copyFrom(el, pre.textContent); }
+    else if (act === "toggleFold") {
+      const box = el.closest(".codeblock"); if (!box) return;
+      const folded = box.classList.toggle("folded");
+      el.textContent = folded ? trf("chat.showAll", el.dataset.lines) : tr("chat.showLess");
+    } else if (act === "toggleWrap") opts.toggleWrap();
+  }
+
+  /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */
+  function dispose() {
+    if (P()) P().stopAll("leave");
+    nodes.clear();
+  }
+
+  return { render, onScroll, onClick, jumpLatest, refreshCards, dispose, nodes, get unseen() { return unseen; } };
+}