@promptctl/cc-candybar 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,10 +91,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.4.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.4.0",
-    "@promptctl/cc-candybar-linux-x64": "1.4.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.4.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.5.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.5.0",
+    "@promptctl/cc-candybar-linux-x64": "1.5.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.5.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/config/default-dsl-config.ts

@@ -386,6 +386,31 @@ export const DEFAULT_DSL_CONFIG = {
     "burn.eta.warnMinutes": { kind: "literal", value: 60 },
     "burn.eta.errorMinutes": { kind: "literal", value: 30 },
 
+    // Token throughput for the active turn — daemon-derived tok/s on three lanes
+    // (render-payload.ts: successive-render delta over the SessionUsageStore).
+    // Same absence idiom as burn: -1 is the structurally-impossible default the
+    // `formatSpeed` helper reads as "—" [LAW:no-silent-failure] (0 tok/s is a
+    // real reading, so it cannot double as the absence marker). Each lane is
+    // independently absent — `input` reads "—" mid-stream while `output` flows.
+    "speed.input": {
+      kind: "input",
+      path: "speed.input",
+      type: "number",
+      default: -1,
+    },
+    "speed.output": {
+      kind: "input",
+      path: "speed.output",
+      type: "number",
+      default: -1,
+    },
+    "speed.total": {
+      kind: "input",
+      path: "speed.total",
+      type: "number",
+      default: -1,
+    },
+
     // Context — daemon fetches via ContextProvider; contextLeftPercentage.
     "context.totalTokens": {
       kind: "input",
@@ -581,6 +606,23 @@ export const DEFAULT_DSL_CONFIG = {
       fg: etaHeatFg(".block.etaMinutes", ".burn.eta.warnMinutes"),
       when: "{{ or (gt .block.resetsAt 0) (gt .weekly.resetsAt 0) }}",
     },
+    // Token throughput for the active turn — output / input / total tok/s, each a
+    // successive-render delta computed daemon-side (render-payload.ts); the
+    // template only formats. Declared-but-opt-in (NOT in the default root, like
+    // block/weekly/burnrate): a user adds `speed` to their layout. Each lane reads
+    // "—" when idle/between turns ([LAW:no-silent-failure] — never a stale or
+    // divide-by-zero number). Visible once the session has done any work (stable,
+    // no layout flicker); `output` is the live generation rate, `input` spikes at
+    // turn start, `total` is their sum.
+    speed: {
+      template:
+        ' ⇅ out {{ template "formatSpeed" .speed.output }} · ' +
+        'in {{ template "formatSpeed" .speed.input }} · ' +
+        'tot {{ template "formatSpeed" .speed.total }} ',
+      bg: "panel",
+      fg: "foreground",
+      when: "{{ gt .session.tokens 0 }}",
+    },
     // Prompt-cache warmth countdown. minutesUntilReset clamps a past expiry
     // to 0, so an expired cache renders "cold" (and reads red via the ≤8
     // arm) rather than a negative number. [LAW:dataflow-not-control-flow]
@@ -759,6 +801,11 @@ export const DEFAULT_DSL_CONFIG = {
     // daemon could not project (-1 sentinel). Reuses the long-remaining cascade.
     formatEta:
       '{{ if lt . 0 }}—{{ else }}{{ template "formatLongTimeRemaining" . }}{{ end }}',
+    // Token throughput: "N/s" (K/M-scaled, rounded) when measured (>= 0), "—"
+    // when the daemon had no projectable sample (-1). Branches on the VALUE, like
+    // formatRate; reuses formatTokenCount so the K/M scale policy has one home.
+    formatSpeed:
+      '{{ if lt . 0 }}—{{ else }}{{ template "formatTokenCount" (round .) }}/s{{ end }}',
     // Breakdown over a dict {input, output, cacheCreation, cacheRead}; each present
     // part is formatted by the shared formatTokenCount and joined with " + ". A
     // `$first` flag (reassigned across if-frames) inserts the separator before all

package/src/daemon/cache/session-usage-store.ts

@@ -47,6 +47,42 @@ export interface TodayInfo {
   date: string;
 }
 
+// [LAW:one-source-of-truth] One observation of the active session's cumulative
+// token counts at a single instant. tok/s is the delta between two of these —
+// the prior sample lives in this store (the single owner of per-session token
+// totals), never in a parallel counter. `input` folds the cache lanes into the
+// prompt-side total so `total === input + output`. `atMs` is the render's clock
+// instant (the daemon's single-enforcer clock), so a frozen test clock makes
+// the rate deterministic.
+export interface SpeedSample {
+  readonly input: number;
+  readonly output: number;
+  readonly total: number;
+  readonly atMs: number;
+}
+
+// The prior observation (absent on the very first render of a session) and the
+// one just taken. The pure rate projection lives at the render-payload boundary;
+// this store only remembers and reports the pair.
+export interface SpeedObservation {
+  readonly prev?: SpeedSample;
+  readonly cur: SpeedSample;
+}
+
+function speedSampleOf(
+  breakdown: TokenBreakdown | null,
+  atMs: number,
+): SpeedSample {
+  // Prompt-side = raw input plus both cache lanes (all tokens fed to the model);
+  // output = generated. total = the same sum the store's `tokens` projection
+  // uses, so `total === input + output`. [LAW:one-source-of-truth]
+  const input = breakdown
+    ? breakdown.input + breakdown.cacheCreation + breakdown.cacheRead
+    : 0;
+  const output = breakdown ? breakdown.output : 0;
+  return { input, output, total: input + output, atMs };
+}
+
 // Per-(session, day) scalar contribution — the only granularity the today fold
 // needs. Raw entries are discarded after bucketing, so per-session retained
 // memory is O(retained-days), not O(entries).
@@ -166,6 +202,17 @@ export class SessionUsageStore {
   // first seed completes every later read awaits an already-settled promise —
   // zero rescan. A rejected seed is dropped so the next read retries.
   private readonly seeded = new Map<string, Promise<void>>();
+  // [LAW:one-source-of-truth] The prior tok/s observation per session. tok/s is
+  // a derivative of the SAME token totals the records map already owns; the
+  // baseline (prev counts + time) lives HERE, not in a parallel counter. One
+  // call to observeSpeed advances it; the pure delta math is render-payload's.
+  private readonly speedSamples = new Map<string, SpeedSample>();
+  // [LAW:no-ambient-temporal-coupling] Explicit owner of observe/commit ordering
+  // for the speed sample. Concurrent renders observing the SAME transcript state
+  // (key = `${sessionId}:${mtime}`) share ONE observation and commit the baseline
+  // exactly once — so they return the same prev+cur and render identical,
+  // deterministic throughput instead of the second clobbering the first.
+  private readonly speedFlight = new SingleFlight();
   private readonly maxEntries: number;
   private readonly staleAgeMs: number;
   private hits = 0;
@@ -284,6 +331,37 @@ export class SessionUsageStore {
     });
   }
 
+  // Take one tok/s observation of the active session: ingest its current
+  // cumulative counts, return the prior sample alongside, and record this one as
+  // the new baseline. [LAW:no-silent-failure] A failed transcript parse flows out
+  // as `failed` (the boundary logs it and the segment reads "—"); an unknown
+  // session yields a zero-count sample, so a first-ever render establishes a
+  // baseline without fabricating a rate. `nowMs` is the caller's single-enforcer
+  // clock instant — the store never reads the clock for tok/s timing itself.
+  async observeSpeed(
+    sessionId: string,
+    transcriptPath: string | undefined,
+    nowMs: number,
+  ): Promise<Outcome<SpeedObservation>> {
+    // [LAW:no-ambient-temporal-coupling] Key the observation by the same
+    // (session, mtime) tuple ingest uses, so concurrent renders at one transcript
+    // state coalesce onto a single observe-and-commit — the read of `prev` and
+    // the write of `cur` happen exactly once for that state, with the flight as
+    // the sole owner of ordering. A distinct mtime is a genuinely new sample and
+    // gets its own key.
+    const mtime = statMtimeMs(transcriptPath);
+    return this.speedFlight.run(`${sessionId}:${mtime}`, async () => {
+      const record = await this.ingest(sessionId, transcriptPath, mtime);
+      if (record.kind === "failed") return record;
+      const breakdown =
+        record.kind === "ok" ? record.value.sessionInfo.tokenBreakdown : null;
+      const cur = speedSampleOf(breakdown, nowMs);
+      const prev = this.speedSamples.get(sessionId);
+      this.speedSamples.set(sessionId, cur);
+      return ok({ ...(prev !== undefined && { prev }), cur });
+    });
+  }
+
   // mtime-gated, coalesced re-parse of ONE session. `ok` is its record,
   // `absent` is an unknown empty session (or no sessionId), `failed` is a
   // transcript that exists but couldn't be parsed — NOT cached (only ok
@@ -416,6 +494,7 @@ export class SessionUsageStore {
     for (const [sid, record] of this.entries) {
       if (now - record.lastSeenAt > this.staleAgeMs) {
         this.entries.delete(sid);
+        this.speedSamples.delete(sid);
         dropped++;
       }
     }
@@ -431,6 +510,7 @@ export class SessionUsageStore {
       const oldest = this.entries.keys().next().value;
       if (oldest === undefined) break;
       this.entries.delete(oldest);
+      this.speedSamples.delete(oldest);
       dlog("info", `usageStore evict ${oldest}`);
     }
   }
@@ -442,5 +522,6 @@ export class SessionUsageStore {
     }
     this.entries.clear();
     this.seeded.clear();
+    this.speedSamples.clear();
   }
 }

package/src/daemon/render-payload.ts

@@ -25,7 +25,10 @@ import type { GitInfo, GitInfoOptions } from "../segments/git.js";
 import { ABSENT, failed, type Outcome } from "../utils/outcome.js";
 import { cacheExpiresAt } from "../segments/cache.js";
 import type { DaemonLogger } from "./log.js";
-import type { SessionUsageStore } from "./cache/session-usage-store.js";
+import type {
+  SessionUsageStore,
+  SpeedObservation,
+} from "./cache/session-usage-store.js";
 import type { ContextProvider } from "../segments/context.js";
 import type { MetricsProvider } from "../segments/metrics.js";
 import type { TmuxService } from "../segments/tmux.js";
@@ -65,6 +68,7 @@ export interface RenderPayload extends ClaudeHookData {
   readonly session?: SessionPayload;
   readonly today?: TodayPayload;
   readonly burn?: BurnPayload;
+  readonly speed?: SpeedPayload;
   readonly block?: BlockPayload;
   readonly weekly?: WeeklyPayload;
   readonly cache?: CachePayload;
@@ -115,6 +119,19 @@ export interface BurnPayload {
   readonly costPerHour?: number;
 }
 
+// [LAW:one-type-per-behavior] Token throughput for the active turn — tokens per
+// second on each of three lanes (prompt-side input, generated output, their
+// total). Each lane is INDEPENDENTLY optional: during streaming `output` moves
+// while `input` (fixed at turn start) is idle, so an absent `input` rate beside a
+// live `output` rate is the honest shape, not a zero. Absence (no baseline yet,
+// idle between turns, or a too-stale prior sample) travels as a missing field to
+// the -1 default, which the `formatSpeed` helper reads as "—". [LAW:no-silent-failure]
+export interface SpeedPayload {
+  readonly input?: number;
+  readonly output?: number;
+  readonly total?: number;
+}
+
 export interface BlockPayload {
   readonly nativeUtilization: number;
   readonly resetsAt: number;
@@ -200,6 +217,15 @@ const MIN_PROJECTABLE_ELAPSED_MS = 5 * 60 * 1000;
 // $/hr is dominated by a single turn rather than a sustained burn.
 const MIN_BURN_SECONDS = 60;
 
+// tok/s is a delta between two successive render observations. The wall-time
+// between them must clear a tiny floor (the clock has to have advanced — below
+// it the rate is divide-by-near-zero noise) and stay under a ceiling: a gap
+// wider than this means the prior sample predates an idle stretch, so the rate
+// would be diluted by dead time. Both bounds → no reading (re-baseline silently
+// on the next render) rather than a misleading number. [LAW:no-silent-failure]
+const MIN_SPEED_SAMPLE_MS = 50;
+const MAX_SPEED_SAMPLE_MS = 10 * 1000;
+
 /**
  * Linearly extrapolate a rate-limit window's utilization to its 100% cap.
  * The window started `windowMs` before `resetsAtSec`; elapsed time and the
@@ -236,6 +262,64 @@ export function projectCostPerHour(
   return (cost * 3600) / durationSeconds;
 }
 
+/**
+ * Instantaneous tokens-per-second between two successive render observations of
+ * one cumulative token count. Returns undefined when the sample window is too
+ * small or too large to be honest (see the floor/ceiling constants) or when the
+ * count did not advance (idle / between turns — a true 0 over a real window is
+ * reported as 0, but a flat count carries no throughput to report). A real
+ * positive rate is always >= 0, so callers use -1 as the absence default — 0
+ * tok/s never doubles as the "no reading" marker. [LAW:no-silent-failure]
+ */
+export function projectTokensPerSecond(
+  prevTokens: number,
+  prevMs: number,
+  curTokens: number,
+  nowMs: number,
+): number | undefined {
+  const deltaMs = nowMs - prevMs;
+  if (deltaMs < MIN_SPEED_SAMPLE_MS || deltaMs > MAX_SPEED_SAMPLE_MS)
+    return undefined;
+  const deltaTokens = curTokens - prevTokens;
+  if (deltaTokens <= 0) return undefined;
+  return (deltaTokens * 1000) / deltaMs;
+}
+
+// [LAW:effects-at-boundaries] Pure fold of one speed observation into the
+// payload's three rate lanes. No baseline (first render of a session) or every
+// lane un-projectable → undefined (the whole `speed` key is dropped); otherwise
+// each lane that projects contributes its rate, each that doesn't is a missing
+// field → the -1 default → "—".
+function projectSpeed(obs: SpeedObservation): SpeedPayload | undefined {
+  const { prev, cur } = obs;
+  if (prev === undefined) return undefined;
+  const input = projectTokensPerSecond(
+    prev.input,
+    prev.atMs,
+    cur.input,
+    cur.atMs,
+  );
+  const output = projectTokensPerSecond(
+    prev.output,
+    prev.atMs,
+    cur.output,
+    cur.atMs,
+  );
+  const total = projectTokensPerSecond(
+    prev.total,
+    prev.atMs,
+    cur.total,
+    cur.atMs,
+  );
+  if (input === undefined && output === undefined && total === undefined)
+    return undefined;
+  return {
+    ...(input !== undefined && { input }),
+    ...(output !== undefined && { output }),
+    ...(total !== undefined && { total }),
+  };
+}
+
 // ─── Builder ─────────────────────────────────────────────────────────────────
 
 // ─── Config-driven provider gating ───────────────────────────────────────────
@@ -428,6 +512,11 @@ export async function buildRenderPayload(
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
 
+  // [LAW:single-enforcer] One clock read feeds every projection this render —
+  // the ETA extrapolations below AND the tok/s sample window in the speed lane,
+  // so an ETA, a reset countdown, and a throughput figure all agree on "now".
+  const nowMs = (deps.clock ?? (() => new Date()))().getTime();
+
   // [LAW:dataflow-not-control-flow][LAW:one-type-per-behavior] Every provider
   // lane is ONE shape: "needed → call provider (whose contract is to never
   // reject — the catch makes the lane total against bugs, mapping a throw
@@ -443,40 +532,57 @@ export async function buildRenderPayload(
       ? run().catch((e: unknown) => failed(`${name}: ${String(e)}`))
       : Promise.resolve(ABSENT);
 
-  const [gitOutcome, usage, today, context, metrics, tmuxSession, cacheExpiry] =
-    await Promise.all([
-      lane("git", wants("git"), () =>
-        deps.gitProvider.getGitInfo(
-          cwd ?? hookData.workspace?.current_dir,
-          gitOptionsFromClosure(neededInputPaths),
-          hookData.workspace?.project_dir,
-        ),
-      ),
-      // [LAW:dataflow-not-control-flow] The burn segment reads `burn.costPerHour`,
-      // a derivative of session cost and metrics duration — so wanting `burn`
-      // pulls in exactly the two lanes it is folded from.
-      lane(
-        "session",
-        wants("session.cost") || wants("session.tokens") || wants("burn"),
-        () => deps.usageStore.getUsageInfo(hookData.session_id, hookData),
+  const [
+    gitOutcome,
+    usage,
+    today,
+    context,
+    metrics,
+    tmuxSession,
+    cacheExpiry,
+    speed,
+  ] = await Promise.all([
+    lane("git", wants("git"), () =>
+      deps.gitProvider.getGitInfo(
+        cwd ?? hookData.workspace?.current_dir,
+        gitOptionsFromClosure(neededInputPaths),
+        hookData.workspace?.project_dir,
       ),
-      lane("today", wants("today"), () =>
-        deps.usageStore.getTodayInfo(hookData),
-      ),
-      lane("context", wants("context"), () =>
-        deps.contextProvider.getContextInfo(hookData),
-      ),
-      lane("metrics", wants("metrics") || wants("burn"), () =>
-        deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
-      ),
-      lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
-      // Prompt-cache expiry: a bounded tail-read through the gated transcript-fs
-      // seam, so it runs alongside the other providers and stays in the shared
-      // in-flight budget rather than blocking the event loop on sync fs.
-      lane("cache", wants("cache"), () =>
-        cacheExpiresAt(hookData.transcript_path),
+    ),
+    // [LAW:dataflow-not-control-flow] The burn segment reads `burn.costPerHour`,
+    // a derivative of session cost and metrics duration — so wanting `burn`
+    // pulls in exactly the two lanes it is folded from.
+    lane(
+      "session",
+      wants("session.cost") || wants("session.tokens") || wants("burn"),
+      () => deps.usageStore.getUsageInfo(hookData.session_id, hookData),
+    ),
+    lane("today", wants("today"), () => deps.usageStore.getTodayInfo(hookData)),
+    lane("context", wants("context"), () =>
+      deps.contextProvider.getContextInfo(hookData),
+    ),
+    lane("metrics", wants("metrics") || wants("burn"), () =>
+      deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
+    ),
+    lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
+    // Prompt-cache expiry: a bounded tail-read through the gated transcript-fs
+    // seam, so it runs alongside the other providers and stays in the shared
+    // in-flight budget rather than blocking the event loop on sync fs.
+    lane("cache", wants("cache"), () =>
+      cacheExpiresAt(hookData.transcript_path),
+    ),
+    // [LAW:one-source-of-truth] tok/s folds from the SAME store the session
+    // lane reads — observeSpeed both reports the prior sample and records this
+    // render's, so it must run every render the speed segment is laid out (the
+    // first establishes the baseline that the second projects from).
+    lane("speed", wants("speed"), () =>
+      deps.usageStore.observeSpeed(
+        hookData.session_id,
+        hookData.transcript_path,
+        nowMs,
       ),
-    ]);
+    ),
+  ]);
   // [LAW:effects-at-boundaries] The projections are pure folds returning data
   // (payload fragment + failure descriptions); the log effect happens once,
   // here, at the edge. `take` is the total fold for the single-value lanes:
@@ -505,8 +611,6 @@ export async function buildRenderPayload(
   // the formatter func — a duplicate code path was retired.)
   const fiveHour = hookData.rate_limits?.five_hour;
   const sevenDay = hookData.rate_limits?.seven_day;
-  // [LAW:single-enforcer] One clock read feeds every projection this render.
-  const nowMs = (deps.clock ?? (() => new Date()))().getTime();
   const blockEta = fiveHour
     ? projectEtaMinutes(
         fiveHour.used_percentage,
@@ -532,6 +636,13 @@ export async function buildRenderPayload(
     wants("burn") && burnCost != null && burnDuration != null
       ? projectCostPerHour(burnCost, burnDuration)
       : undefined;
+  // [LAW:effects-at-boundaries] The store reported the prev+cur samples (an
+  // effect: it read state and advanced the baseline); the rate is a pure fold of
+  // that data here at the edge. Absent observation (lane skipped/failed) or no
+  // projectable lane → no `speed` key → every lane reads its -1 default.
+  const speedObs = take(speed);
+  const speedPayload =
+    speedObs !== undefined ? projectSpeed(speedObs) : undefined;
 
   // [LAW:one-source-of-truth] The theme variable surfaces the session's
   // resolved theme so the toolbar/tray DSL templates can encode it into
@@ -597,6 +708,7 @@ export async function buildRenderPayload(
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
     ...(costPerHour !== undefined && { burn: { costPerHour } }),
+    ...(speedPayload !== undefined && { speed: speedPayload }),
     ...(wants("block") &&
       fiveHour !== undefined && {
         block: {