@circuitwall/jarela 2.4.0 → 2.5.0

package/contexts/ThemeContext.tsx

@@ -2,13 +2,25 @@
 import { createContext, useCallback, useContext, useEffect, useState, type ReactNode } from "react";
 
 export type Theme = "light" | "dark" | "system";
+export type AccentColor = "default" | "blue" | "teal" | "violet" | "rose";
+export type SurfaceStyle = "ambient" | "calm" | "liquid";
 
 const STORAGE_KEY = "jarela-theme";
+const ACCENT_STORAGE_KEY = "jarela-accent-color";
+const SURFACE_STORAGE_KEY = "jarela-surface-style";
 
 function isTheme(v: unknown): v is Theme {
   return v === "light" || v === "dark" || v === "system";
 }
 
+function isAccentColor(v: unknown): v is AccentColor {
+  return v === "default" || v === "blue" || v === "teal" || v === "violet" || v === "rose";
+}
+
+function isSurfaceStyle(v: unknown): v is SurfaceStyle {
+  return v === "ambient" || v === "calm" || v === "liquid";
+}
+
 function readStored(): Theme {
   if (typeof window === "undefined") return "system";
   try {
@@ -19,6 +31,26 @@ function readStored(): Theme {
   }
 }
 
+function readStoredAccent(): AccentColor {
+  if (typeof window === "undefined") return "blue";
+  try {
+    const value = window.localStorage.getItem(ACCENT_STORAGE_KEY);
+    return isAccentColor(value) ? value : "default";
+  } catch {
+    return "default";
+  }
+}
+
+function readStoredSurface(): SurfaceStyle {
+  if (typeof window === "undefined") return "ambient";
+  try {
+    const value = window.localStorage.getItem(SURFACE_STORAGE_KEY);
+    return isSurfaceStyle(value) ? value : "ambient";
+  } catch {
+    return "ambient";
+  }
+}
+
 const LIGHT_CHROME = "#ffffff";
 const DARK_CHROME = "#09090b";
 
@@ -44,9 +76,27 @@ function apply(theme: Theme) {
   syncChrome(theme);
 }
 
+function applyAccentColor(accentColor: AccentColor) {
+  if (typeof document === "undefined") return;
+  if (accentColor === "default") {
+    document.documentElement.removeAttribute("data-accent-color");
+    return;
+  }
+  document.documentElement.setAttribute("data-accent-color", accentColor);
+}
+
+function applySurfaceStyle(surfaceStyle: SurfaceStyle) {
+  if (typeof document === "undefined") return;
+  document.documentElement.setAttribute("data-surface-style", surfaceStyle);
+}
+
 interface Ctx {
   theme: Theme;
   setTheme: (t: Theme) => void;
+  accentColor: AccentColor;
+  setAccentColor: (color: AccentColor) => void;
+  surfaceStyle: SurfaceStyle;
+  setSurfaceStyle: (style: SurfaceStyle) => void;
 }
 
 const ThemeContext = createContext<Ctx | null>(null);
@@ -56,10 +106,18 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
   // which writes data-theme before React hydrates. The effect below syncs the
   // React state to whatever the script (or localStorage) decided.
   const [theme, setThemeState] = useState<Theme>("system");
+  const [accentColor, setAccentColorState] = useState<AccentColor>("blue");
+  const [surfaceStyle, setSurfaceStyleState] = useState<SurfaceStyle>("ambient");
 
   useEffect(() => {
     const stored = readStored();
+    const storedAccent = readStoredAccent();
+    const storedSurface = readStoredSurface();
     setThemeState(stored);
+    setAccentColorState(storedAccent);
+    setSurfaceStyleState(storedSurface);
+    applyAccentColor(storedAccent);
+    applySurfaceStyle(storedSurface);
     // When in "system" mode, mirror OS-level changes into the PWA chrome.
     if (typeof window === "undefined") return;
     const mq = window.matchMedia("(prefers-color-scheme: dark)");
@@ -80,7 +138,32 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
     }
   }, []);
 
-  return <ThemeContext.Provider value={{ theme, setTheme }}>{children}</ThemeContext.Provider>;
+  const setAccentColor = useCallback((color: AccentColor) => {
+    setAccentColorState(color);
+    applyAccentColor(color);
+    try {
+      if (color === "default") window.localStorage.removeItem(ACCENT_STORAGE_KEY);
+      else window.localStorage.setItem(ACCENT_STORAGE_KEY, color);
+    } catch {
+      /* ignore quota / private-mode errors */
+    }
+  }, []);
+
+  const setSurfaceStyle = useCallback((style: SurfaceStyle) => {
+    setSurfaceStyleState(style);
+    applySurfaceStyle(style);
+    try {
+      window.localStorage.setItem(SURFACE_STORAGE_KEY, style);
+    } catch {
+      /* ignore quota / private-mode errors */
+    }
+  }, []);
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme, accentColor, setAccentColor, surfaceStyle, setSurfaceStyle }}>
+      {children}
+    </ThemeContext.Provider>
+  );
 }
 
 export function useTheme() {

package/hooks/useAgentSession.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { renderHook, waitFor } from "@testing-library/react";
+import { act, renderHook, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useAgentSession } from "@/hooks/useAgentSession";
 
@@ -11,6 +11,7 @@ vi.mock("@/api/client", () => ({
   api: {
     threads: {
       get: (...args: unknown[]) => threadGetMock(...args),
+      metadata: (...args: unknown[]) => threadGetMock(...args),
     },
     agents: {
       getThread: (...args: unknown[]) => agentGetThreadMock(...args),
@@ -35,5 +36,15 @@ describe("useAgentSession contract", () => {
     expect(result.current.loading).toBe(result.current.state.loading);
     expect(result.current.refresh).toBe(result.current.commands.refresh);
     expect(agentGetThreadMock).not.toHaveBeenCalled();
+    expect(threadGetMock).toHaveBeenCalledWith("preferred-thread", { startup: true });
+  });
+
+  it("uses the startup handoff initially but keeps explicit refreshes fresh", async () => {
+    agentGetThreadMock.mockResolvedValue({ thread_id: "thread" });
+    const { result } = renderHook(() => useAgentSession("agent"));
+    await waitFor(() => expect(result.current.threadId).toBe("thread"));
+    expect(agentGetThreadMock).toHaveBeenLastCalledWith("agent", { startup: true });
+    await act(async () => { await result.current.refresh(); });
+    expect(agentGetThreadMock).toHaveBeenLastCalledWith("agent", undefined);
   });
 });

package/hooks/useAgentSession.ts

@@ -15,7 +15,7 @@ export function useAgentSession(
   const [error, setError] = useState<string | null>(null);
   const requestSeqRef = useRef(0);
 
-  const refresh = useCallback(async () => {
+  const refresh = useCallback(async (opts?: { startup?: boolean }) => {
     if (!agentId) {
       setThreadId(null);
       setError(null);
@@ -32,7 +32,9 @@ export function useAgentSession(
       // prefer it as long as it still belongs to this agent.
       if (preferredThreadId) {
         try {
-          const d = await api.threads.get(preferredThreadId, { limit: 1 });
+          const d = opts?.startup
+            ? await api.threads.get(preferredThreadId, { startup: true })
+            : await api.threads.metadata(preferredThreadId);
           if (mySeq !== requestSeqRef.current) return;
           if (d.agent_id === agentId) {
             setThreadId(preferredThreadId);
@@ -43,7 +45,7 @@ export function useAgentSession(
         }
       }
 
-      const t = await api.agents.getThread(agentId);
+      const t = await api.agents.getThread(agentId, opts);
       if (mySeq !== requestSeqRef.current) return;
       setThreadId(t.thread_id);
     } catch (err) {
@@ -70,7 +72,7 @@ export function useAgentSession(
       return;
     }
 
-    void refresh();
+    void refresh({ startup: true });
 
   }, [agentId, preferredThreadId, refresh]);
 

package/hooks/useUrlSync.test.ts

@@ -30,4 +30,17 @@ describe("useUrlSync contract", () => {
       replaceStateSpy.mockRestore();
     });
   });
+
+  it.each([
+    "/?tab=documents",
+    "/?tab=tools&item=documents",
+    "/?tab=tools&item=memory",
+  ])("routes legacy Knowledge URL %s to the Advanced Knowledge panel", async (url) => {
+    window.history.replaceState(null, "", url);
+    renderHook(() => useUrlSync(), { wrapper });
+
+    await waitFor(() => {
+      expect(window.location.search).toBe("?tab=memory");
+    });
+  });
 });

package/hooks/useUrlSync.ts

@@ -38,10 +38,6 @@ export function useUrlSync(): UnifiedHookResult<
       tab = "tools";
       item = "packages";
     }
-    if (tab === "documents" || tab === "memory") {
-      tab = "tools";
-      item = "memory";
-    }
     // Browser-extension "Open Jarela" passes ?agent=<id> (and optionally
     // ?thread=<id>) so the app lands on the user's currently-picked
     // target agent instead of whichever chat was last open. The agent

package/lib/db/migrations.test.ts

@@ -18,6 +18,67 @@ afterAll(() => {
   try { rmSync(tmpRoot, { recursive: true, force: true }); } catch {}
 });
 
+describe("responsive transcript indexes (ADR-0103)", () => {
+  it("restores missing indexes on upgrade and remains idempotent", async () => {
+    const db = getDb();
+    const names = [
+      "idx_messages_thread_seq", "idx_messages_created_at",
+      "idx_threads_updated", "idx_message_usage_thread_created",
+      "idx_memory_namespace_updated", "idx_memory_updated",
+      "idx_runtime_operations_thread_state", "idx_signal_events_thread",
+      "idx_signal_events_operation", "idx_signal_deliveries_lease",
+      "idx_background_results_expiry", "idx_message_embedding_jobs_lease",
+    ];
+    for (const name of names) db.exec(`DROP INDEX IF EXISTS ${name}`);
+    const { runMigrations } = await import("./migrations");
+    runMigrations(db);
+    runMigrations(db);
+    const indexes = db.prepare("SELECT name FROM sqlite_master WHERE type='index'").all()
+      .map((row) => row.name);
+    expect(indexes).toEqual(expect.arrayContaining(names));
+  });
+
+  it.each([
+    ["SELECT rowid, msg_id, content FROM messages WHERE thread_id=? ORDER BY rowid DESC LIMIT ?", ["thread", 51]],
+    ["SELECT rowid, msg_id, content FROM messages WHERE thread_id=? AND rowid<? ORDER BY rowid DESC LIMIT ?", ["thread", 100, 51]],
+    ["SELECT rowid, msg_id, content FROM messages WHERE thread_id=? AND rowid>? ORDER BY rowid ASC LIMIT ?", ["thread", 100, 50]],
+    ["SELECT content FROM messages WHERE created_at>=? ORDER BY created_at ASC", ["2026-10-01"]],
+    ["SELECT * FROM threads WHERE agent_id=? ORDER BY updated_at DESC LIMIT ?", ["agent", 50]],
+    ["SELECT * FROM threads ORDER BY updated_at DESC LIMIT ? OFFSET ?", [50, 0]],
+  ])("uses ordered indexes for %s", (query, params) => {
+    const plan = getDb().prepare(`EXPLAIN QUERY PLAN ${query}`).all(...params)
+      .map((row) => String(row.detail)).join("; ");
+    expect(plan).not.toMatch(/USE TEMP B-TREE|SCAN (?:messages|threads)(?! USING INDEX)/);
+    expect(plan).toMatch(/USING INDEX/);
+  });
+
+  it.each([
+    ["SELECT * FROM message_usage WHERE thread_id=? ORDER BY created_at DESC LIMIT 1", ["thread"], "idx_message_usage_thread_created"],
+    ["SELECT namespace,key,value FROM memory_store WHERE namespace=? ORDER BY updated_at DESC LIMIT ?", ["facts", 50], "idx_memory_namespace_updated"],
+    ["SELECT namespace,key,value FROM memory_store ORDER BY updated_at DESC LIMIT ?", [50], "idx_memory_updated"],
+    ["SELECT rowid FROM runtime_operations WHERE thread_id=? AND state='accepted'", ["thread"], "idx_runtime_operations_thread_state"],
+    ["SELECT rowid FROM signal_events WHERE thread_id=?", ["thread"], "idx_signal_events_thread"],
+    ["SELECT rowid FROM signal_events WHERE operation_id=?", ["operation"], "idx_signal_events_operation"],
+    ["SELECT key FROM background_tool_results WHERE expires_at<=?", [1000], "idx_background_results_expiry"],
+    ["SELECT event_id FROM signal_deliveries WHERE state='leased' AND lease_until<=?", [1000], "idx_signal_deliveries_lease"],
+    ["SELECT message_id FROM message_embedding_jobs WHERE state='processing' AND lease_until_ms<=?", [1000], "idx_message_embedding_jobs_lease"],
+  ])("indexes secondary lookup %s", (query, params, index) => {
+    const plan = getDb().prepare(`EXPLAIN QUERY PLAN ${query}`).all(...params)
+      .map((row) => String(row.detail)).join("; ");
+    expect(plan).not.toMatch(/USE TEMP B-TREE/);
+    expect(plan).toContain(index);
+    if (!query.includes("FROM memory_store ORDER BY")) expect(plan).toContain("SEARCH");
+  });
+
+  it("reuses the unique agent index instead of adding a redundant ordering index", () => {
+    const indexes = getDb().prepare("PRAGMA index_list(threads)").all();
+    expect(indexes).toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "idx_threads_agent_id", unique: 1 }),
+    ]));
+    expect(indexes.some((row) => row.name === "idx_threads_agent_updated")).toBe(false);
+  });
+});
+
 describe("warm summary limit migration", () => {
   it("adds the default limit to existing agents", async () => {
     const db = getDb();

package/lib/db/migrations.ts

@@ -35,6 +35,9 @@ export function runMigrations(db: DatabaseSync): void {
     -- (getMessages, getRecentMessagesWindow, getMessagesPage, clear).
     -- Without this every read full-scans the messages table.
     CREATE INDEX IF NOT EXISTS idx_messages_thread_id ON messages(thread_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_messages_thread_seq ON messages(thread_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_created_at ON messages(created_at);
+    CREATE INDEX IF NOT EXISTS idx_threads_updated ON threads(updated_at DESC);
     CREATE TABLE IF NOT EXISTS runtime_operations (
       id TEXT PRIMARY KEY,
       kind TEXT NOT NULL,
@@ -58,6 +61,9 @@ export function runMigrations(db: DatabaseSync): void {
       created_at INTEGER NOT NULL,
       UNIQUE(kind,operation_id,agent_id,thread_id)
     );
+    CREATE INDEX IF NOT EXISTS idx_runtime_operations_thread_state ON runtime_operations(thread_id,state);
+    CREATE INDEX IF NOT EXISTS idx_signal_events_thread ON signal_events(thread_id);
+    CREATE INDEX IF NOT EXISTS idx_signal_events_operation ON signal_events(operation_id);
     CREATE TABLE IF NOT EXISTS signal_deliveries (
       event_id TEXT PRIMARY KEY REFERENCES signal_events(id) ON DELETE CASCADE,
       wake_eligible INTEGER NOT NULL DEFAULT 0,
@@ -72,6 +78,7 @@ export function runMigrations(db: DatabaseSync): void {
     );
     CREATE INDEX IF NOT EXISTS idx_signal_events_target ON signal_events(agent_id,thread_id,seq);
     CREATE INDEX IF NOT EXISTS idx_signal_deliveries_due ON signal_deliveries(state,available_at);
+    CREATE INDEX IF NOT EXISTS idx_signal_deliveries_lease ON signal_deliveries(state,lease_until);
     CREATE TABLE IF NOT EXISTS background_tool_results (
       key TEXT PRIMARY KEY REFERENCES runtime_operations(id) ON DELETE CASCADE,
       thread_id TEXT NOT NULL REFERENCES threads(thread_id) ON DELETE CASCADE,
@@ -83,6 +90,7 @@ export function runMigrations(db: DatabaseSync): void {
       expires_at INTEGER NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_background_results_owner ON background_tool_results(thread_id,expires_at);
+    CREATE INDEX IF NOT EXISTS idx_background_results_expiry ON background_tool_results(expires_at);
     CREATE TABLE IF NOT EXISTS memory_store (
       namespace  TEXT NOT NULL,
       key        TEXT NOT NULL,
@@ -91,6 +99,8 @@ export function runMigrations(db: DatabaseSync): void {
       updated_at TEXT NOT NULL,
       PRIMARY KEY (namespace, key)
     );
+    CREATE INDEX IF NOT EXISTS idx_memory_namespace_updated ON memory_store(namespace,updated_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_updated ON memory_store(updated_at DESC);
     CREATE TABLE IF NOT EXISTS model_configs (
       name       TEXT PRIMARY KEY,
       provider   TEXT NOT NULL,
@@ -660,6 +670,7 @@ function ensureMessageUsageTable(db: DatabaseSync): void {
     );
     CREATE INDEX IF NOT EXISTS idx_message_usage_created_at ON message_usage(created_at);
     CREATE INDEX IF NOT EXISTS idx_message_usage_agent_id   ON message_usage(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_message_usage_thread_created ON message_usage(thread_id,created_at DESC);
   `);
 }
 
@@ -703,6 +714,8 @@ function ensureMessageEmbeddingJobsTable(db: DatabaseSync): void {
     );
     CREATE INDEX IF NOT EXISTS idx_message_embedding_jobs_due
       ON message_embedding_jobs(state, available_at_ms, lease_until_ms);
+    CREATE INDEX IF NOT EXISTS idx_message_embedding_jobs_lease
+      ON message_embedding_jobs(state, lease_until_ms);
     INSERT OR IGNORE INTO message_embedding_jobs (message_id, created_at, updated_at)
       SELECT msg_id, created_at, created_at FROM messages WHERE embedding IS NULL;
   `);

package/lib/embeddings/performance.test.ts

@@ -0,0 +1,114 @@
+import { DatabaseSync } from "node:sqlite";
+import { performance } from "node:perf_hooks";
+import { afterAll, expect, it, vi } from "vitest";
+import { LOCAL_EMBEDDING_MODEL_ID } from "./constants";
+
+// Opt-in, local-only benchmark. No user database, credentials, or downloads.
+const state = vi.hoisted(() => ({ db: null as DatabaseSync | null }));
+vi.mock("@/lib/db", () => ({
+  getDb: () => {
+    if (!state.db) throw new Error("benchmark database not initialized");
+    return state.db;
+  },
+}));
+vi.mock("@/lib/providers", () => ({
+  getProvider: () => { throw new Error("remote providers are forbidden in this benchmark"); },
+}));
+vi.mock("@/lib/stores/model-config", () => ({
+  getModelConfig: () => null,
+  getDefaultModelConfig: () => null,
+  getModelParams: () => ({}),
+  listModelConfigs: () => [],
+}));
+
+const previousDownload = process.env.JARELA_LOCAL_EMBEDDING_DOWNLOAD;
+afterAll(() => {
+  state.db?.close();
+  if (previousDownload === undefined) delete process.env.JARELA_LOCAL_EMBEDDING_DOWNLOAD;
+  else process.env.JARELA_LOCAL_EMBEDDING_DOWNLOAD = previousDownload;
+});
+
+it.skipIf(process.env.JARELA_BENCHMARK_EMBEDDINGS !== "1")(
+  "reports local embedding and synthetic memory-search latency",
+  async () => {
+    process.env.JARELA_LOCAL_EMBEDDING_DOWNLOAD = "0";
+    const { getLocalModelStatus } = await import("./local-model");
+    expect(getLocalModelStatus().state, "Install the local model before running this offline benchmark").toBe("ready");
+    const { runMigrations } = await import("@/lib/db/migrations");
+    state.db = new DatabaseSync(":memory:");
+    runMigrations(state.db);
+    const { setLocalEmbeddingsEnabled, setEmbeddingVectorsSignature } = await import("@/lib/stores/app-settings");
+    setLocalEmbeddingsEnabled(true);
+    setEmbeddingVectorsSignature(LOCAL_EMBEDDING_MODEL_ID);
+    const { embedLocally } = await import("./local");
+    const { embedQueryOne, searchMemory, _resetEmbeddingCache, _resetEmbedCaches, reembedStaleVectors } = await import("./index");
+    const results: Array<{ operation: string; samples: number; median_ms: number; p95_ms: number }> = [];
+    async function time(operation: string, count: number, run: (index: number) => Promise<void>) {
+      const elapsed: number[] = [];
+      for (let i = 0; i < count; i++) {
+        const start = performance.now();
+        await run(i);
+        elapsed.push(performance.now() - start);
+      }
+      elapsed.sort((a, b) => a - b);
+      results.push({
+        operation, samples: count,
+        median_ms: Number(elapsed[Math.floor(elapsed.length / 2)].toFixed(3)),
+        p95_ms: Number(elapsed[Math.ceil(elapsed.length * 0.95) - 1].toFixed(3)),
+      });
+    }
+    const query = "What is the deployment rollback procedure?";
+    const validate = (vector: number[] | null) => {
+      expect(vector).toHaveLength(384);
+      expect(vector?.every(Number.isFinite)).toBe(true);
+    };
+    await time("cold pipeline + first query inference", 1, async () => {
+      validate((await embedLocally([query], "query"))[0]);
+    });
+    await time("warm pipeline, uncached short query", 10, async (i) => {
+      validate((await embedLocally([`${query} revision ${i}`], "query"))[0]);
+    });
+    await time("warm pipeline, 16 short passages", 3, async () => {
+      const vectors = await embedLocally(Array.from({ length: 16 }, (_, i) => `Deployment step ${i}: preserve backups and verify health.`), "passage");
+      expect(vectors).toHaveLength(16);
+      vectors.forEach(validate);
+    });
+    await embedQueryOne(query);
+    await time("query embedding content-cache hit", 20, async () => { validate(await embedQueryOne(query)); });
+    const vector = await embedQueryOne(query);
+    const encoded = JSON.stringify(vector);
+    const db = state.db;
+    db.prepare("INSERT INTO threads(thread_id,agent_id,created_at,updated_at) VALUES ('bench','bench',?,?)")
+      .run("2026-01-01", "2026-01-01");
+    const memory = db.prepare("INSERT INTO memory_store(namespace,key,value,created_at,updated_at,embedding) VALUES ('benchmark',?,?,?,?,?)");
+    const message = db.prepare("INSERT INTO messages(msg_id,thread_id,role,content,created_at,embedding) VALUES (?,'bench','assistant',?,?,?)");
+    const job = db.prepare("INSERT INTO message_embedding_jobs(message_id,source_hash,state,created_at,updated_at,model_signature) VALUES (?,?,'done','2026-01-01','2026-01-01',?)");
+    for (const rows of [1_000, 10_000]) {
+      db.exec("DELETE FROM memory_store WHERE namespace='benchmark'; DELETE FROM message_embedding_jobs; DELETE FROM messages; BEGIN");
+      for (let i = 0; i < rows / 2; i++) {
+        const content = `Synthetic deployment rollback procedure ${i}: restore backup, verify health, then resume traffic.`;
+        memory.run(`key-${i}`, content, "2026-01-01", "2026-01-01", encoded);
+        message.run(`msg-${i}`, content, "2026-01-01", encoded);
+        job.run(`msg-${i}`, "synthetic", LOCAL_EMBEDDING_MODEL_ID);
+      }
+      db.exec("COMMIT");
+      _resetEmbedCaches();
+      await time(`${rows} vectors: first search, cold row cache`, 1, async () => {
+        const hits = await searchMemory(query, { literal: true, limit: 10 });
+        expect(hits).toHaveLength(10);
+      });
+      await reembedStaleVectors(384);
+      await time(`${rows} vectors: warm rows + cached query`, 10, async () => {
+        expect(await searchMemory(query, { literal: true, limit: 10 })).toHaveLength(10);
+      });
+      await time(`${rows} vectors: warm rows + new query inference`, 5, async (i) => {
+        _resetEmbeddingCache();
+        expect(await searchMemory(`${query} check ${i}`, { literal: true, limit: 10 })).toHaveLength(10);
+      });
+      await reembedStaleVectors(384);
+    }
+    console.table(results);
+    console.log("Synthetic repeated 384-dimensional vectors; measures scan/sort cost, not retrieval quality. No HTTP transport or provider network latency.");
+  },
+  120_000,
+);

package/lib/stores/dashboard-metrics-cache.test.ts

@@ -0,0 +1,99 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DatabaseSync } from "node:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-test-dashboard-cache-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+const { getDb, closeDb, DB_PATH } = await import("@/lib/db");
+const { getDashboardMetrics } = await import("./dashboard-metrics");
+const { recordMessageUsage } = await import("./message-usage");
+const { getPricingTables } = await import("./pricing");
+const pricing = await import("./pricing");
+
+beforeEach(() => {
+  const db = getDb();
+  db.exec("DELETE FROM message_usage; DELETE FROM messages; DELETE FROM threads;");
+  const now = new Date().toISOString();
+  db.prepare("INSERT INTO threads(thread_id, agent_id, created_at, updated_at) VALUES (?,?,?,?)")
+    .run("t1", "a1", now, now);
+  db.prepare("INSERT INTO messages(msg_id, thread_id, role, content, created_at) VALUES (?,?,?,?,?)")
+    .run("m1", "t1", "assistant", "  legacy estimate  ", now);
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+afterAll(() => {
+  closeDb();
+  rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("dashboard metrics cache", () => {
+  it("reuses a result only while the data, pricing, and window are unchanged", async () => {
+    const first = await getDashboardMetrics(30);
+    expect(await getDashboardMetrics(30)).toBe(first);
+    expect(first.summary.output_tokens_est).toBe(4);
+    expect(await getDashboardMetrics(7)).not.toBe(first);
+  });
+
+  it("invalidates immediately after local writes", async () => {
+    const first = await getDashboardMetrics();
+    getDb().prepare("UPDATE messages SET content=? WHERE msg_id=?").run("a".repeat(100), "m1");
+    const next = await getDashboardMetrics();
+    expect(next).not.toBe(first);
+    expect(next.summary.output_tokens_est).toBe(25);
+  });
+
+  it("invalidates for writes through another connection", async () => {
+    const first = await getDashboardMetrics();
+    const writer = new DatabaseSync(DB_PATH);
+    try {
+      writer.prepare("UPDATE messages SET content=? WHERE msg_id=?").run("b".repeat(80), "m1");
+      const next = await getDashboardMetrics();
+      expect(next).not.toBe(first);
+      expect(next.summary.output_tokens_est).toBe(20);
+    } finally {
+      writer.close();
+    }
+  });
+
+  it("expires after five seconds and across UTC day boundaries", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-10-18T23:59:59.000Z"));
+    const first = await getDashboardMetrics();
+    vi.setSystemTime(new Date("2026-10-19T00:00:00.000Z"));
+    const nextDay = await getDashboardMetrics();
+    expect(nextDay).not.toBe(first);
+    vi.advanceTimersByTime(5000);
+    expect(await getDashboardMetrics()).not.toBe(nextDay);
+  });
+
+  it("invalidates when pricing tables change", async () => {
+    const first = await getDashboardMetrics();
+    const tables = getPricingTables();
+    vi.spyOn(pricing, "getPricingTables").mockReturnValue({ ...tables });
+    expect(await getDashboardMetrics()).not.toBe(first);
+  });
+
+  it("preserves snapshot tokens, costs, and tool counts without needing the body", async () => {
+    getDb().prepare("UPDATE messages SET content=?, tool_events=? WHERE msg_id='m1'")
+      .run("x".repeat(100_000), JSON.stringify([
+        { id: "call1", phase: "call", name: "test", payload: {} },
+        { id: "call1", phase: "result", name: "test", payload: { ok: true } },
+      ]));
+    recordMessageUsage({
+      message_id: "m1", thread_id: "t1", agent_id: "a1", agent_name: "Synthetic",
+      provider: "synthetic", model_id: "synthetic", model_config_name: null,
+      input_tokens: 100, output_tokens: 20, input_rate_usd_per_mtok: null,
+      output_rate_usd_per_mtok: null, cost_usd: 0.5,
+    });
+    const data = await getDashboardMetrics();
+    expect(data.summary).toMatchObject({
+      input_tokens_est: 100, output_tokens_est: 20,
+      recorded_cost_usd: 0.5, tool_calls: 1, tool_successes: 1,
+    });
+    expect(data.summary.data_quality.measured_messages).toBe(1);
+  });
+});

package/lib/stores/dashboard-metrics.ts

@@ -12,6 +12,16 @@ import {
 
 const CHARS_PER_TOKEN = 4;
 const DEFAULT_WINDOW_DAYS = 30;
+const METRICS_CACHE_MS = 5_000;
+
+let metricsCache: {
+  db: ReturnType<typeof getDb>;
+  changes: number;
+  dataVersion: number;
+  tables: PricingTables;
+  createdAt: number;
+  metrics: DashboardMetrics;
+} | null = null;
 
 export interface DashboardTierTokens {
   hot_tokens: number;
@@ -256,10 +266,25 @@ export async function getDashboardMetrics(days = DEFAULT_WINDOW_DAYS): Promise<D
   const now = new Date();
   const boundedDays = Number.isFinite(days) ? Math.min(120, Math.max(7, Math.floor(days))) : DEFAULT_WINDOW_DAYS;
   const since = new Date(now.getTime() - (boundedDays * 24 * 60 * 60 * 1000)).toISOString();
+  const db = getDb();
+  const tables = getPricingTables();
+  // total_changes covers this connection; data_version covers other writers.
+  const { changes } = db.prepare("SELECT total_changes() AS changes").get() as { changes: number };
+  const { data_version: dataVersion } = db.prepare("PRAGMA data_version").get() as { data_version: number };
+  if (metricsCache?.db === db && metricsCache.changes === changes
+    && metricsCache.dataVersion === dataVersion && metricsCache.tables === tables
+    && metricsCache.metrics.days === boundedDays
+    && metricsCache.metrics.generated_at.slice(0, 10) === now.toISOString().slice(0, 10)
+    && now.getTime() - metricsCache.createdAt >= 0
+    && now.getTime() - metricsCache.createdAt < METRICS_CACHE_MS) {
+    return metricsCache.metrics;
+  }
 
-  const usageRows = getDb()
+  const usageRows = db
     .prepare(
-      `SELECT m.created_at, m.role, m.content, m.tool_events, m.thread_id, t.agent_id,
+      `SELECT m.created_at, m.role,
+              CASE WHEN mu.input_tokens IS NULL THEN m.content ELSE '' END AS content,
+              m.tool_events, m.thread_id, t.agent_id,
               a.name AS agent_name, mc.provider AS provider,
               mc.model_id AS model_id,
                   COALESCE(ta.model_config_name, a.model_config_name, dmc.name) AS model_config_name,
@@ -313,7 +338,6 @@ export async function getDashboardMetrics(days = DEFAULT_WINDOW_DAYS): Promise<D
     }
   }
 
-  const tables = getPricingTables();
   const { byProvider, generatedAt } = tables;
   const dayMap = seedDayBuckets(now, boundedDays);
   const agentMap = new Map<string, AgentBucket>();
@@ -645,7 +669,7 @@ export async function getDashboardMetrics(days = DEFAULT_WINDOW_DAYS): Promise<D
     };
   }
 
-  return {
+  const metrics: DashboardMetrics = {
     generated_at: now.toISOString(),
     days: boundedDays,
     summary: {
@@ -701,6 +725,8 @@ export async function getDashboardMetrics(days = DEFAULT_WINDOW_DAYS): Promise<D
       notes: "Dashboard cost is recalculated from captured provider token usage and the latest matching rates. The original per-turn cost snapshots remain unchanged; legacy rows use content-length token estimates.",
     },
   };
+  metricsCache = { db, changes, dataVersion, tables, createdAt: now.getTime(), metrics };
+  return metrics;
 }
 
 function seedDayBuckets(now: Date, days: number): Map<string, DayBucket> {