From e45cab2a2d9d7bf5e48ace7111fd84b1b9bf2df3 Mon Sep 17 00:00:00 2001 From: Adam Malczewski Date: Thu, 11 Jun 2026 16:06:48 +0900 Subject: feat(cache-warming,surfaces,metrics,markdown): conversation-scoped surfaces, cache warming + retention, markdown Consumes the backend cache-warming + cache-rate handoffs end-to-end and adds supporting infra: - protocol/transport: conversation-scoped surfaces (conversationId on subscribe/invoke/surface + staleness routing); store auto-subscribes the catalog with the focused conversation and re-scopes on switch. - surface-host: generic Number field renderer + custom rendererId dispatch (graceful skip on unknown). - cache-warming feature: enabled toggle, min+sec interval, AUTHORITATIVE countdown from the surface's cache-warming-timer nextWarmAt, manual Warm now (POST /chat/warm), lastWarmAt-keyed history, cache-retention stat, expectedCacheRate headline. - metrics: cross-turn expected-cache (retention) derivation + bubble badge; cache-rate fix needs no code change (inputTokens now total). - markdown feature: marked + marked-highlight + highlight.js + dompurify, rendered in ChatView. - fixes (gemini review): {#key activeConversationId} remount of CacheWarmingView to stop history/feedback leaking across tabs; guard NaN interval inputs from committing 0. - docs/contracts: regenerated transport/ui-contract mirrors; backend-handoff updated (CR-3 resolved). Verified: svelte-check 0 errors, biome clean, 494 tests pass, vite build OK. --- src/app.css | 106 +++++++++ src/app/App.svelte | 45 +++- src/app/App.test.ts | 9 +- src/app/store.svelte.ts | 83 ++++++- src/core/metrics/format.test.ts | 59 +++++ src/core/metrics/format.ts | 29 +++ src/core/metrics/index.ts | 2 + src/core/metrics/place.test.ts | 13 ++ src/core/metrics/place.ts | 13 +- src/core/metrics/types.ts | 5 + src/core/protocol/index.ts | 11 +- src/core/protocol/reducer.test.ts | 110 +++++++++- src/core/protocol/reducer.ts | 101 +++++++-- src/core/protocol/types.ts | 19 +- src/features/cache-warming/index.ts | 8 + .../cache-warming/logic/view-model.test.ts | 220 +++++++++++++++++++ src/features/cache-warming/logic/view-model.ts | 242 +++++++++++++++++++++ .../cache-warming/ui/CacheWarmingView.svelte | 234 ++++++++++++++++++++ src/features/chat/ui/ChatView.svelte | 11 +- src/features/markdown/index.ts | 8 + src/features/markdown/logic/markdown.test.ts | 58 +++++ src/features/markdown/logic/markdown.ts | 165 ++++++++++++++ src/features/markdown/ui/Markdown.svelte | 58 +++++ src/features/markdown/ui/markdown.test.ts | 40 ++++ src/features/surface-host/logic/plan.test.ts | 41 ++++ src/features/surface-host/logic/plan.ts | 33 ++- src/features/surface-host/logic/types.ts | 17 ++ src/features/surface-host/ui/Number.svelte | 43 ++++ src/features/surface-host/ui/SurfaceView.svelte | 3 + 29 files changed, 1736 insertions(+), 50 deletions(-) create mode 100644 src/features/cache-warming/index.ts create mode 100644 src/features/cache-warming/logic/view-model.test.ts create mode 100644 src/features/cache-warming/logic/view-model.ts create mode 100644 src/features/cache-warming/ui/CacheWarmingView.svelte create mode 100644 src/features/markdown/index.ts create mode 100644 src/features/markdown/logic/markdown.test.ts create mode 100644 src/features/markdown/logic/markdown.ts create mode 100644 src/features/markdown/ui/Markdown.svelte create mode 100644 src/features/markdown/ui/markdown.test.ts create mode 100644 src/features/surface-host/ui/Number.svelte (limited to 'src') diff --git a/src/app.css b/src/app.css index 5db1f25..2c30b5f 100644 --- a/src/app.css +++ b/src/app.css @@ -1,4 +1,6 @@ @import "tailwindcss"; +/* Syntax-highlight theme for fenced code blocks in rendered Markdown. */ +@import "highlight.js/styles/atom-one-dark.min.css"; /* DaisyUI v5 — enable the plugin AND bundle the dracula theme (set as default, applied via ). Themes not listed here are NOT @@ -7,6 +9,110 @@ themes: dracula --default; } +/* Rendered-Markdown (assistant messages) typography — scoped to .markdown-body + so it never leaks into the rest of the app. */ +.markdown-body { + & p { + margin-block: 0.5em; + &:first-child { + margin-block-start: 0; + } + &:last-child { + margin-block-end: 0; + } + } + & h1, + & h2, + & h3, + & h4, + & h5, + & h6 { + font-weight: 600; + line-height: 1.25; + margin-block: 0.75em 0.25em; + &:first-child { + margin-block-start: 0; + } + } + & h1 { + font-size: 1.4em; + } + & h2 { + font-size: 1.2em; + } + & h3 { + font-size: 1.1em; + } + & ul, + & ol { + padding-inline-start: 1.5em; + margin-block: 0.5em; + } + & ul { + list-style-type: disc; + } + & ol { + list-style-type: decimal; + } + & li { + margin-block: 0.15em; + } + & pre { + overflow-x: auto; + border-radius: var(--radius-box); + margin-block: 0.5em; + } + & pre code { + display: block; + padding: 0.75em 1em; + font-size: 0.8125em; + line-height: 1.5; + } + & :not(pre) > code { + font-size: 0.875em; + padding: 0.15em 0.4em; + border-radius: var(--radius-selector); + background-color: oklch(var(--color-base-content) / 0.1); + } + & blockquote { + border-inline-start: 3px solid oklch(var(--color-base-content) / 0.2); + padding-inline-start: 0.75em; + margin-block: 0.5em; + opacity: 0.8; + } + & a { + color: oklch(var(--color-primary)); + text-decoration: underline; + &:hover { + opacity: 0.8; + } + } + & strong { + font-weight: 600; + } + & table { + width: 100%; + border-collapse: collapse; + margin-block: 0.5em; + font-size: 0.875em; + } + & th, + & td { + border: 1px solid oklch(var(--color-base-content) / 0.15); + padding: 0.4em 0.75em; + text-align: start; + } + & th { + font-weight: 600; + background-color: oklch(var(--color-base-200)); + } + & hr { + border: none; + border-top: 1px solid oklch(var(--color-base-content) / 0.2); + margin-block: 0.75em; + } +} + /* App shell fills the viewport and never scrolls/overflows at the page level — the inner regions (tab strip, chat transcript) own their own scrolling. */ html, diff --git a/src/app/App.svelte b/src/app/App.svelte index f02797e..dae6177 100644 --- a/src/app/App.svelte +++ b/src/app/App.svelte @@ -1,8 +1,14 @@
@@ -165,9 +193,20 @@

Surfaces

- {#each store.surfaces as spec (spec.id)} + {#each store.surfaces.filter((s) => s.id !== CACHE_WARMING_ID) as spec (spec.id)} {/each}
+ {:else if kind === "cache-warming"} + + {#key store.activeConversationId} + + {/key} {/if} {/snippet} diff --git a/src/app/App.test.ts b/src/app/App.test.ts index 121bd20..1534d1c 100644 --- a/src/app/App.test.ts +++ b/src/app/App.test.ts @@ -388,7 +388,14 @@ describe("App component interaction tests", () => { // Extensions is the default view, so the modules table renders immediately. expect(screen.getByRole("columnheader", { name: "Module" })).toBeInTheDocument(); - for (const name of ["chat", "tabs", "surface-host", "views", "conversation-cache"]) { + for (const name of [ + "chat", + "tabs", + "surface-host", + "views", + "conversation-cache", + "markdown", + ]) { expect(screen.getByRole("cell", { name })).toBeInTheDocument(); } diff --git a/src/app/store.svelte.ts b/src/app/store.svelte.ts index efbe065..c242d77 100644 --- a/src/app/store.svelte.ts +++ b/src/app/store.svelte.ts @@ -4,6 +4,8 @@ import type { ConversationHistoryResponse, ConversationMetricsResponse, ModelsResponse, + WarmRequest, + WarmResponse, } from "@dispatch/transport-contract"; import type { SubscribeMessage, SurfaceServerMessage, SurfaceSpec } from "@dispatch/ui-contract"; import { createIdbChunkStore } from "../adapters/idb"; @@ -12,6 +14,7 @@ import type { WebSocketLike } from "../adapters/ws"; import { createSurfaceSocket, type SurfaceSocketOptions } from "../adapters/ws"; import { applyServerMessage, + getSurfaceSpec, type ProtocolState, initialState as protocolInitialState, invoke as protocolInvoke, @@ -30,6 +33,11 @@ import { randomId } from "./uuid"; const DEFAULT_MODEL = "opencode/deepseek-v4-flash"; +/** Outcome of a manual `POST /chat/warm` (the "warm now" affordance). */ +export type WarmResult = + | { readonly ok: true; readonly response: WarmResponse } + | { readonly ok: false; readonly error: string }; + export interface AppStore { readonly tabs: readonly Tab[]; readonly activeConversationId: string | null; @@ -40,12 +48,19 @@ export interface AppStore { /** Every received surface spec, in catalog order — all auto-subscribed + expanded. */ readonly surfaces: readonly SurfaceSpec[]; readonly lastError: ProtocolState["lastError"]; + /** The current spec for one surface by id (discovery-by-id), or null if absent. */ + surface(surfaceId: string): SurfaceSpec | null; send(text: string): void; selectModel(model: string): void; newDraft(): void; selectTab(conversationId: string): void; closeTab(conversationId: string): void; invoke(surfaceId: string, actionId: string, payload?: unknown): void; + /** + * Manually warm the focused conversation's prompt cache (`POST /chat/warm`). + * Returns null when no conversation is focused (a draft has nothing to warm). + */ + warmNow(): Promise; dispose(): void; } @@ -179,6 +194,11 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { } } + /** The conversation the surfaces should scope to (undefined for a draft). */ + function focusedConversationId(): string | undefined { + return tabsStore.activeConversationId ?? undefined; + } + function handleServerMessage(msg: SurfaceServerMessage): void { protocol = applyServerMessage(protocol, msg); // Surfaces are auto-expanded: whenever the catalog changes, subscribe to @@ -188,10 +208,16 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { } } - /** Subscribe to every catalog entry not yet subscribed; unsubscribe stragglers. */ + /** + * Subscribe to every catalog entry, scoped to the focused conversation, and + * unsubscribe stragglers. Re-run on conversation switch: a conversation-scoped + * surface (e.g. cache-warming) re-scopes to the new id (`protocolSubscribe` + * emits unsubscribe-old + subscribe-new); a global surface ignores the id. + */ function syncSubscriptions(): void { + const cid = focusedConversationId(); for (const entry of protocol.catalog) { - const result = protocolSubscribe(protocol, entry.id); + const result = protocolSubscribe(protocol, entry.id, cid); protocol = result.state; for (const msg of result.outgoing) { socket?.send(msg); @@ -216,11 +242,14 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { onMessage: handleServerMessage, onChat: handleChatMessage, onReopen() { - // The server forgot our subscriptions on reconnect; re-send for all - // catalog entries (protocolSubscribe would no-op since they're still in - // our local map, so emit the wire messages directly). - for (const entry of protocol.catalog) { - const msg: SubscribeMessage = { type: "subscribe", surfaceId: entry.id }; + // The server forgot our subscriptions on reconnect; re-send each with the + // conversation it was subscribed under (protocolSubscribe would no-op since + // they're still in our local map, so emit the wire messages directly). + for (const [surfaceId, sub] of protocol.subscriptions) { + const msg: SubscribeMessage = + sub.conversationId === undefined + ? { type: "subscribe", surfaceId } + : { type: "subscribe", surfaceId, conversationId: sub.conversationId }; socket?.send(msg); } }, @@ -292,7 +321,7 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { get surfaces(): readonly SurfaceSpec[] { const out: SurfaceSpec[] = []; for (const entry of protocol.catalog) { - const spec = protocol.subscriptions.get(entry.id); + const spec = getSurfaceSpec(protocol, entry.id); if (spec) out.push(spec); } return out; @@ -301,6 +330,10 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { return protocol.lastError; }, + surface(surfaceId: string): SurfaceSpec | null { + return getSurfaceSpec(protocol, surfaceId); + }, + send(text: string): void { if (tabsStore.activeConversationId === null) { // Draft: promote to tab on first send @@ -320,6 +353,9 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { draftConversationId = nextDraftId; refreshActiveChat(); + // The draft became a real conversation: re-scope conversation-scoped + // surfaces (e.g. cache-warming) to its id. + syncSubscriptions(); // Now send on the promoted store chatStores.get(conversationId)?.send(text); } else { @@ -344,6 +380,7 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { draftStore = createChatFor(nextDraftId, activeModel); draftConversationId = nextDraftId; refreshActiveChat(); + syncSubscriptions(); }, selectTab(conversationId: string): void { @@ -353,6 +390,7 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { activeModel = tab.model; } refreshActiveChat(); + syncSubscriptions(); }, closeTab(conversationId: string): void { @@ -364,15 +402,42 @@ export function createAppStore(opts?: CreateAppStoreOptions): AppStore { } void cache.delete(conversationId); refreshActiveChat(); + syncSubscriptions(); }, invoke(surfaceId: string, actionId: string, payload?: unknown): void { - const result = protocolInvoke(protocol, surfaceId, actionId, payload); + const result = protocolInvoke( + protocol, + surfaceId, + actionId, + payload, + focusedConversationId(), + ); protocol = result.state; for (const msg of result.outgoing) { socket?.send(msg); } }, + + async warmNow(): Promise { + const conversationId = tabsStore.activeConversationId; + if (conversationId === null) return null; + const body: WarmRequest = { conversationId, model: activeModel }; + try { + const res = await fetchImpl(`${httpBase}/chat/warm`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify(body), + }); + if (!res.ok) { + const errBody = (await res.json().catch(() => null)) as { error?: string } | null; + return { ok: false, error: errBody?.error ?? `Warm failed (HTTP ${res.status})` }; + } + return { ok: true, response: (await res.json()) as WarmResponse }; + } catch (err) { + return { ok: false, error: err instanceof Error ? err.message : "Warm request failed" }; + } + }, dispose(): void { for (const store of chatStores.values()) { store.dispose(); diff --git a/src/core/metrics/format.test.ts b/src/core/metrics/format.test.ts index 77c5204..3eec93d 100644 --- a/src/core/metrics/format.test.ts +++ b/src/core/metrics/format.test.ts @@ -2,8 +2,10 @@ import type { StepId, StepMetrics, TurnMetrics } from "@dispatch/wire"; import { describe, expect, it } from "vitest"; import { computeCachePct, + computeExpectedCachePct, computeTps, viewCacheRate, + viewExpectedCache, viewStepMetrics, viewTurnMetrics, } from "./format"; @@ -249,3 +251,60 @@ describe("viewCacheRate", () => { expect(miss.isHit).toBe(false); }); }); + +describe("computeExpectedCachePct", () => { + it("null when there is no prior turn (first turn has no baseline)", () => { + expect(computeExpectedCachePct({ inputTokens: 100, outputTokens: 0 }, null)).toBeNull(); + }); + + it("null when the prior turn cached nothing (denominator 0)", () => { + const prev = { inputTokens: 100, outputTokens: 0 }; + const current = { inputTokens: 200, outputTokens: 0, cacheReadTokens: 50 }; + expect(computeExpectedCachePct(current, prev)).toBeNull(); + }); + + it("100% when the whole prior cached prefix was read back (backend worked example)", () => { + // turn 1: cacheRead 0, cacheWrite 5146 → prefix 5146; turn 2 reads 5146 back. + const prev = { inputTokens: 5149, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 5146 }; + const current = { + inputTokens: 8462, + outputTokens: 0, + cacheReadTokens: 5146, + cacheWriteTokens: 3313, + }; + expect(computeExpectedCachePct(current, prev)).toBe(100); + }); + + it("drops below 100% when the cache busted (read < prior prefix)", () => { + const prev = { + inputTokens: 1000, + outputTokens: 0, + cacheReadTokens: 100, + cacheWriteTokens: 900, + }; + const current = { inputTokens: 1000, outputTokens: 0, cacheReadTokens: 500 }; + // 500 / (100 + 900) = 50% + expect(computeExpectedCachePct(current, prev)).toBe(50); + }); + + it("clamps to 100 if read somehow exceeds the prior prefix", () => { + const prev = { inputTokens: 100, outputTokens: 0, cacheWriteTokens: 100 }; + const current = { inputTokens: 100, outputTokens: 0, cacheReadTokens: 250 }; + expect(computeExpectedCachePct(current, prev)).toBe(100); + }); +}); + +describe("viewExpectedCache", () => { + it("null view when it cannot be derived (no prior turn)", () => { + expect(viewExpectedCache({ inputTokens: 100, outputTokens: 0 }, null)).toBeNull(); + }); + + it("success level + hit flag for full retention", () => { + const prev = { inputTokens: 5149, outputTokens: 0, cacheWriteTokens: 5146 }; + const current = { inputTokens: 8462, outputTokens: 0, cacheReadTokens: 5146 }; + const v = viewExpectedCache(current, prev); + expect(v?.pct).toBe(100); + expect(v?.level).toBe("success"); + expect(v?.isHit).toBe(true); + }); +}); diff --git a/src/core/metrics/format.ts b/src/core/metrics/format.ts index cc86976..ee8db60 100644 --- a/src/core/metrics/format.ts +++ b/src/core/metrics/format.ts @@ -75,6 +75,35 @@ export function viewCacheRate(u: Usage): CacheRateView { return { pct, level: cacheLevel(pct), isHit: (u.cacheReadTokens ?? 0) > 0 }; } +/** + * Expected cache (retention): of the cache that existed going INTO this turn, how + * much was read back — `clamp01(cacheRead_N / (cacheRead_{N-1} + cacheWrite_{N-1}))`. + * The denominator is the PRIOR turn's cached prefix (what it read + what it wrote). + * Ideally ~100% on every turn after the first; <100% = the cache busted/expired. + * + * Returns `null` when it cannot be derived: no prior turn (`prev === null`) or the + * prior turn cached nothing (denominator <= 0) — distinct from a real 0%. + */ +export function computeExpectedCachePct(current: Usage, prev: Usage | null): number | null { + if (prev === null) return null; + const denom = (prev.cacheReadTokens ?? 0) + (prev.cacheWriteTokens ?? 0); + if (denom <= 0) return null; + const read = current.cacheReadTokens ?? 0; + const rate = read / denom; + const clamped = rate < 0 ? 0 : rate > 1 ? 1 : rate; + return Math.round(clamped * 100); +} + +/** + * Build a view of the cross-turn retention (percentage + colour level + hit flag), + * or `null` when it can't be derived (see `computeExpectedCachePct`). + */ +export function viewExpectedCache(current: Usage, prev: Usage | null): CacheRateView | null { + const pct = computeExpectedCachePct(current, prev); + if (pct === null) return null; + return { pct, level: cacheLevel(pct), isHit: (current.cacheReadTokens ?? 0) > 0 }; +} + /** Build a formatted view of a turn's aggregate metrics. */ export function viewTurnMetrics(turn: TurnMetrics): TurnMetricsView { const total = totalTokens(turn.usage); diff --git a/src/core/metrics/index.ts b/src/core/metrics/index.ts index 6997ab9..8822159 100644 --- a/src/core/metrics/index.ts +++ b/src/core/metrics/index.ts @@ -1,7 +1,9 @@ export { computeCachePct, + computeExpectedCachePct, computeTps, viewCacheRate, + viewExpectedCache, viewStepMetrics, viewTurnMetrics, } from "./format"; diff --git a/src/core/metrics/place.test.ts b/src/core/metrics/place.test.ts index d94882d..0b9c0ec 100644 --- a/src/core/metrics/place.test.ts +++ b/src/core/metrics/place.test.ts @@ -526,4 +526,17 @@ describe("interleaveTurnMetrics — cumulative usage (cache total)", () => { expect(tm[0]?.cumulativeUsage.inputTokens).toBe(1000); expect(tm[0]?.cumulativeUsage.cacheReadTokens).toBe(500); }); + + it("carries the prior finalized turn's usage as the retention baseline", () => { + const rows = interleaveTurnMetrics( + [userGroup(1, "q1"), assistantGroup(2, "a1"), userGroup(3, "q2"), assistantGroup(4, "a2")], + [cacheEntry("t1", 2669, 10, 384), cacheEntry("t2", 2737, 10, 2560)], + ); + const tm = turnMetricsRows(rows); + // first finalized turn has no earlier baseline + expect(tm[0]?.prevTurnUsage).toBeNull(); + // second turn's baseline is the first turn's usage + expect(tm[1]?.prevTurnUsage?.inputTokens).toBe(2669); + expect(tm[1]?.prevTurnUsage?.cacheReadTokens).toBe(384); + }); }); diff --git a/src/core/metrics/place.ts b/src/core/metrics/place.ts index fc30df0..afeb84b 100644 --- a/src/core/metrics/place.ts +++ b/src/core/metrics/place.ts @@ -79,11 +79,19 @@ export function interleaveTurnMetrics( } // Running cumulative usage across finalized turns (conversation total at each - // entry index), for the per-turn "chat total" cache rate. + // entry index), for the per-turn "chat total" cache rate. Alongside it, the + // previous finalized turn's usage at each index — the baseline for cross-turn + // retention (expected cache). const cumulativeByEntry: Usage[] = []; + const prevUsageByEntry: (Usage | null)[] = []; let runningUsage: Usage = { inputTokens: 0, outputTokens: 0 }; + let lastFinalizedUsage: Usage | null = null; for (const e of entries) { - if (e.total !== null) runningUsage = addUsage(runningUsage, e.total.usage); + prevUsageByEntry.push(lastFinalizedUsage); + if (e.total !== null) { + runningUsage = addUsage(runningUsage, e.total.usage); + lastFinalizedUsage = e.total.usage; + } cumulativeByEntry.push(runningUsage); } @@ -170,6 +178,7 @@ export function interleaveTurnMetrics( kind: "turn-metrics", turn: entry.total, cumulativeUsage: cumulativeByEntry[seg] ?? entry.total.usage, + prevTurnUsage: prevUsageByEntry[seg] ?? null, }); } } diff --git a/src/core/metrics/types.ts b/src/core/metrics/types.ts index cf2511c..f5557f7 100644 --- a/src/core/metrics/types.ts +++ b/src/core/metrics/types.ts @@ -52,6 +52,11 @@ export type MetricsRow = readonly turn: TurnMetrics; /** Cumulative usage across all finalized turns up to and including this one. */ readonly cumulativeUsage: Usage; + /** + * Usage of the most recent EARLIER finalized turn, or `null` when this is the + * first finalized turn. The baseline for cross-turn retention (expected cache). + */ + readonly prevTurnUsage: Usage | null; }; /** Formatted cache hit-rate view: percentage + colour severity + hit flag. */ diff --git a/src/core/protocol/index.ts b/src/core/protocol/index.ts index 25174ea..e7fd161 100644 --- a/src/core/protocol/index.ts +++ b/src/core/protocol/index.ts @@ -1,2 +1,9 @@ -export { applyServerMessage, initialState, invoke, subscribe, unsubscribe } from "./reducer"; -export type { ProtocolResult, ProtocolState } from "./types"; +export { + applyServerMessage, + getSurfaceSpec, + initialState, + invoke, + subscribe, + unsubscribe, +} from "./reducer"; +export type { ProtocolResult, ProtocolState, Subscription } from "./types"; diff --git a/src/core/protocol/reducer.test.ts b/src/core/protocol/reducer.test.ts index 57e12f2..c8e517a 100644 --- a/src/core/protocol/reducer.test.ts +++ b/src/core/protocol/reducer.test.ts @@ -1,5 +1,12 @@ import { describe, expect, it } from "vitest"; -import { applyServerMessage, initialState, invoke, subscribe, unsubscribe } from "./reducer"; +import { + applyServerMessage, + getSurfaceSpec, + initialState, + invoke, + subscribe, + unsubscribe, +} from "./reducer"; const makeSpec = (id: string, title = id) => ({ id, @@ -32,11 +39,10 @@ describe("applyServerMessage — catalog", () => { describe("applyServerMessage — surface", () => { it("sets the spec for a subscribed surface", () => { let s = initialState(); - const result = subscribe(s, "s1"); - s = result.state; + s = subscribe(s, "s1").state; const spec = makeSpec("s1", "Surface 1"); const next = applyServerMessage(s, { type: "surface", spec }); - expect(next.subscriptions.get("s1")).toEqual(spec); + expect(getSurfaceSpec(next, "s1")).toEqual(spec); }); it("ignores a surface message for a non-subscribed surface", () => { @@ -56,7 +62,7 @@ describe("applyServerMessage — update", () => { type: "update", update: { surfaceId: "s1", spec: makeSpec("s1", "V2") }, }); - expect(next.subscriptions.get("s1")?.title).toBe("V2"); + expect(getSurfaceSpec(next, "s1")?.title).toBe("V2"); }); it("ignores an update for a non-subscribed surface", () => { @@ -86,7 +92,7 @@ describe("applyServerMessage — error", () => { }); describe("subscribe", () => { - it("emits exactly one subscribe message", () => { + it("emits exactly one subscribe message (global, no conversationId)", () => { const s = initialState(); const result = subscribe(s, "s1"); expect(result.outgoing).toEqual([{ type: "subscribe", surfaceId: "s1" }]); @@ -96,10 +102,14 @@ describe("subscribe", () => { it("adds the surface to subscriptions with null spec", () => { const s = initialState(); const result = subscribe(s, "s1"); - expect(result.state.subscriptions.get("s1")).toBeNull(); + expect(result.state.subscriptions.get("s1")).toEqual({ + conversationId: undefined, + spec: null, + }); + expect(getSurfaceSpec(result.state, "s1")).toBeNull(); }); - it("is idempotent — second subscribe is a no-op", () => { + it("is idempotent — second subscribe with the same scope is a no-op", () => { let s = initialState(); s = subscribe(s, "s1").state; const result = subscribe(s, "s1"); @@ -108,6 +118,67 @@ describe("subscribe", () => { }); }); +describe("subscribe — conversation-scoped", () => { + it("includes conversationId in the subscribe message", () => { + const s = initialState(); + const result = subscribe(s, "cache-warming", "conv-A"); + expect(result.outgoing).toEqual([ + { type: "subscribe", surfaceId: "cache-warming", conversationId: "conv-A" }, + ]); + expect(result.state.subscriptions.get("cache-warming")?.conversationId).toBe("conv-A"); + }); + + it("re-scopes on conversation switch: unsubscribe old pair then subscribe new", () => { + let s = initialState(); + s = subscribe(s, "cw", "conv-A").state; + s = applyServerMessage(s, { + type: "surface", + spec: makeSpec("cw", "A-spec"), + conversationId: "conv-A", + }); + const result = subscribe(s, "cw", "conv-B"); + expect(result.outgoing).toEqual([ + { type: "unsubscribe", surfaceId: "cw", conversationId: "conv-A" }, + { type: "subscribe", surfaceId: "cw", conversationId: "conv-B" }, + ]); + // previous spec retained until the new one arrives (no flicker) + expect(getSurfaceSpec(result.state, "cw")?.title).toBe("A-spec"); + expect(result.state.subscriptions.get("cw")?.conversationId).toBe("conv-B"); + }); + + it("drops a stale update echoing the previous conversationId", () => { + let s = initialState(); + s = subscribe(s, "cw", "conv-A").state; + s = subscribe(s, "cw", "conv-B").state; // re-scoped to B + const next = applyServerMessage(s, { + type: "update", + update: { surfaceId: "cw", spec: makeSpec("cw", "STALE-A"), conversationId: "conv-A" }, + }); + expect(getSurfaceSpec(next, "cw")).toBeNull(); // stale ignored, no spec yet for B + }); + + it("accepts an update echoing the current conversationId", () => { + let s = initialState(); + s = subscribe(s, "cw", "conv-B").state; + const next = applyServerMessage(s, { + type: "update", + update: { surfaceId: "cw", spec: makeSpec("cw", "B-spec"), conversationId: "conv-B" }, + }); + expect(getSurfaceSpec(next, "cw")?.title).toBe("B-spec"); + }); + + it("accepts a global (no-echo) surface message even when subscribed with a conversationId", () => { + // loaded-extensions is global: server ignores our conversationId and echoes none. + let s = initialState(); + s = subscribe(s, "loaded-extensions", "conv-A").state; + const next = applyServerMessage(s, { + type: "surface", + spec: makeSpec("loaded-extensions", "Ext"), + }); + expect(getSurfaceSpec(next, "loaded-extensions")?.title).toBe("Ext"); + }); +}); + describe("unsubscribe", () => { it("emits unsubscribe and drops the spec", () => { let s = initialState(); @@ -118,6 +189,15 @@ describe("unsubscribe", () => { expect(result.state.subscriptions.has("s1")).toBe(false); }); + it("includes conversationId for a scoped subscription", () => { + let s = initialState(); + s = subscribe(s, "cw", "conv-A").state; + const result = unsubscribe(s, "cw"); + expect(result.outgoing).toEqual([ + { type: "unsubscribe", surfaceId: "cw", conversationId: "conv-A" }, + ]); + }); + it("is a no-op if not subscribed", () => { const s = initialState(); const result = unsubscribe(s, "nope"); @@ -143,6 +223,20 @@ describe("invoke", () => { ]); }); + it("includes conversationId when provided", () => { + const s = initialState(); + const result = invoke(s, "cw", "cache-warming/set-interval", 120, "conv-A"); + expect(result.outgoing).toEqual([ + { + type: "invoke", + surfaceId: "cw", + actionId: "cache-warming/set-interval", + payload: 120, + conversationId: "conv-A", + }, + ]); + }); + it("does not mutate state", () => { const s = initialState(); const result = invoke(s, "s1", "a1"); diff --git a/src/core/protocol/reducer.ts b/src/core/protocol/reducer.ts index 992a918..3d6b1c8 100644 --- a/src/core/protocol/reducer.ts +++ b/src/core/protocol/reducer.ts @@ -2,6 +2,7 @@ import type { InvokeMessage, SubscribeMessage, SurfaceServerMessage, + SurfaceSpec, UnsubscribeMessage, } from "@dispatch/ui-contract"; import type { ProtocolResult, ProtocolState } from "./types"; @@ -15,6 +16,31 @@ export function initialState(): ProtocolState { }; } +// ── Message builders (respect exactOptionalPropertyTypes: omit `conversationId` +// entirely for a global subscription rather than setting it to `undefined`). ── + +function subMsg(surfaceId: string, conversationId: string | undefined): SubscribeMessage { + return conversationId === undefined + ? { type: "subscribe", surfaceId } + : { type: "subscribe", surfaceId, conversationId }; +} + +function unsubMsg(surfaceId: string, conversationId: string | undefined): UnsubscribeMessage { + return conversationId === undefined + ? { type: "unsubscribe", surfaceId } + : { type: "unsubscribe", surfaceId, conversationId }; +} + +/** + * Is an inbound spec/update (which echoes `echoedId`) current for the + * subscription whose desired scope is `desiredId`? A scoped surface echoes its + * conversationId, so it must match the one we last subscribed with; a GLOBAL + * surface echoes nothing (`undefined`) and is always current. + */ +function isCurrent(desiredId: string | undefined, echoedId: string | undefined): boolean { + return echoedId === undefined || echoedId === desiredId; +} + /** Fold an inbound server message into the next protocol state. */ export function applyServerMessage(state: ProtocolState, msg: SurfaceServerMessage): ProtocolState { switch (msg.type) { @@ -22,18 +48,21 @@ export function applyServerMessage(state: ProtocolState, msg: SurfaceServerMessa return { ...state, catalog: msg.catalog }; case "surface": { - const surfaceId = msg.spec.id; - if (!state.subscriptions.has(surfaceId)) return state; + const sub = state.subscriptions.get(msg.spec.id); + if (sub === undefined) return state; + if (!isCurrent(sub.conversationId, msg.conversationId)) return state; const subs = new Map(state.subscriptions); - subs.set(surfaceId, msg.spec); + subs.set(msg.spec.id, { conversationId: sub.conversationId, spec: msg.spec }); return { ...state, subscriptions: subs }; } case "update": { - const surfaceId = msg.update.surfaceId; - if (!state.subscriptions.has(surfaceId)) return state; + const { surfaceId, spec, conversationId } = msg.update; + const sub = state.subscriptions.get(surfaceId); + if (sub === undefined) return state; + if (!isCurrent(sub.conversationId, conversationId)) return state; const subs = new Map(state.subscriptions); - subs.set(surfaceId, msg.update.spec); + subs.set(surfaceId, { conversationId: sub.conversationId, spec }); return { ...state, subscriptions: subs }; } @@ -43,40 +72,72 @@ export function applyServerMessage(state: ProtocolState, msg: SurfaceServerMessa } /** - * Subscribe to a surface. Idempotent: if already subscribed, returns the same - * state with no outgoing message. + * Subscribe to a surface for a given conversation (omit `conversationId` for a + * GLOBAL surface / when no conversation is focused). + * + * - Not yet subscribed → emits one `subscribe`. + * - Already subscribed with the SAME scope → idempotent no-op. + * - Already subscribed with a DIFFERENT conversation (a re-scope on conversation + * switch) → emits `unsubscribe` for the old pair then `subscribe` for the new + * one, retaining the previous spec until the new one arrives (no flicker). */ -export function subscribe(state: ProtocolState, surfaceId: string): ProtocolResult { - if (state.subscriptions.has(surfaceId)) { +export function subscribe( + state: ProtocolState, + surfaceId: string, + conversationId?: string, +): ProtocolResult { + const existing = state.subscriptions.get(surfaceId); + if (existing !== undefined && existing.conversationId === conversationId) { return { state, outgoing: [] }; } const subs = new Map(state.subscriptions); - subs.set(surfaceId, null); - const outgoing: SubscribeMessage = { type: "subscribe", surfaceId }; - return { state: { ...state, subscriptions: subs }, outgoing: [outgoing] }; + const outgoing: (SubscribeMessage | UnsubscribeMessage)[] = []; + const priorSpec: SurfaceSpec | null = existing?.spec ?? null; + if (existing !== undefined) { + outgoing.push(unsubMsg(surfaceId, existing.conversationId)); + } + subs.set(surfaceId, { conversationId, spec: priorSpec }); + outgoing.push(subMsg(surfaceId, conversationId)); + return { state: { ...state, subscriptions: subs }, outgoing }; } /** - * Unsubscribe from a surface. Drops the local spec and emits one unsubscribe. - * If not subscribed, returns the same state with no outgoing. + * Unsubscribe from a surface. Drops the local subscription and emits one + * `unsubscribe` (for the conversation pair it was subscribed under). No-op if + * not subscribed. */ export function unsubscribe(state: ProtocolState, surfaceId: string): ProtocolResult { - if (!state.subscriptions.has(surfaceId)) { + const existing = state.subscriptions.get(surfaceId); + if (existing === undefined) { return { state, outgoing: [] }; } const subs = new Map(state.subscriptions); subs.delete(surfaceId); - const outgoing: UnsubscribeMessage = { type: "unsubscribe", surfaceId }; - return { state: { ...state, subscriptions: subs }, outgoing: [outgoing] }; + return { + state: { ...state, subscriptions: subs }, + outgoing: [unsubMsg(surfaceId, existing.conversationId)], + }; } -/** Invoke a field's action on a surface. Emits an InvokeMessage; no state change. */ +/** + * Invoke a field's action on a surface. Emits an InvokeMessage (carrying + * `conversationId` for a scoped surface); no state change. + */ export function invoke( state: ProtocolState, surfaceId: string, actionId: string, payload?: unknown, + conversationId?: string, ): ProtocolResult { - const outgoing: InvokeMessage = { type: "invoke", surfaceId, actionId, payload }; + const outgoing: InvokeMessage = + conversationId === undefined + ? { type: "invoke", surfaceId, actionId, payload } + : { type: "invoke", surfaceId, actionId, payload, conversationId }; return { state, outgoing: [outgoing] }; } + +/** The current spec for a subscribed surface, or `null` if absent/unsubscribed. */ +export function getSurfaceSpec(state: ProtocolState, surfaceId: string): SurfaceSpec | null { + return state.subscriptions.get(surfaceId)?.spec ?? null; +} diff --git a/src/core/protocol/types.ts b/src/core/protocol/types.ts index effec0d..db8886a 100644 --- a/src/core/protocol/types.ts +++ b/src/core/protocol/types.ts @@ -5,12 +5,27 @@ import type { SurfaceSpec, } from "@dispatch/ui-contract"; +/** + * One surface subscription's local state. + * + * `conversationId` is the conversation we last subscribed this surface WITH + * (`undefined` = subscribed globally, no conversation in focus). It is the + * "desired" scope: an inbound `surface`/`update` that echoes a DIFFERENT + * conversation is stale (we have since re-scoped) and is dropped. A GLOBAL + * surface ignores the id server-side and echoes none — that (`undefined` echo) + * is always accepted. `spec` is `null` until the first `surface` arrives. + */ +export interface Subscription { + readonly conversationId: string | undefined; + readonly spec: SurfaceSpec | null; +} + /** The client-side view of the surface protocol state. */ export interface ProtocolState { /** The latest catalog received from the server (empty until first CatalogMessage). */ readonly catalog: SurfaceCatalog; - /** Surfaces the client intends to be subscribed to; null = subscribed but no spec yet. */ - readonly subscriptions: ReadonlyMap; + /** Surfaces the client intends to be subscribed to, keyed by surfaceId. */ + readonly subscriptions: ReadonlyMap; /** The last error received from the server, if any. */ readonly lastError: SurfaceErrorMessage | null; } diff --git a/src/features/cache-warming/index.ts b/src/features/cache-warming/index.ts new file mode 100644 index 0000000..c432de6 --- /dev/null +++ b/src/features/cache-warming/index.ts @@ -0,0 +1,8 @@ +export type { WarmFeedback, WarmNow } from "./logic/view-model"; +export { default as CacheWarmingView } from "./ui/CacheWarmingView.svelte"; + +/** Public module manifest — aggregated by the shell's "Loaded Modules" view. */ +export const manifest = { + name: "cache-warming", + description: "Prompt-cache warming controls, history, and countdown", +} as const; diff --git a/src/features/cache-warming/logic/view-model.test.ts b/src/features/cache-warming/logic/view-model.test.ts new file mode 100644 index 0000000..3d6f6d0 --- /dev/null +++ b/src/features/cache-warming/logic/view-model.test.ts @@ -0,0 +1,220 @@ +import type { SurfaceSpec } from "@dispatch/ui-contract"; +import { describe, expect, it } from "vitest"; +import { + clampMinutes, + clampSeconds, + colorClass, + formatCountdown, + formatWarmLabel, + fromMinSec, + initialWarmingState, + observeWarm, + parseControls, + parsePct, + secondsUntilNext, + statusForPct, + toMinSec, +} from "./view-model"; + +const spec = (fields: SurfaceSpec["fields"]): SurfaceSpec => ({ + id: "cache-warming", + region: "side", + title: "Cache Warming", + fields, +}); + +describe("parsePct", () => { + it("parses a percentage string", () => { + expect(parsePct("100%")).toBe(100); + expect(parsePct("93 %")).toBe(93); + expect(parsePct("0%")).toBe(0); + }); + it("returns null for a dash / non-numeric", () => { + expect(parsePct("—")).toBeNull(); + expect(parsePct("n/a")).toBeNull(); + }); +}); + +describe("parseControls", () => { + it("returns empty defaults for a null spec", () => { + const c = parseControls(null); + expect(c).toEqual({ + enabled: false, + toggleActionId: null, + intervalSeconds: 0, + setIntervalActionId: null, + lastPct: null, + retentionPct: null, + nextWarmAt: null, + lastWarmAt: null, + }); + }); + + it("extracts toggle / number / both stats / timer by kind", () => { + const c = parseControls( + spec([ + { + kind: "toggle", + label: "Enabled", + value: true, + action: { actionId: "cache-warming/toggle" }, + }, + { + kind: "number", + label: "Interval", + value: 240, + unit: "s", + action: { actionId: "cache-warming/set-interval" }, + }, + { kind: "stat", label: "Last cache rate", value: "61%" }, + { kind: "stat", label: "Cache retention", value: "100%" }, + { + kind: "custom", + rendererId: "cache-warming-timer", + payload: { nextWarmAt: 1_700_000_240_000, lastWarmAt: 1_700_000_000_000 }, + }, + ]), + ); + expect(c).toEqual({ + enabled: true, + toggleActionId: "cache-warming/toggle", + intervalSeconds: 240, + setIntervalActionId: "cache-warming/set-interval", + lastPct: 61, + retentionPct: 100, + nextWarmAt: 1_700_000_240_000, + lastWarmAt: 1_700_000_000_000, + }); + }); + + it("tells the retention stat apart from the rate stat by label", () => { + const c = parseControls( + spec([ + { kind: "stat", label: "Cache retention", value: "100%" }, + { kind: "stat", label: "Last cache rate", value: "61%" }, + ]), + ); + expect(c.retentionPct).toBe(100); + expect(c.lastPct).toBe(61); + }); + + it("treats a '—' stat as no pct", () => { + const c = parseControls(spec([{ kind: "stat", label: "Last cache rate", value: "—" }])); + expect(c.lastPct).toBeNull(); + }); + + it("ignores an unknown custom renderer and a malformed timer payload", () => { + const c = parseControls( + spec([ + { kind: "custom", rendererId: "something-else", payload: { nextWarmAt: 5 } }, + { kind: "custom", rendererId: "cache-warming-timer", payload: "nope" }, + ]), + ); + expect(c.nextWarmAt).toBeNull(); + expect(c.lastWarmAt).toBeNull(); + }); +}); + +describe("interval ↔ min/sec", () => { + it("clampSeconds caps at 0..59", () => { + expect(clampSeconds(75)).toBe(59); + expect(clampSeconds(-3)).toBe(0); + expect(clampSeconds(30)).toBe(30); + expect(clampSeconds(Number.NaN)).toBe(0); + }); + it("clampMinutes floors at 0", () => { + expect(clampMinutes(-1)).toBe(0); + expect(clampMinutes(4)).toBe(4); + }); + it("toMinSec splits total seconds", () => { + expect(toMinSec(240)).toEqual({ minutes: 4, seconds: 0 }); + expect(toMinSec(125)).toEqual({ minutes: 2, seconds: 5 }); + expect(toMinSec(45)).toEqual({ minutes: 0, seconds: 45 }); + }); + it("fromMinSec combines (clamping seconds to 59)", () => { + expect(fromMinSec(4, 0)).toBe(240); + expect(fromMinSec(2, 5)).toBe(125); + expect(fromMinSec(1, 75)).toBe(119); // 75s clamped to 59 + }); +}); + +describe("status + formatting", () => { + it("statusForPct buckets high/mid/low", () => { + expect(statusForPct(100)).toBe("success"); + expect(statusForPct(80)).toBe("success"); + expect(statusForPct(60)).toBe("warning"); + expect(statusForPct(40)).toBe("warning"); + expect(statusForPct(10)).toBe("error"); + }); + it("colorClass maps to literal DaisyUI classes", () => { + expect(colorClass("success")).toBe("text-success"); + expect(colorClass("warning")).toBe("text-warning"); + expect(colorClass("error")).toBe("text-error"); + }); + it("formatWarmLabel matches the manual-warm phrasing", () => { + expect(formatWarmLabel(100)).toBe("Warmed — 100% cache hit"); + expect(formatWarmLabel(92.6)).toBe("Warmed — 93% cache hit"); + }); + it("formatCountdown renders s and m:ss", () => { + expect(formatCountdown(9)).toBe("9s"); + expect(formatCountdown(59)).toBe("59s"); + expect(formatCountdown(60)).toBe("1:00"); + expect(formatCountdown(185)).toBe("3:05"); + expect(formatCountdown(-5)).toBe("0s"); + }); +}); + +describe("warming history reducer (observeWarm)", () => { + it("starts empty", () => { + const s = initialWarmingState(); + expect(s.history).toEqual([]); + expect(s.lastWarmAt).toBeNull(); + }); + + it("records a new entry on each new authoritative lastWarmAt", () => { + let s = initialWarmingState(); + s = observeWarm(s, 1000, 100); + s = observeWarm(s, 2000, 90); + expect(s.history).toEqual([ + { pct: 90, at: 2000 }, + { pct: 100, at: 1000 }, + ]); + expect(s.lastWarmAt).toBe(2000); + }); + + it("de-duplicates on the timestamp, not the pct (a re-pushed surface → no dup)", () => { + let s = initialWarmingState(); + s = observeWarm(s, 1000, 100); // warm + s = observeWarm(s, 1000, 100); // toggle/interval re-push, same lastWarmAt → skip + expect(s.history).toHaveLength(1); + }); + + it("records two warms with the SAME pct (distinct timestamps both count)", () => { + let s = initialWarmingState(); + s = observeWarm(s, 1000, 100); + s = observeWarm(s, 2000, 100); + expect(s.history.map((e) => e.at)).toEqual([2000, 1000]); + }); + + it("ignores a null lastWarmAt; a null pct advances the key without an entry", () => { + let s = initialWarmingState(); + s = observeWarm(s, null, 100); + expect(s.history).toEqual([]); + s = observeWarm(s, 1000, null); + expect(s.history).toEqual([]); + expect(s.lastWarmAt).toBe(1000); + }); +}); + +describe("secondsUntilNext (authoritative, from nextWarmAt)", () => { + it("is null when nothing is scheduled (nextWarmAt null)", () => { + expect(secondsUntilNext(null, 5000)).toBeNull(); + }); + + it("counts down to nextWarmAt, floored at 0", () => { + expect(secondsUntilNext(10_000, 10_000)).toBe(0); + expect(secondsUntilNext(250_000, 10_000)).toBe(240); + expect(secondsUntilNext(70_000, 10_000)).toBe(60); + expect(secondsUntilNext(5_000, 999_999)).toBe(0); // already past + }); +}); diff --git a/src/features/cache-warming/logic/view-model.ts b/src/features/cache-warming/logic/view-model.ts new file mode 100644 index 0000000..f7740d7 --- /dev/null +++ b/src/features/cache-warming/logic/view-model.ts @@ -0,0 +1,242 @@ +import type { SurfaceSpec } from "@dispatch/ui-contract"; + +/** + * Pure core for the cache-warming view — zero DOM, zero effects, zero Svelte. + * + * The backend's `cache-warming` surface carries a toggle, a number interval (in + * seconds), two `stat`s ("last cache rate" + "cache retention"), and a `custom` + * `cache-warming-timer` field bearing the AUTHORITATIVE `nextWarmAt`/`lastWarmAt` + * epoch-ms timestamps. This module turns those inputs into the view-model the + * (thin) Svelte component renders: parsed controls, a warming-history reducer + * keyed off the authoritative `lastWarmAt`, an authoritative countdown, and the + * status/format helpers. + */ + +// ── Manual-warm port (consumer-defines-port; the composition root adapts the +// store's `POST /chat/warm` result to this shape). ────────────────────────── +export type WarmFeedback = + | { readonly ok: true; readonly cachePct: number; readonly expectedCacheRate: number } + | { readonly ok: false; readonly error: string }; + +export type WarmNow = () => Promise; + +// ── Parsed surface controls ─────────────────────────────────────────────────── + +export interface ParsedControls { + readonly enabled: boolean; + readonly toggleActionId: string | null; + readonly intervalSeconds: number; + readonly setIntervalActionId: string | null; + /** Most recent warm's cache-hit %, from the "last cache rate" stat (`null` when "—"/absent). */ + readonly lastPct: number | null; + /** Cross-turn retention %, from the "cache retention" stat (`null` when "—"/absent). */ + readonly retentionPct: number | null; + /** Authoritative epoch-ms the next AUTOMATIC warm fires, or `null` when not scheduled. */ + readonly nextWarmAt: number | null; + /** Authoritative epoch-ms of the most recent completed warm, or `null` if none. */ + readonly lastWarmAt: number | null; +} + +const EMPTY_CONTROLS: ParsedControls = { + enabled: false, + toggleActionId: null, + intervalSeconds: 0, + setIntervalActionId: null, + lastPct: null, + retentionPct: null, + nextWarmAt: null, + lastWarmAt: null, +}; + +/** The `cache-warming-timer` custom field's renderer id (this feature owns it). */ +const TIMER_RENDERER_ID = "cache-warming-timer"; + +/** Parse a stat's display string (e.g. "100%", "93 %", "—") into a number or null. */ +export function parsePct(value: string): number | null { + const match = value.match(/-?\d+(?:\.\d+)?/); + if (match === null) return null; + const n = Number(match[0]); + return Number.isFinite(n) ? n : null; +} + +/** A finite number, else null. */ +function numOrNull(v: unknown): number | null { + return typeof v === "number" && Number.isFinite(v) ? v : null; +} + +/** Pull the authoritative `nextWarmAt`/`lastWarmAt` out of the timer custom payload. */ +function parseTimer(payload: unknown): { nextWarmAt: number | null; lastWarmAt: number | null } { + if (typeof payload !== "object" || payload === null) { + return { nextWarmAt: null, lastWarmAt: null }; + } + const p = payload as Record; + return { nextWarmAt: numOrNull(p.nextWarmAt), lastWarmAt: numOrNull(p.lastWarmAt) }; +} + +/** + * Extract the cache-warming controls from the surface spec by FIELD KIND. The + * surface has one toggle, one number, two stats (rate + retention, told apart by + * label), and one `custom` timer field. Returns empty defaults when the spec is + * absent. + */ +export function parseControls(spec: SurfaceSpec | null): ParsedControls { + if (spec === null) return EMPTY_CONTROLS; + let enabled = false; + let toggleActionId: string | null = null; + let intervalSeconds = 0; + let setIntervalActionId: string | null = null; + let lastPct: number | null = null; + let retentionPct: number | null = null; + let nextWarmAt: number | null = null; + let lastWarmAt: number | null = null; + let seenToggle = false; + let seenNumber = false; + let seenRateStat = false; + for (const field of spec.fields) { + if (field.kind === "toggle" && !seenToggle) { + enabled = field.value; + toggleActionId = field.action.actionId; + seenToggle = true; + } else if (field.kind === "number" && !seenNumber) { + intervalSeconds = field.value; + setIntervalActionId = field.action.actionId; + seenNumber = true; + } else if (field.kind === "stat") { + // Retention is told apart by its label; everything else is the cache rate + // (first one wins, so a stray later stat can't clobber it). + if (/retention/i.test(field.label)) { + retentionPct = parsePct(field.value); + } else if (!seenRateStat) { + lastPct = parsePct(field.value); + seenRateStat = true; + } + } else if (field.kind === "custom" && field.rendererId === TIMER_RENDERER_ID) { + const timer = parseTimer(field.payload); + nextWarmAt = timer.nextWarmAt; + lastWarmAt = timer.lastWarmAt; + } + } + return { + enabled, + toggleActionId, + intervalSeconds, + setIntervalActionId, + lastPct, + retentionPct, + nextWarmAt, + lastWarmAt, + }; +} + +// ── Interval ↔ minutes/seconds (seconds capped at 59) ───────────────────────── + +export interface MinSec { + readonly minutes: number; + readonly seconds: number; +} + +export function clampSeconds(n: number): number { + if (!Number.isFinite(n)) return 0; + return Math.min(59, Math.max(0, Math.floor(n))); +} + +export function clampMinutes(n: number): number { + if (!Number.isFinite(n)) return 0; + return Math.max(0, Math.floor(n)); +} + +export function toMinSec(totalSeconds: number): MinSec { + const total = Math.max(0, Math.floor(totalSeconds)); + return { minutes: Math.floor(total / 60), seconds: total % 60 }; +} + +/** Combine a minutes + seconds pair (each clamped) into total seconds. */ +export function fromMinSec(minutes: number, seconds: number): number { + return clampMinutes(minutes) * 60 + clampSeconds(seconds); +} + +// ── Status + formatting ─────────────────────────────────────────────────────── + +export type WarmStatus = "success" | "warning" | "error"; + +/** Cache-hit % → semantic status (green high, yellow mid, red low). */ +export function statusForPct(pct: number): WarmStatus { + if (pct >= 80) return "success"; + if (pct >= 40) return "warning"; + return "error"; +} + +/** A status → its DaisyUI text-colour class (full literal so Tailwind keeps it). */ +export function colorClass(status: WarmStatus): string { + switch (status) { + case "success": + return "text-success"; + case "warning": + return "text-warning"; + case "error": + return "text-error"; + } +} + +/** The status line for a warm, matching the manual-warm feedback phrasing. */ +export function formatWarmLabel(pct: number): string { + return `Warmed — ${Math.round(pct)}% cache hit`; +} + +/** Seconds → a short countdown string (e.g. "3:05", "9s"). */ +export function formatCountdown(seconds: number): string { + const s = Math.max(0, Math.floor(seconds)); + if (s < 60) return `${s}s`; + const m = Math.floor(s / 60); + const rem = s % 60; + return `${m}:${String(rem).padStart(2, "0")}`; +} + +// ── Warming history reducer (keyed off the authoritative `lastWarmAt`) ───────── + +export interface WarmEntry { + readonly pct: number; + /** Authoritative epoch-ms of this warm (the surface's `lastWarmAt`). */ + readonly at: number; +} + +export interface WarmingViewState { + /** Warmings, MOST RECENT FIRST. */ + readonly history: readonly WarmEntry[]; + /** The last authoritative `lastWarmAt` recorded, for change-detection (de-dup key). */ + readonly lastWarmAt: number | null; +} + +const MAX_HISTORY = 50; + +export function initialWarmingState(): WarmingViewState { + return { history: [], lastWarmAt: null }; +} + +/** + * Fold the surface's authoritative `lastWarmAt` + current "last cache rate" into + * history. Records a new entry only when `lastWarmAt` CHANGED (a toggle/interval + * update re-pushes the same timestamp → no entry), de-duplicated on the timestamp + * (not the pct, so two warms with the same % both count). A null `lastWarmAt` is + * ignored; a null pct advances the de-dup key without adding an entry. + */ +export function observeWarm( + state: WarmingViewState, + lastWarmAt: number | null, + pct: number | null, +): WarmingViewState { + if (lastWarmAt === null || lastWarmAt === state.lastWarmAt) return state; + if (pct === null) return { ...state, lastWarmAt }; + const history = [{ pct, at: lastWarmAt }, ...state.history].slice(0, MAX_HISTORY); + return { history, lastWarmAt }; +} + +/** + * Seconds until the next automatic warm, AUTHORITATIVE: derived straight from the + * backend's `nextWarmAt` epoch-ms (never FE-anchored/guessed). `null` when nothing + * is scheduled (disabled, or a turn is generating so the timer is cancelled). + */ +export function secondsUntilNext(nextWarmAt: number | null, now: number): number | null { + if (nextWarmAt === null) return null; + return Math.max(0, Math.ceil((nextWarmAt - now) / 1000)); +} diff --git a/src/features/cache-warming/ui/CacheWarmingView.svelte b/src/features/cache-warming/ui/CacheWarmingView.svelte new file mode 100644 index 0000000..ced5e99 --- /dev/null +++ b/src/features/cache-warming/ui/CacheWarmingView.svelte @@ -0,0 +1,234 @@ + + +
+ + + + +
+ Refresh interval + + + m + + s + +
+ + + {#if !controls.enabled} +

Warming paused.

+ {:else if remaining !== null} +

Next warm in {formatCountdown(remaining)}

+ {:else} +

Next warm: waiting…

+ {/if} + + + {#if controls.retentionPct !== null} +

+ Cache retention: {controls.retentionPct}% +

+ {/if} + + + + + {#if !canWarm} +

Open or start a conversation to control its cache warming.

+ {:else if errorText} +

{errorText}

+ {:else if manualResult} + +

+ Warmed — {manualResult.expectedCacheRate}% retained ({manualResult.cachePct}% of prompt cached) +

+ {/if} + + + {#if latest} +
+ +
+ {formatWarmLabel(latest.pct)} +
+
+ {#if earlier.length > 0} + {#each earlier as entry, i (i)} +

{formatWarmLabel(entry.pct)}

+ {/each} + {:else} +

No earlier warmings.

+ {/if} +
+
+ {:else} +

No warming yet.

+ {/if} +
diff --git a/src/features/chat/ui/ChatView.svelte b/src/features/chat/ui/ChatView.svelte index 3d1421d..00691aa 100644 --- a/src/features/chat/ui/ChatView.svelte +++ b/src/features/chat/ui/ChatView.svelte @@ -3,10 +3,12 @@ import { interleaveTurnMetrics, viewCacheRate, + viewExpectedCache, viewStepMetrics, viewTurnMetrics, type TurnMetricsEntry, } from "../../../core/metrics"; + import { Markdown } from "../../markdown"; const badgeClass = { success: "badge-success", @@ -113,7 +115,7 @@
{#if rendered.chunk.type === "text"} -

{rendered.chunk.text}

+ {:else if rendered.chunk.type === "error"}