From 01f9fb2a4ad6110def531ead16b370c818e8ee81 Mon Sep 17 00:00:00 2001
From: Adam Malczewski <github@tradam.dev>
Date: Mon, 19 Oct 2026 17:02:40 +0900
Subject: feat(chat): cache timer for Claude Code subscription models

Per-step and per-turn timers for the gaps between model requests (the
Claude prompt cache expires after 5 min idle). A step gap runs live under
the executing tools from step-complete until its last tool result (or the
next step's output), then is stamped on that step's metrics line beside
its cache badge. A turn gap runs live on the turn's metrics line from
done/error until the next message is sent, then is stamped there. Counts
m:ss up to 10 min, then '10+ min'; colour tracks the 5-min TTL.

Gated on claude/<model>. Pure reducer in core/metrics/cache-timer.ts;
the turn gap is seeded from an idle conversation's lastActivityAt so it
survives a reload. Stamps are in-memory only.
---
 src/features/chat/ui/CacheTimerBadge.svelte | 58 +++++++++++++++++++++++++++
 src/features/chat/ui/ChatView.svelte        | 62 ++++++++++++++++++++++++++++-
 2 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 src/features/chat/ui/CacheTimerBadge.svelte

(limited to 'src/features/chat/ui')

diff --git a/src/features/chat/ui/CacheTimerBadge.svelte b/src/features/chat/ui/CacheTimerBadge.svelte
new file mode 100644
index 0000000..e5abed5
--- /dev/null
+++ b/src/features/chat/ui/CacheTimerBadge.svelte
@@ -0,0 +1,58 @@
+<script lang="ts">
+  /**
+   * One cache-timer badge. LIVE when given `since` (counts up from that epoch
+   * ms, ticking once a second, and stops ticking at the 10-minute cap); STAMPED
+   * when given `elapsedMs` (a finished gap — static). Formatting lives in
+   * `core/metrics` (`viewCacheTimer`). Owning the tick here means only this
+   * badge re-renders each second, not the transcript.
+   */
+  import { untrack } from "svelte";
+  import { CACHE_TIMER_MAX_MS, viewCacheTimer } from "../../../core/metrics";
+
+  let {
+    since,
+    elapsedMs,
+    now = Date.now,
+  }: {
+    /** Live: epoch ms the gap started. */
+    since?: number;
+    /** Stamped: the gap's final duration (wins over `since`). */
+    elapsedMs?: number;
+    /** Wall clock (injected for tests). */
+    now?: () => number;
+  } = $props();
+
+  // Initial read only (the effect below keeps it current while live).
+  let current = $state(untrack(() => now()));
+
+  $effect(() => {
+    if (elapsedMs !== undefined || since === undefined) return;
+    const start = since;
+    current = now();
+    if (current - start >= CACHE_TIMER_MAX_MS) return;
+    const id = setInterval(() => {
+      current = now();
+      if (current - start >= CACHE_TIMER_MAX_MS) clearInterval(id);
+    }, 1000);
+    return () => clearInterval(id);
+  });
+
+  const badgeClass = {
+    success: "badge-success",
+    warning: "badge-warning",
+    error: "badge-error",
+  } as const;
+
+  const live = $derived(elapsedMs === undefined);
+  const view = $derived(viewCacheTimer(elapsedMs ?? current - (since ?? current)));
+</script>
+
+<span
+  class="badge badge-sm gap-1 font-mono tabular-nums {badgeClass[view.level]}"
+  class:badge-outline={!live}
+  title={live
+    ? "Cache timer (running): time since the last model request. The Claude prompt cache expires after 5 minutes idle."
+    : "Cache timer (stopped): how long the cache sat idle before the next request. The Claude prompt cache expires after 5 minutes idle."}
+  data-testid={live ? "cache-timer-live" : "cache-timer-stamp"}
+  ><span aria-hidden="true">⏱</span>{view.label}</span
+>
diff --git a/src/features/chat/ui/ChatView.svelte b/src/features/chat/ui/ChatView.svelte
index 18fea7c..e641791 100644
--- a/src/features/chat/ui/ChatView.svelte
+++ b/src/features/chat/ui/ChatView.svelte
@@ -2,7 +2,9 @@
   import type { TurnProviderRetryEvent } from "@dispatch/wire";
   import { groupRenderedChunks, resolveImageUrl, type RenderedChunk, viewProviderRetry } from "../index";
   import {
+    type CacheTimerState,
     interleaveTurnMetrics,
+    lastTurnRowIndex,
     viewCacheRate,
     viewExpectedCache,
     viewStepMetrics,
@@ -10,6 +12,7 @@
     type TurnMetricsEntry,
   } from "../../../core/metrics";
   import { Markdown } from "../../markdown";
+  import CacheTimerBadge from "./CacheTimerBadge.svelte";
   import LazyCollapse from "./LazyCollapse.svelte";
   import ToolCard from "./ToolCard.svelte";
 
@@ -27,6 +30,7 @@
     thinkingKeyBase = 0,
     providerRetry = null,
     apiBaseUrl = "",
+    cacheTimer = null,
   }: {
     chunks: readonly RenderedChunk[];
     turnMetrics?: readonly TurnMetricsEntry[];
@@ -55,6 +59,14 @@
      * "" (root-relative — a browser resolves `/images/…` against its origin).
      */
     apiBaseUrl?: string;
+    /**
+     * The cache timer (gaps between model requests): a running step gap shows
+     * live at the bottom (under the executing tools), a running turn gap live
+     * on that turn's metrics row; finished gaps are stamped on their step /
+     * turn metrics line. `null` (the default) hides it entirely — the caller
+     * gates on the model.
+     */
+    cacheTimer?: CacheTimerState | null;
   } = $props();
 
   // True while a show-earlier page-in is awaited (disables the button).
@@ -74,6 +86,31 @@
 
   const rows = $derived(interleaveTurnMetrics(groups, turnMetrics));
 
+  // A SEEDED turn gap (no turnId — e.g. after a reload) renders on the most
+  // recent turn's row (when no user message follows it).
+  const seededTurnRow = $derived(
+    cacheTimer?.running?.kind === "turn" && cacheTimer.running.turnId === null
+      ? lastTurnRowIndex(rows)
+      : null,
+  );
+
+  /** Start of the running turn gap if it belongs on this turn row, else undefined. */
+  function liveTurnSince(turnId: string, rowIndex: number): number | undefined {
+    const r = cacheTimer?.running;
+    if (r?.kind !== "turn") return undefined;
+    if (r.turnId === turnId || (r.turnId === null && rowIndex === seededTurnRow)) {
+      return r.startedAt;
+    }
+    return undefined;
+  }
+
+  // A running step gap with tool calls → the live timer under the executing tools.
+  const liveStepGap = $derived(
+    cacheTimer?.running?.kind === "step" && cacheTimer.running.toolCount > 0
+      ? cacheTimer.running
+      : null,
+  );
+
   // Tool cards use toolCallId keys across pending/result/seal and orphan page-in.
   // Stable per-row keys. Thinking blocks get an ordinal key (`think<n>`) that
   // survives the provisional→committed (seq null → seq N) transition, so the
@@ -180,13 +217,14 @@
       </button>
     </div>
   {/if}
-  {#each keyedRows as { row, key } (key)}
+  {#each keyedRows as { row, key }, i (key)}
     <!-- `.chat-row`: content-visibility:auto — the browser skips layout/paint
          for rows outside the viewport (see app.css). -->
     <div class="chat-row">
     {#if row.kind === "step-metrics"}
       {@const sv = viewStepMetrics(row.step, row.index)}
       {@const stepCache = viewCacheRate(row.step.usage)}
+      {@const stepStamp = cacheTimer?.stepStamps.get(row.step.stepId)}
       <div class="chat chat-start">
         <div class="chat-bubble w-full max-w-5xl bg-transparent p-0">
           <div class="flex flex-wrap items-center gap-x-1 text-xs">
@@ -203,6 +241,9 @@
               class="badge badge-xs {badgeClass[stepCache.level]}"
               data-testid="step-cache-badge">{stepCache.pct}%</span
             >
+            {#if stepStamp !== undefined}
+              <CacheTimerBadge elapsedMs={stepStamp} />
+            {/if}
           </div>
         </div>
       </div>
@@ -211,6 +252,8 @@
       {@const lastCache = viewCacheRate(row.turn.usage)}
       {@const chatCache = viewCacheRate(row.cumulativeUsage)}
       {@const retention = viewExpectedCache(row.turn.steps[0]?.usage, row.prevLastStepUsage)}
+      {@const turnLive = liveTurnSince(row.turn.turnId, i)}
+      {@const turnStamp = cacheTimer?.turnStamps.get(row.turn.turnId)}
       <div class="chat chat-start">
         <div class="chat-bubble w-full max-w-5xl bg-transparent p-0">
           <div class="flex flex-col gap-1 text-xs">
@@ -236,6 +279,11 @@
                   <span class="badge badge-sm {badgeClass[retention.level]}">{retention.pct}%</span>
                 </span>
               {/if}
+              {#if turnLive !== undefined}
+                <CacheTimerBadge since={turnLive} />
+              {:else if turnStamp !== undefined}
+                <CacheTimerBadge elapsedMs={turnStamp} />
+              {/if}
             </div>
           </div>
         </div>
@@ -252,6 +300,18 @@
     {/if}
     </div>
   {/each}
+  {#if liveStepGap}
+    <!-- Live cache timer while the last step's tools execute; stamped onto that
+         step's metrics line once they return (or the next step starts). -->
+    <div class="chat chat-start">
+      <div class="chat-bubble w-full max-w-5xl bg-transparent p-0">
+        <div class="flex items-center gap-1 text-xs" data-testid="cache-timer-tools">
+          <span class="opacity-70">Running tools</span>
+          <CacheTimerBadge since={liveStepGap.startedAt} />
+        </div>
+      </div>
+    </div>
+  {/if}
   {#if providerRetry}
     {@const rv = viewProviderRetry(providerRetry)}
     <!-- Transient yellow warning: a provider error is being retried with backoff.
-- 
cgit v1.2.3