@oar-sh/oar 0.9.9 → 0.9.11

package/server/public/app/about-ui.js

@@ -0,0 +1,73 @@
+// ⋯ → About OAR: the menu entry's label and the modal (about-view.mjs builds
+// its HTML from GET /api/about).
+
+import {
+  closeSummaryModal,
+  escHtml,
+  getUpdateState,
+  openSummaryModal,
+  renderSummaryModalContent,
+  setSummaryModalLoading,
+} from './store.js';
+import { apiFetchOrThrow } from './api-client.js';
+import { openSettingsModal } from './settings-modal.js';
+import { aboutMenuLabel, buildAboutModalHtml } from './about-view.mjs';
+
+const ABOUT_KIND = 'about';
+const ABOUT_TITLE = 'About OAR';
+
+/** The entry carries the running version; /api/status brings it on load. */
+export function syncAboutMenuLabel(version = getUpdateState()?.runningVersion) {
+  const button = document.getElementById('chat-menu-about');
+  if (button) button.textContent = aboutMenuLabel(version);
+}
+
+function bindAboutModalActions() {
+  const body = document.getElementById('summary-modal-body');
+  const button = body?.querySelector('[data-about-open-settings]');
+  if (!button) return;
+  button.addEventListener('click', (event) => {
+    event.preventDefault();
+    closeSummaryModal();
+    openSettingsModal('general');
+    document.getElementById('update-auto-check-toggle')?.scrollIntoView?.({ block: 'center' });
+  });
+}
+
+async function loadAboutAndRender() {
+  const about = await apiFetchOrThrow('/api/about');
+  if (!about) throw new Error('The relay is not reachable right now.');
+  renderSummaryModalContent({
+    title: ABOUT_TITLE,
+    subtitle: about.version ? `Version ${about.version}` : '',
+    bodyHtml: buildAboutModalHtml(about),
+    refresh: loadAboutAndRender,
+    kind: ABOUT_KIND,
+  });
+  bindAboutModalActions();
+  syncAboutMenuLabel(about.version);
+}
+
+export async function showAbout() {
+  openSummaryModal({
+    title: ABOUT_TITLE,
+    subtitle: 'Loading…',
+    bodyHtml: '<div class="summary-loading">Reading the relay…</div>',
+    refresh: loadAboutAndRender,
+    kind: ABOUT_KIND,
+  });
+  setSummaryModalLoading(true);
+  try {
+    await loadAboutAndRender();
+  } catch (error) {
+    renderSummaryModalContent({
+      title: ABOUT_TITLE,
+      subtitle: 'Unable to load',
+      bodyHtml: `<div class="summary-error">${escHtml(error?.message || 'Unknown error')}</div>`,
+      refresh: loadAboutAndRender,
+      kind: ABOUT_KIND,
+    });
+  } finally {
+    setSummaryModalLoading(false);
+  }
+}

package/server/public/app/about-view.mjs

@@ -0,0 +1,234 @@
+// The About OAR modal, as HTML from a GET /api/about payload. No DOM here;
+// about-ui.js opens the modal and wires it.
+
+export const OAR_REPO_URL = 'https://github.com/oar-sh/oar';
+export const OAR_SITE_URL = 'https://oar.sh';
+export const OAR_RELEASES_URL = 'https://github.com/oar-sh/oar/releases';
+
+const STATE_LABELS = Object.freeze({
+  online: 'online',
+  offline: 'offline',
+  idle: 'idle',
+});
+
+const USAGE_LABELS = Object.freeze({
+  github: 'GitHub Copilot',
+  cursor: 'Cursor',
+  grok: 'Grok',
+  'claude-cloud': 'Claude Cloud',
+});
+
+function esc(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function finite(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+export function aboutMenuLabel(version) {
+  const text = String(version || '').trim();
+  return text && text !== '0.0.0' ? `ℹ️ About OAR · ${text}` : 'ℹ️ About OAR';
+}
+
+export function formatCount(value) {
+  const number = finite(value);
+  return number === null ? '–' : Math.round(number).toLocaleString('en-US');
+}
+
+/** Tokens and other large amounts: 1 234, 12.3 k, 4.56 M. */
+export function formatAmount(value) {
+  const number = finite(value);
+  if (number === null) return '–';
+  if (Math.abs(number) >= 1e9) return `${(number / 1e9).toFixed(2)} B`;
+  if (Math.abs(number) >= 1e6) return `${(number / 1e6).toFixed(2)} M`;
+  if (Math.abs(number) >= 1e4) return `${(number / 1e3).toFixed(1)} k`;
+  return Number.isInteger(number) ? number.toLocaleString('en-US') : number.toFixed(2);
+}
+
+export function formatUsd(value) {
+  const number = finite(value);
+  return number === null ? '–' : `USD ${number.toFixed(2)}`;
+}
+
+export function formatBytes(value) {
+  const number = finite(value);
+  if (number === null || number < 0) return '–';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let size = number;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit += 1;
+  }
+  return unit === 0 ? `${Math.round(size)} B` : `${size.toFixed(size >= 100 ? 0 : 1)} ${units[unit]}`;
+}
+
+export function formatUptime(seconds) {
+  const total = finite(seconds);
+  if (total === null || total < 0) return '–';
+  const days = Math.floor(total / 86_400);
+  const hours = Math.floor((total % 86_400) / 3_600);
+  const minutes = Math.floor((total % 3_600) / 60);
+  if (days > 0) return `${days} d ${hours} h`;
+  if (hours > 0) return `${hours} h ${minutes} min`;
+  if (minutes > 0) return `${minutes} min`;
+  return `${Math.floor(total)} s`;
+}
+
+function defaultFormatDateTime(iso) {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return '–';
+  return new Date(at).toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' });
+}
+
+function defaultFormatDate(iso) {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return '–';
+  return new Date(at).toLocaleDateString(undefined, { dateStyle: 'medium' });
+}
+
+function row(label, value, { hint = '', title = '' } = {}) {
+  return `<tr><td><div class="plan-usage-detail-label"><span>${esc(label)}</span>${hint ? `<span class="plan-usage-detail-hint">${esc(hint)}</span>` : ''}</div></td>`
+    + `<td class="plan-usage-detail-value"${title ? ` title="${esc(title)}"` : ''}>${value}</td></tr>`;
+}
+
+function section(id, title, inner, { subtitle = '' } = {}) {
+  return `<section class="plan-usage-card about-section" data-about-section="${esc(id)}">`
+    + `<div class="plan-usage-card-head"><div class="plan-usage-card-titles"><span class="plan-usage-card-title">${esc(title)}</span>`
+    + `${subtitle ? `<span class="plan-usage-account">${esc(subtitle)}</span>` : ''}</div></div>${inner}</section>`;
+}
+
+function table(rows) {
+  return rows.length ? `<table class="plan-usage-detail-table"><tbody>${rows.join('')}</tbody></table>` : '';
+}
+
+function note(text) {
+  return `<div class="plan-usage-detail-note">${text}</div>`;
+}
+
+function externalLink(href, text) {
+  return `<a class="plan-usage-link" href="${esc(href)}" target="_blank" rel="noopener">${esc(text)}</a>`;
+}
+
+function providerDetails(provider) {
+  const parts = [];
+  if (provider.engine === 'extension') parts.push('extension engine');
+  if (provider.engine === 'sdk') parts.push('SDK engine');
+  if (provider.cliVersion) parts.push(`CLI ${provider.cliVersion}`);
+  if (provider.sdkVersion) parts.push(`SDK ${provider.sdkVersion}`);
+  return parts.join(' · ');
+}
+
+function providerState(provider) {
+  const state = STATE_LABELS[provider.state] ? provider.state : 'idle';
+  const workers = finite(provider.runningWorkers) || 0;
+  const count = workers > 0 ? ` · ${workers} ${workers === 1 ? 'worker' : 'workers'}` : '';
+  return `<span class="about-state" data-state="${esc(state)}">${esc(STATE_LABELS[state])}</span>${esc(count)}`;
+}
+
+function usageRows(id, usage) {
+  if (id === 'github') {
+    return [row('Premium requests', esc(formatAmount(usage.premiumRequests)), { hint: `over ${formatCount(usage.turns)} replies` })];
+  }
+  if (id === 'cursor') {
+    return [
+      row('Tokens', esc(formatAmount(usage.totalTokens)), {
+        hint: `${formatAmount(usage.inputTokens)} in · ${formatAmount(usage.outputTokens)} out · ${formatAmount((finite(usage.cacheReadTokens) || 0) + (finite(usage.cacheWriteTokens) || 0))} cache`,
+      }),
+      row('Cost', esc(formatUsd(usage.rawCostUsd)), { hint: `model price over ${formatCount(usage.runs)} runs; charged ${formatUsd(usage.chargedUsd)}` }),
+    ];
+  }
+  if (id === 'grok') {
+    return [
+      row('Tokens', esc(formatAmount(usage.totalTokens)), { hint: `${formatAmount(usage.inputTokens)} in · ${formatAmount(usage.outputTokens)} out` }),
+      row('Cost', esc(formatUsd(usage.costUsd)), { hint: `over ${formatCount(usage.turns)} turns` }),
+    ];
+  }
+  if (id === 'claude-cloud') {
+    return [row('Cost', esc(formatUsd(usage.costUsd)), { hint: `over ${formatCount(usage.sessions)} cloud sessions` })];
+  }
+  return [];
+}
+
+function buildUpdateSection(update, formatDateTime) {
+  if (update.checkEnabled) {
+    if (update.available && update.latestVersion) {
+      return section('update', 'Updates', note(`Latest: ${esc(update.latestVersion)} · ${externalLink(update.notesUrl || OAR_RELEASES_URL, 'release notes')}`));
+    }
+    const checked = update.lastCheckedAt ? `, checked ${esc(formatDateTime(update.lastCheckedAt))}` : '';
+    return section('update', 'Updates', note(update.lastCheckedAt ? `Up to date${checked}.` : 'Not checked yet.'));
+  }
+  if (update.checkKilled) {
+    return section('update', 'Updates', note('Update checks are turned off on this relay (OAR_NO_UPDATE_CHECK).'));
+  }
+  return section('update', 'Updates', note(
+    'Update checks are off. Turn on <button type="button" class="plan-usage-link about-inline-button" data-about-open-settings>Settings › General › Check for updates automatically</button> to see the latest version here.',
+  ));
+}
+
+/**
+ * @param {object} about the GET /api/about payload
+ * @param {object} [options]
+ * @param {(iso: string) => string} [options.formatDateTime]
+ * @param {(iso: string) => string} [options.formatDate]
+ */
+export function buildAboutModalHtml(about = {}, {
+  formatDateTime = defaultFormatDateTime,
+  formatDate = defaultFormatDate,
+} = {}) {
+  const sections = [];
+
+  const commit = String(about.commit || '').trim();
+  const install = about.installMethod === 'git-checkout' ? 'git checkout' : (about.installMethod === 'npm-global' ? 'npm package' : '');
+  sections.push(section('build', 'OAR', table([
+    row('Version', esc(about.version || '–'), install ? { hint: install } : {}),
+    ...(commit ? [row('Commit', `<code>${esc(commit.slice(0, 7))}</code>`, { title: commit })] : []),
+    row('Started', esc(about.startedAt ? formatDateTime(about.startedAt) : '–')),
+    row('Uptime', esc(formatUptime(about.uptimeSeconds))),
+  ])));
+
+  const providers = Array.isArray(about.providers) ? about.providers : [];
+  sections.push(section('providers', 'Providers', providers.length
+    ? table(providers.map((provider) => row(provider.label || provider.id, providerState(provider), { hint: providerDetails(provider) })))
+      + (providers.some((provider) => provider.state === 'idle')
+        ? note('Idle: on, with no worker running right now; one starts with the next turn.')
+        : '')
+    : note('No provider is turned on.')));
+
+  const stats = about.stats || {};
+  const turnsByProvider = Array.isArray(stats.turnsByProvider) ? stats.turnsByProvider : [];
+  const archived = finite(stats.archivedConversations) || 0;
+  sections.push(section('activity', 'Activity', table([
+    row('Conversations', esc(formatCount(stats.conversations)), archived ? { hint: `${formatCount(archived)} archived` } : {}),
+    row('Turns', esc(formatCount(stats.turns)), { hint: 'replies written by an agent' }),
+    row('Messages', esc(formatCount(stats.messages))),
+    ...turnsByProvider.map((entry) => row(`Turns on ${entry.label || entry.id}`, esc(formatCount(entry.turns)))),
+  ]), { subtitle: stats.firstConversationAt ? `since ${formatDate(stats.firstConversationAt)}` : '' }));
+
+  const usage = about.usage && typeof about.usage === 'object' ? about.usage : {};
+  const usageIds = Object.keys(USAGE_LABELS).filter((id) => usage[id]);
+  sections.push(section('usage', 'Usage', (usageIds.length
+    ? usageIds.map((id) => `<div class="about-usage-provider">${esc(USAGE_LABELS[id])}</div>${table(usageRows(id, usage[id]))}`).join('')
+    : note('No provider has reported usage yet.'))
+    + note('What the providers report and this relay keeps: Copilot premium requests per reply, Cursor and Grok tokens and cost per billing cycle, Claude Cloud cost per session. Claude Code and OpenAI turns keep no usage here.')));
+
+  const relay = about.relay || {};
+  sections.push(section('relay', 'Relay', table([
+    row('Uptime', esc(formatUptime(relay.uptimeSeconds))),
+    row('Database', esc(formatBytes(relay.dbBytes)), { hint: `${formatBytes(relay.dbFileBytes)} + ${formatBytes(relay.walBytes)} WAL` }),
+    row('Running workers', esc(formatCount(relay.runningWorkers))),
+  ])));
+
+  sections.push(buildUpdateSection(about.update || {}, formatDateTime));
+
+  sections.push(`<div class="about-links" data-about-section="links">${externalLink(OAR_REPO_URL, 'github.com/oar-sh/oar')}${externalLink(OAR_SITE_URL, 'oar.sh')}</div>`);
+
+  return `<div class="about-modal">${sections.join('')}</div>`;
+}

package/server/public/app/action-confirmations.js

@@ -19,6 +19,7 @@ import {
   refreshWorkspaceRootHints,
 } from './api-client.js';
 import { isSuspendHostActionVisible } from './settings-modal.js';
+import { describeRelayRestartError } from './relay-restart-error.mjs';
 import {
   applyHostSuspendState,
   describeHostSuspendBlocker,
@@ -311,10 +312,17 @@ export async function confirmEmptyQueue() {
   emptyQueueInFlight = true;
   setSummaryModalLoading(true);
   try {
-    const result = await requestQueueEmpty({
-      reason: 'manual-empty-queue',
-      requestedBy: 'localhost-api',
-    });
+    let result = null;
+    try {
+      result = await requestQueueEmpty({
+        reason: 'manual-empty-queue',
+        requestedBy: 'localhost-api',
+      });
+    } catch (error) {
+      closeSummaryModal();
+      alert(`Failed to empty queue: ${error?.message || 'unknown error'}`);
+      return;
+    }
     closeSummaryModal();
     if (!result?.ok) {
       alert('Failed to empty queue');
@@ -334,23 +342,32 @@ export async function confirmEmptyQueue() {
   }
 }
 
+/** A failed restart request: a refusal as an alert, no answer as a notice. */
+export function showRelayRestartRequestError(error) {
+  const { kind, text } = describeRelayRestartError(error);
+  if (kind === 'refused') alert(text);
+  else showTransientRelayNotice(text, 9000);
+}
+
 export async function confirmRestartWebRelay() {
   if (restartRelayInFlight) return;
   restartRelayInFlight = true;
   setSummaryModalLoading(true);
   try {
-    const result = await requestRelayRestart({
-      reason: 'manual-restart',
-      requestedBy: 'localhost-api',
-      restart: true,
-    });
-    closeSummaryModal();
-    // Restart can close the connection before the browser receives JSON.
-    if (!result) {
-      showTransientRelayNotice('Relay restart requested. Connection may briefly drop while it restarts.', 7000);
+    let result = null;
+    try {
+      result = await requestRelayRestart({
+        reason: 'manual-restart',
+        requestedBy: 'localhost-api',
+        restart: true,
+      });
+    } catch (error) {
+      closeSummaryModal();
+      showRelayRestartRequestError(error);
       return;
     }
-    if (!result.ok) {
+    closeSummaryModal();
+    if (!result?.ok) {
       alert('Failed to queue relay restart');
       return;
     }

package/server/public/app/agent-exchange-fold-view.mjs

@@ -0,0 +1,187 @@
+// Agent-to-agent exchanges in the transcript: a prompt another agent sent this
+// session (another relay's agent, or an agent on this relay) folds into ONE
+// row, "note from win-test · report builder · answered below", which opens to
+// the prompt as it renders otherwise.
+//
+// DOM-free on purpose, like relay-event-view.mjs: conversation-view.js reads
+// the rows off the transcript, plans with this module and applies the plan.
+// Presentation only: the transcript data is never touched.
+//
+// Nothing addressed to the user is folded away. The fold covers the agent's
+// prompt and nothing else: this session's reply to it can carry a line for
+// the user, so the reply, the live bubble of the running turn and every card
+// of the turn always show, as they do for a message of the user's own. The
+// row still says how the turn stands.
+//
+// One prompt is left as it is: an agent's prompt that was steered into a
+// running turn. It renders as part of that turn's flow (steered-turn-merge.mjs:
+// the dashed bubble, the marker attached under it), and a row in its place
+// would break that flow.
+
+import { isRelayEventMessage } from './relay-event-view.mjs';
+import { relayErrorCodeFromText } from './relay-error-ctas.mjs';
+import { isLocalAgentOrigin, localAgentOriginModel, normalizeRemoteOrigin } from './remote-relay-origin-view.mjs';
+
+export const AGENT_EXCHANGE_HEAD_CLASS = 'agent-exchange-head';
+export const AGENT_EXCHANGE_CLOSED_CLASS = 'agent-exchange-closed';
+
+export const AGENT_EXCHANGE_STATUS_TEXT = Object.freeze({
+  working: 'working…',
+  replied: 'answered below',
+  failed: 'failed',
+  stopped: 'stopped',
+  none: 'no reply yet',
+});
+
+// The code a turn the user stopped ends with (shared/relay-stop-failure.mjs).
+const STOPPED_ERROR_CODE = 'turn-aborted';
+// A steer's settle markers (steered-turn-merge.mjs): the message was consumed
+// by another turn, folded into it or stopped with it.
+const STEER_MARKER_KINDS = new Set(['folded', 'stopped']);
+
+function defaultEscape(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function oneLine(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** True for an `origin` that names an agent: one on this relay or another relay's. */
+export function isAgentOrigin(origin) {
+  return isLocalAgentOrigin(origin) || !!normalizeRemoteOrigin(origin);
+}
+
+/** A prompt an agent sent: a user row with an agent's origin, never a relay event. */
+export function isAgentPromptMessage(message) {
+  return message?.role === 'user' && !isRelayEventMessage(message) && isAgentOrigin(message?.origin);
+}
+
+/**
+ * How a reply ended, from its text: 'failed' or 'stopped' for a failure note
+ * of the relay, '' for an answer. The note goes below what the turn had
+ * written before it failed, so only the last paragraph is read.
+ */
+export function replyOutcome(text) {
+  const paragraphs = String(text ?? '').trim().split(/\r?\n\s*\r?\n/);
+  const code = relayErrorCodeFromText(paragraphs[paragraphs.length - 1]);
+  if (!code) return '';
+  return code === STOPPED_ERROR_CODE ? 'stopped' : 'failed';
+}
+
+/**
+ * What the plan needs of one message, built when its row is: an agent
+ * prompt's origin, an assistant row's kind, the prompt it answers and how it
+ * ended.
+ */
+export function agentExchangeRowOf(message, { id = message?.id } = {}) {
+  const role = message?.role === 'assistant' ? 'assistant' : (message?.role === 'user' ? 'user' : '');
+  return {
+    id: String(id ?? '').trim(),
+    role,
+    relayEvent: isRelayEventMessage(message),
+    origin: isAgentPromptMessage(message) ? message.origin : null,
+    kind: String(message?.kind || '').trim(),
+    sourceMessageId: role === 'assistant' ? String(message?.sourceMessageId || '').trim() : '',
+    outcome: role === 'assistant' ? replyOutcome(message?.text) : '',
+  };
+}
+
+/**
+ * The plan for a transcript: one entry per agent prompt, in transcript order.
+ *
+ * `rows` are the transcript's rows in order (agentExchangeRowOf, plus
+ * `steered` for a user row steered-turn-merge.mjs classed as steered), and
+ * the live bubble of a running turn as `{ id: <its message id>, role:
+ * 'assistant', live: true }`. `runningIds` names turns that run without a
+ * live bubble on the page.
+ *
+ * Each entry: `{ promptId, prompt, status, fold }`. The prompt's row is the
+ * only one a fold covers; the replies and the live bubble are read for the
+ * status alone. `fold` is false for a prompt steered into a running turn.
+ */
+export function planAgentExchangeFolds(rows, { runningIds = [] } = {}) {
+  const list = (Array.isArray(rows) ? rows : []).filter((row) => row && String(row.id || '').trim());
+  const running = new Set(Array.from(runningIds || [], (value) => String(value ?? '').trim()).filter(Boolean));
+
+  const turns = [];
+  const turnById = new Map();
+  for (const row of list) {
+    if (row.role !== 'user' || !row.origin || turnById.has(row.id)) continue;
+    const turn = { prompt: row, replies: [], live: false };
+    turns.push(turn);
+    turnById.set(row.id, turn);
+  }
+  for (const row of list) {
+    if (row.role !== 'assistant') continue;
+    const turn = turnById.get(row.live ? row.id : row.sourceMessageId);
+    if (!turn) continue;
+    if (row.live) turn.live = true;
+    else turn.replies.push(row);
+  }
+
+  return turns.map((turn) => {
+    const markers = turn.replies.filter((row) => STEER_MARKER_KINDS.has(row.kind));
+    // An answer, or the marker that the answer is on a continuation row
+    // further down.
+    const answers = turn.replies.filter((row) => !STEER_MARKER_KINDS.has(row.kind));
+    const last = answers[answers.length - 1] || null;
+    let status = 'none';
+    if (last) status = last.outcome || 'replied';
+    else if (turn.live || running.has(turn.prompt.id)) status = 'working';
+    return {
+      promptId: turn.prompt.id,
+      prompt: turn.prompt,
+      status,
+      fold: !turn.prompt.steered && !markers.length,
+    };
+  });
+}
+
+/**
+ * Whether a folded prompt shows open. `choice` is the user's own toggle of
+ * it (true opened, false closed, undefined none) and always wins; without
+ * one it is open while the turn works and closes by itself once it is
+ * replied, failed or stopped.
+ */
+export function agentExchangeFoldOpen(status, choice) {
+  if (typeof choice === 'boolean') return choice;
+  return status === 'working';
+}
+
+/**
+ * The folded row's words: who sent the prompt (the relay's name; for an agent
+ * on this relay the name the origin carries, else "this relay"), from which
+ * session (for a local one its current title when `conversations` knows it),
+ * and how the turn stands.
+ */
+export function agentExchangeSummary(origin, status, { conversations = null } = {}) {
+  const local = localAgentOriginModel(origin, { conversations, linkable: false });
+  const remote = local ? null : normalizeRemoteOrigin(origin);
+  const from = local ? (oneLine(origin?.relayName) || 'this relay') : (remote?.relayName || 'another relay');
+  const title = local ? local.fullTitle : (remote?.conversationTitle || '');
+  const known = Object.prototype.hasOwnProperty.call(AGENT_EXCHANGE_STATUS_TEXT, status) ? status : 'none';
+  const head = [`note from ${from}`, title].filter(Boolean).join(' · ');
+  const statusText = AGENT_EXCHANGE_STATUS_TEXT[known];
+  return { from, title, status: known, statusText, head, text: `${head} · ${statusText}` };
+}
+
+/**
+ * The folded row's markup: a <details> whose summary is the whole row. Its
+ * body stays empty — the prompt's bubble is its sibling in the prompt's own
+ * node, shown while it is open.
+ */
+export function renderAgentExchangeRowHtml(summary, { escHtml = defaultEscape, timeText = '', open = false } = {}) {
+  return `<details class="agent-exchange-row agent-exchange-${escHtml(summary?.status || 'none')}"${open ? ' open' : ''}>`
+    + `<summary class="agent-exchange-summary" title="${escHtml(summary?.text)}">`
+    + `<span class="agent-exchange-text">${escHtml(summary?.head)}</span>`
+    + `<span class="agent-exchange-status">${escHtml(summary?.statusText)}</span>`
+    + (timeText ? `<span class="agent-exchange-time">${escHtml(timeText)}</span>` : '')
+    + '</summary>'
+    + '</details>';
+}