@brainpilot/web 0.0.8 → 0.0.10

package/src/contexts/SessionContext.tsx

@@ -102,6 +102,25 @@ const SessionContext = createContext<SessionContextValue | null>(null);
 // CONTENT / END leaves old long sessions looking empty.
 const HISTORY_REHYDRATE_LIMIT = 0;
 
+/**
+ * #194-B1: merge the full rehydrated history under whatever the live message
+ * list already holds. On refresh the SSE ring-buffer tail seeds a few recent
+ * messages before history arrives; we must NOT discard the (complete) history
+ * just because the list is non-empty. The persisted history is the base; we
+ * append only the messages already shown that history doesn't contain (by id) —
+ * in-flight optimistic sends, or events newer than the persisted file. Ordering
+ * matters: history first (chronological), then the live-only tail.
+ */
+export function mergeRehydratedMessages(
+  existing: ChatMessage[],
+  history: ChatMessage[],
+): ChatMessage[] {
+  if (existing.length === 0) return history;
+  const historyIds = new Set(history.map((m) => m.id));
+  const extra = existing.filter((m) => !historyIds.has(m.id));
+  return [...history, ...extra];
+}
+
 function foldSessionHistory(events: unknown[], sessionId: string): {
   messages: ChatMessage[];
   trace: TraceGraph | null;
@@ -293,13 +312,18 @@ export function SessionProvider({ children }: { children: ReactNode }) {
         hydratedSessionsRef.current.add(sessionId);
         if (lastUsage) setTokenUsage(lastUsage);
 
-        // Only seed the message list if the user hasn't already started typing
-        // / receiving live SSE for this session in the brief window before
-        // history arrived (otherwise we'd clobber their in-flight messages).
-        setMessagesBySession((current) => {
-          if ((current[sessionId]?.length ?? 0) > 0) return current;
-          return { ...current, [sessionId]: nextMessages };
-        });
+        // Merge the full history under whatever SSE / optimistic messages have
+        // already landed — do NOT bail just because the list is non-empty
+        // (#194-B1). On refresh the SSE ring-buffer tail arrives first and seeds
+        // a few recent messages; the old `length > 0 → skip` guard then dropped
+        // the entire rehydrated history, leaving only those few. The persisted
+        // history is the complete log, so use it as the base and append only the
+        // messages SSE already showed that the history doesn't contain (by id) —
+        // in-flight optimistic sends, or events newer than the persisted file.
+        setMessagesBySession((current) => ({
+          ...current,
+          [sessionId]: mergeRehydratedMessages(current[sessionId] ?? [], nextMessages),
+        }));
         if (nextTrace) {
           setTraceBySession((current) =>
             current[sessionId] ? current : { ...current, [sessionId]: nextTrace! },

package/src/contexts/messageReducer.ts

@@ -171,6 +171,25 @@ export function reduceMessagesForEvent(existing: ChatMessage[], event: WebSocket
       // Strip NO-RENDER wrapper used by record_trace "Message Complete" hint
       delta = delta.replace(/<!--NO-RENDER-->[\s\S]*?<!--\/NO-RENDER-->/g, "");
       if (!delta) return existing;
+      // Orphaned CONTENT (no matching START) — recover gracefully instead of
+      // dropping it. This happens when a demo bundle was exported from a
+      // tail-sliced history: the leading START of the earliest messages is gone,
+      // and a plain `.map` here would no-op, silently swallowing the opening
+      // replies. Synthesize the message so the content still renders.
+      if (!existing.some((m) => m.id === id)) {
+        return [
+          ...existing,
+          {
+            id,
+            role: "assistant",
+            content: delta,
+            createdAt: new Date().toISOString(),
+            agent,
+            streaming: true,
+            kind: "text",
+          },
+        ];
+      }
       return existing.map((m) =>
         m.id === id ? { ...m, content: (m.content ?? "") + delta } : m,
       );

package/src/contracts/backend.ts

@@ -481,7 +481,14 @@ function normalizeStringArray(value: unknown): string[] {
 }
 
 function camelizeKey(key: string): string {
-  return key.replace(/_([a-z])/g, (_, char: string) => char.toUpperCase());
+  // Preserve a leading-underscore prefix: `_ts` / `_seq` are AG-UI transport
+  // metadata whose underscore is significant. Without this guard the regex
+  // turns `_ts` into `Ts`, so `normalizeAgUiEvent` strips the timestamp and the
+  // demo replay's timeline collapses (every event lands at ms=0). Only internal
+  // snake_case boundaries (e.g. `agent_name` → `agentName`) are camelized.
+  const lead = key.match(/^_+/)?.[0] ?? "";
+  const rest = key.slice(lead.length);
+  return lead + rest.replace(/_([a-z])/g, (_, char: string) => char.toUpperCase());
 }
 
 function camelizeObject(value: unknown): unknown {

package/src/i18n/messages/chat.ts

@@ -23,6 +23,8 @@ export default defineMessages(
     "chat.agentsWorking": "{names} 正在工作",
     "chat.aria.stop": "停止生成",
     "chat.stop": "停止",
+    "chat.runningScripts.count": "{count} 个脚本正在运行",
+    "chat.runningScripts.pending": "参数传输中…",
     "chat.aria.newPrompt": "新的研究提问",
     "chat.srAsk": "提出一个研究问题",
     "chat.placeholder": "向 MAS 提问。输入 @ 使用插件或提及文件",
@@ -86,6 +88,8 @@ export default defineMessages(
     "chat.agentsWorking": "{names} are working",
     "chat.aria.stop": "Stop generating",
     "chat.stop": "stop",
+    "chat.runningScripts.count": "{count} script(s) running",
+    "chat.runningScripts.pending": "receiving args…",
     "chat.aria.newPrompt": "New research prompt",
     "chat.srAsk": "Ask a research question",
     "chat.placeholder": "Ask MAS. Type @ to use plugins or mention files",

package/src/i18n/messages/files.ts

@@ -17,6 +17,7 @@ export default defineMessages(
     "files.aria.tree": "文件树",
     "files.selectForDownload": "选择 {name} 以下载",
     "files.error.notRunning": "Sandbox 未运行，无法读取文件。",
+    "files.error.loadFailed": "加载文件列表失败",
     "files.error.downloadFailed": "下载文件失败",
     "files.error.refreshFailed": "刷新文件失败",
     "files.error.previewFailed": "无法预览文件",
@@ -56,6 +57,7 @@ export default defineMessages(
     "files.aria.tree": "File tree",
     "files.selectForDownload": "Select {name} for download",
     "files.error.notRunning": "Sandbox is not running; cannot read files.",
+    "files.error.loadFailed": "Failed to load file list",
     "files.error.downloadFailed": "Failed to download file",
     "files.error.refreshFailed": "Failed to refresh files",
     "files.error.previewFailed": "Unable to preview file",

package/src/i18n/messages/settings.ts

@@ -12,7 +12,34 @@ export default defineMessages(
     "settings.tab.account": "账户",
     "settings.tab.providers": "服务商",
     "settings.tab.mcp": "MCP",
+    "settings.tab.knowledgeBase": "知识库",
     "settings.tab.preferences": "偏好",
+    // knowledge base
+    "settings.kb.title": "本地知识库",
+    "settings.kb.desc": "将 PDF 放入 KnowledgeBase/source/pdf/，然后构建本地 RAG 索引。嵌入模型在本机运行；仅 OCR 与元数据抽取阶段需要联网。",
+    "settings.kb.ocrKey": "SiliconFlow OCR API Key",
+    "settings.kb.metaKey": "元数据抽取 API Key",
+    "settings.kb.metaBaseUrl": "元数据抽取 Base URL",
+    "settings.kb.metaModel": "元数据抽取模型",
+    "settings.kb.reuseAgentKey": "复用 agent 当前的 LLM key 进行元数据抽取",
+    "settings.kb.stages": "要运行的阶段",
+    "settings.kb.start": "构建知识库",
+    "settings.kb.cancel": "取消构建",
+    "settings.kb.progress": "阶段进度",
+    "settings.kb.log": "实时日志",
+    "settings.kb.logEmpty": "尚无构建事件 — 点击「构建知识库」开始。",
+    "settings.kb.error.missingOcrKey": "缺少 SiliconFlow OCR API Key",
+    "settings.kb.error.missingMetaKey": "缺少元数据抽取 API Key（或勾选「复用 agent LLM key」）",
+    "settings.kb.env.title": "Python 运行环境",
+    "settings.kb.env.venvMissing": "尚未为 KnowledgeBase 创建 Python 虚拟环境。点下面按钮一键创建：",
+    "settings.kb.env.setupButton": "一键配置 Python 环境",
+    "settings.kb.env.setupHint": "在 KnowledgeBase/.venv 里创建 venv 并安装 requirements.txt 中的所有依赖（约 2-5 分钟，需联网下载 PyTorch / FlagEmbedding）",
+    "settings.kb.env.reinstallButton": "重建虚拟环境",
+    "settings.kb.env.reinstallHint": "删除现有 .venv 并从头重装所有依赖",
+    "settings.kb.env.cliFallback": "或者也可以在终端手动执行",
+    "settings.kb.env.venvHint": "venv 创建后无需任何额外环境变量配置 —— 构建按钮会自动发现它。如果你想用别的解释器，把绝对路径写到 BP_KB_PYTHON 环境变量里再启动 BrainPilot。",
+    "settings.kb.env.needSetupFirst": "请先点击「一键配置 Python 环境」",
+    "settings.kb.env.busy": "Python 环境配置正在进行中…",
     // account
     "settings.account.title": "账户",
     "settings.account.username": "用户名",
@@ -76,6 +103,8 @@ export default defineMessages(
     "settings.providerForm.models": "模型",
     "settings.providerForm.addModel": "添加模型",
     "settings.providerForm.removeModel": "移除模型",
+    "settings.providerForm.modelsHint":
+      "示例模型仅作占位，保存前请改成你的网关支持的模型，否则发消息时才会报模型不可用。",
     "settings.providerForm.useColor": "使用颜色 {color}",
     "settings.providerForm.color": "颜色",
     "settings.providerForm.cancel": "取消",
@@ -107,7 +136,33 @@ export default defineMessages(
     "settings.tab.account": "Account",
     "settings.tab.providers": "Providers",
     "settings.tab.mcp": "MCP",
+    "settings.tab.knowledgeBase": "Knowledge Base",
     "settings.tab.preferences": "Preferences",
+    "settings.kb.title": "Local Knowledge Base",
+    "settings.kb.desc": "Drop PDFs into KnowledgeBase/source/pdf/, then build a local RAG index. Embedding models run on your machine; only the OCR and metadata-extraction stages call out.",
+    "settings.kb.ocrKey": "SiliconFlow OCR API key",
+    "settings.kb.metaKey": "Metadata-extract API key",
+    "settings.kb.metaBaseUrl": "Metadata-extract base URL",
+    "settings.kb.metaModel": "Metadata-extract model",
+    "settings.kb.reuseAgentKey": "Reuse the agent's active LLM key for metadata extraction",
+    "settings.kb.stages": "Stages to run",
+    "settings.kb.start": "Build Knowledge Base",
+    "settings.kb.cancel": "Cancel build",
+    "settings.kb.progress": "Stage progress",
+    "settings.kb.log": "Live log",
+    "settings.kb.logEmpty": "No build events yet — press \"Build Knowledge Base\" to start.",
+    "settings.kb.error.missingOcrKey": "SiliconFlow OCR API key required",
+    "settings.kb.error.missingMetaKey": "Metadata-extract API key required (or check \"reuse agent LLM key\")",
+    "settings.kb.env.title": "Python environment",
+    "settings.kb.env.venvMissing": "No Python venv set up for KnowledgeBase yet. Click below to create one:",
+    "settings.kb.env.setupButton": "Set up Python environment",
+    "settings.kb.env.setupHint": "Creates KnowledgeBase/.venv and installs everything in requirements.txt (2-5 min; downloads PyTorch + FlagEmbedding)",
+    "settings.kb.env.reinstallButton": "Reinstall venv",
+    "settings.kb.env.reinstallHint": "Remove the existing .venv and reinstall every dependency from scratch",
+    "settings.kb.env.cliFallback": "Or run this in a terminal yourself",
+    "settings.kb.env.venvHint": "Once the venv exists no env vars are needed — the build button auto-detects it. To use a different interpreter, set BP_KB_PYTHON to its absolute path before launching BrainPilot.",
+    "settings.kb.env.needSetupFirst": "Click \"Set up Python environment\" first",
+    "settings.kb.env.busy": "Python environment setup is currently running…",
     "settings.account.title": "Account",
     "settings.account.username": "Username",
     "settings.account.userId": "User ID",
@@ -166,6 +221,8 @@ export default defineMessages(
     "settings.providerForm.models": "Models",
     "settings.providerForm.addModel": "Add model",
     "settings.providerForm.removeModel": "Remove model",
+    "settings.providerForm.modelsHint":
+      "The example model is only a placeholder — replace it with one your gateway supports before saving, or the model will be rejected when you send a message.",
     "settings.providerForm.useColor": "Use color {color}",
     "settings.providerForm.color": "Color",
     "settings.providerForm.cancel": "Cancel",

package/src/styles/global.css

@@ -1683,7 +1683,10 @@ button {
 .prompt-home--active .prompt-home__inner {
   width: min(1040px, 100%);
   height: 100%;
-  grid-template-rows: minmax(0, 1fr) auto auto;
+  /* Rows: message stream (fills) | toast | running-scripts panel | composer.
+   * The two middle rows are optional and collapse to zero when their children
+   * are unmounted (empty child on `auto` row occupies no space). */
+  grid-template-rows: minmax(0, 1fr) auto auto auto;
   align-content: end;
   gap: 16px;
   justify-items: stretch;
@@ -1965,6 +1968,134 @@ button {
   animation: pulse 1.5s infinite;
 }
 
+/* Running-scripts panel — sits directly above the composer while any bash
+ * tool call is streaming. Collapses/expands with a native <details>. Visual
+ * weight matches .agent-running-toast so the two stack cleanly. */
+.running-scripts {
+  justify-self: stretch;
+  width: 100%;
+  margin: 0 0 6px;
+  border: 1px solid var(--color-border);
+  border-radius: 12px;
+  background: var(--color-surface-soft);
+  color: var(--color-text);
+  font-size: 13px;
+  overflow: hidden;
+  animation: fadeSlideIn var(--ease-layout) both;
+}
+.running-scripts > details > summary {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px 8px 14px;
+  cursor: pointer;
+  list-style: none;
+  user-select: none;
+}
+.running-scripts > details > summary::-webkit-details-marker {
+  display: none;
+}
+.running-scripts__dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--color-info);
+  animation: pulse 1.5s infinite;
+  flex: 0 0 auto;
+}
+.running-scripts__chevron {
+  transition: transform var(--ease-standard);
+  flex: 0 0 auto;
+  color: var(--color-text-subtle);
+}
+.running-scripts > details:not([open]) .running-scripts__chevron {
+  transform: rotate(-90deg);
+}
+.running-scripts__label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.running-scripts__stop {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+  height: 22px;
+  padding: 0 9px;
+  border: 1px solid var(--color-border);
+  border-radius: 999px;
+  background: var(--color-surface);
+  color: var(--color-text-muted);
+  font-size: 11px;
+  cursor: pointer;
+  transition:
+    background var(--ease-standard),
+    border-color var(--ease-standard),
+    color var(--ease-standard);
+}
+.running-scripts__stop:hover {
+  background: var(--color-danger-soft);
+  border-color: color-mix(in srgb, var(--color-danger) 40%, var(--color-border));
+  color: var(--color-danger);
+}
+.running-scripts__list {
+  list-style: none;
+  margin: 0;
+  padding: 0 10px 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.running-scripts__item {
+  border: 1px solid var(--color-border);
+  border-radius: 10px;
+  background: var(--color-surface);
+  padding: 8px 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.running-scripts__item-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--color-text-subtle);
+}
+.running-scripts__item-agent {
+  padding: 1px 8px;
+  border-radius: 999px;
+  background: var(--color-hover);
+  color: var(--color-text);
+  font-size: 11px;
+}
+.running-scripts__item-name {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  color: var(--color-text);
+}
+.running-scripts__item-elapsed {
+  margin-left: auto;
+  font-variant-numeric: tabular-nums;
+}
+.running-scripts__cmd {
+  margin: 0;
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: var(--color-surface-raised);
+  color: var(--color-text);
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 12px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow-x: auto;
+  max-height: 180px;
+}
+
 .command-picker {
   position: relative;
 }
@@ -4755,6 +4886,13 @@ button {
   gap: 8px;
 }
 
+.provider-form__models-hint {
+  margin: 8px 0 0;
+  color: var(--color-text-subtle);
+  font-size: 11px;
+  line-height: 1.45;
+}
+
 .provider-model-row {
   display: grid !important;
   grid-template-columns: minmax(0, 1fr) 40px;

package/src/utils/api.ts

@@ -66,13 +66,44 @@ function authHeaders(json = true): Record<string, string> {
   return json ? { "Content-Type": "application/json" } : {};
 }
 
+/**
+ * #206: build a readable message from a Zod issue list. The backend returns
+ * `details: parsed.error.issues` — each issue has a `path` (field) and a
+ * `message`. We render `field: message` per issue so a validation 400 tells the
+ * user *which* field is wrong (empty name, invalid url, …) instead of degrading
+ * to a generic "Request failed (400)".
+ */
+function formatIssues(details: unknown): string | null {
+  if (!Array.isArray(details) || details.length === 0) return null;
+  const parts: string[] = [];
+  for (const issue of details) {
+    if (!issue || typeof issue !== "object") continue;
+    const { path, message } = issue as { path?: unknown; message?: unknown };
+    if (typeof message !== "string" || message.length === 0) continue;
+    const field = Array.isArray(path) ? path.filter((p) => p !== "" && p != null).join(".") : "";
+    parts.push(field ? `${field}: ${message}` : message);
+  }
+  return parts.length > 0 ? parts.join("; ") : null;
+}
+
 async function parseError(res: Response): Promise<string> {
   const contentType = res.headers.get("content-type") || "";
   if (contentType.includes("application/json")) {
-    const body = (await res.json().catch(() => null)) as { detail?: unknown } | null;
-    if (typeof body?.detail === "string") {
+    // #206: the backend uses two shapes — `{ detail }` (single string) and the
+    // Zod validation shape `{ error, details }`. parseError previously read only
+    // `detail`, so every `{ error, details }` 400/409 fell through to the generic
+    // text fallback. Read all three: detail → error(+formatted details) → error.
+    const body = (await res.json().catch(() => null)) as
+      | { detail?: unknown; error?: unknown; details?: unknown }
+      | null;
+    if (typeof body?.detail === "string" && body.detail.length > 0) {
       return body.detail;
     }
+    const issues = formatIssues(body?.details);
+    if (typeof body?.error === "string" && body.error.length > 0) {
+      return issues ? `${body.error} (${issues})` : body.error;
+    }
+    if (issues) return issues;
   }
   const text = await res.text().catch(() => "");
   return text || `Request failed (${res.status})`;
@@ -123,6 +154,20 @@ export const api = {
     return handleJson(await apiFetch(`${API_BASE}/version`));
   },
 
+  // #156: real on-disk paths for the Files panel (local mode only). Hosted
+  // backends return `{ localMode: false }` with no host path. Best-effort:
+  // any failure resolves to a non-local shape so callers fall back cleanly.
+  async getInfo(): Promise<{ localMode: boolean; dataDir?: string; workspacesRoot?: string }> {
+    if (runtimeConfig.useMockBackend) {
+      return { localMode: false };
+    }
+    try {
+      return await handleJson(await apiFetch(`${API_BASE}/info`));
+    } catch {
+      return { localMode: false };
+    }
+  },
+
   auth: {
     async me(): Promise<User> {
       if (runtimeConfig.useMockBackend) {
@@ -505,7 +550,14 @@ export const api = {
         `${API_BASE}/sessions/${sessionId}/history${qs}`,
         { headers: authHeaders() },
       );
-      if (!res.ok) return { events: [], total: 0, truncated: false };
+      // A 404 means the session has no transcript on disk (genuinely empty) —
+      // return an empty history. Any OTHER non-OK status is a real failure
+      // (routing / storage / auth); surface it instead of silently rendering an
+      // empty transcript, which historically masked broken rehydrates (#223).
+      if (res.status === 404) return { events: [], total: 0, truncated: false };
+      if (!res.ok) {
+        throw new Error(`history fetch failed: ${res.status} ${res.statusText}`);
+      }
       const raw = (await res.json().catch(() => null)) as
         | { events?: unknown[]; total?: number; truncated?: boolean }
         | null;
@@ -721,4 +773,88 @@ export const api = {
       return normalizeProviderProfile(raw as Parameters<typeof normalizeProviderProfile>[0]);
     },
   },
+
+  // Knowledge Base — local pipeline build orchestration.
+  // Mirrors the backend /api/kb/* routes. The SSE event stream is consumed
+  // directly via `new EventSource()` in the panel component (so it can stay
+  // attached for the lifetime of the dialog), so we don't expose a helper
+  // here for it.
+  kb: {
+    async build(opts: {
+      ocrApiKey?: string;
+      metaApiKey?: string;
+      metaBaseUrl?: string;
+      metaModel?: string;
+      kbRoot?: string;
+      ocrConcurrency?: number;
+      ocrLimit?: number;
+      skip?: Array<"ocr" | "extract" | "chunk" | "vectorize">;
+      only?: Array<"ocr" | "extract" | "chunk" | "vectorize">;
+    }): Promise<{ ok: boolean; startedAt?: number; error?: string }> {
+      const res = await apiFetch(`${API_BASE}/kb/build`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(opts),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        return { ok: false, error: body.error || `kb build failed (${res.status})` };
+      }
+      return handleJson(res);
+    },
+
+    async status(): Promise<{
+      active: boolean;
+      startedAt: number | null;
+      finishedAt: number | null;
+      exitCode: number | null | undefined;
+      error?: string;
+      recentEvents: Array<{
+        ts: string;
+        stage: string;
+        event: string;
+        msg: string;
+        [k: string]: unknown;
+      }>;
+      environment: {
+        python: string;
+        pythonIsVenv: boolean;
+        venvExists: boolean;
+        expectedVenvPath: string;
+        scriptsPresent: boolean;
+        kbRoot: string;
+      };
+    }> {
+      return handleJson(await apiFetch(`${API_BASE}/kb/status`));
+    },
+
+    async cancel(): Promise<{ ok: boolean; message?: string }> {
+      const res = await apiFetch(`${API_BASE}/kb/cancel`, { method: "POST" });
+      return res.json().catch(() => ({ ok: false }));
+    },
+
+    // Bootstrap the Python venv (KnowledgeBase/.venv) before the first
+    // build can run. Streams progress on the same SSE channel as `build`,
+    // so the panel only needs one EventSource subscription.
+    async setupEnv(opts: {
+      python?: string;
+      reinstall?: boolean;
+      kbRoot?: string;
+    } = {}): Promise<{ ok: boolean; startedAt?: number; error?: string }> {
+      const res = await apiFetch(`${API_BASE}/kb/setup-env`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(opts),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        return { ok: false, error: body.error || `setup-env failed (${res.status})` };
+      }
+      return handleJson(res);
+    },
+
+    eventsUrl(): string {
+      return `${API_BASE}/kb/events`;
+    },
+  },
 };

package/src/utils/format.ts

@@ -5,3 +5,12 @@ export function formatBytes(bytes: number) {
   const value = bytes / 1024 ** index;
   return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${units[index]}`;
 }
+
+/** Compact elapsed formatter: "3.2s" under a minute, "1m 05s" above. */
+export function formatElapsed(ms: number): string {
+  const totalSeconds = Math.max(0, ms) / 1000;
+  if (totalSeconds < 60) return `${totalSeconds.toFixed(1)}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = Math.floor(totalSeconds % 60);
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}