@promptctl/cc-candybar 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.1.1",
+  "version": "1.2.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.1.1",
-    "@promptctl/cc-candybar-darwin-x64": "1.1.1",
-    "@promptctl/cc-candybar-linux-x64": "1.1.1",
-    "@promptctl/cc-candybar-linux-arm64": "1.1.1"
+    "@promptctl/cc-candybar-darwin-arm64": "1.2.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.2.0",
+    "@promptctl/cc-candybar-linux-x64": "1.2.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.2.0"
   },
   "pnpm": {
     "supportedArchitectures": {

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

@@ -108,6 +108,29 @@ function blockLikeFg(pctRef: string): string {
   );
 }
 
+// [LAW:dataflow-not-control-flow] The burn segment heats as the cap NEARS, so
+// the cascade reads the projected minutes-to-cap (smaller = hotter), the
+// inverse direction of blockLikeBg's fuller-is-hotter. The not-projectable
+// sentinel (-1, sorts below every threshold) is caught first so "we cannot
+// project" colors calm, never error. Thresholds are var refs so a user
+// overrides them through the same by-name variables cascade.
+function etaHeatBg(etaRef: string, warnRef: string, errRef: string): string {
+  return (
+    `{{ if lt ${etaRef} 0 }}panel` +
+    `{{ else }}{{ if lt ${etaRef} ${errRef} }}error` +
+    `{{ else }}{{ if lt ${etaRef} ${warnRef} }}warning` +
+    `{{ else }}panel{{ end }}{{ end }}{{ end }}`
+  );
+}
+
+function etaHeatFg(etaRef: string, warnRef: string): string {
+  return (
+    `{{ if lt ${etaRef} 0 }}foreground` +
+    `{{ else }}{{ if lt ${etaRef} ${warnRef} }}button-color-foreground` +
+    `{{ else }}foreground{{ end }}{{ end }}`
+  );
+}
+
 // ─── The default config ──────────────────────────────────────────────────────
 
 export const DEFAULT_DSL_CONFIG = {
@@ -327,6 +350,34 @@ export const DEFAULT_DSL_CONFIG = {
     },
     "weekly.budget.warningThreshold": { kind: "literal", value: 80 },
 
+    // Burn rate + cap projection — daemon-derived (see render-payload.ts).
+    // Each projection is ABSENT when not projectable; the var-system fills the
+    // -1 default, a structurally-impossible value the burnrate helpers read as
+    // "—" [LAW:no-silent-failure] (0 minutes / $0-per-hr are real, displayable
+    // values, so they cannot double as the absence marker).
+    "burn.costPerHour": {
+      kind: "input",
+      path: "burn.costPerHour",
+      type: "number",
+      default: -1,
+    },
+    "block.etaMinutes": {
+      kind: "input",
+      path: "block.etaMinutes",
+      type: "number",
+      default: -1,
+    },
+    "weekly.etaMinutes": {
+      kind: "input",
+      path: "weekly.etaMinutes",
+      type: "number",
+      default: -1,
+    },
+    // ETA-heat thresholds (minutes-to-cap) — overridable per-config through the
+    // variables-merge-by-name cascade, like the *.budget.warningThreshold knobs.
+    "burn.eta.warnMinutes": { kind: "literal", value: 60 },
+    "burn.eta.errorMinutes": { kind: "literal", value: 30 },
+
     // Context — daemon fetches via ContextProvider; contextLeftPercentage.
     "context.totalTokens": {
       kind: "input",
@@ -486,6 +537,24 @@ export const DEFAULT_DSL_CONFIG = {
       fg: blockLikeFg(".weekly.percentage"),
       when: "{{ gt .weekly.resetsAt 0 }}",
     },
+    // Burn rate + cap projection: "$X/hr · Nm to 5h · Nd to wk". The headline
+    // number of a usage monitor — how fast you are spending and when you hit
+    // the wall. All math is daemon-side (render-payload.ts); the template only
+    // formats. Heats as the 5h cap nears (etaHeat*). Shown when either
+    // rate-limit window is active — the same signal block/weekly gate on.
+    burnrate: {
+      template:
+        ' ⚡ {{ template "formatRate" .burn.costPerHour }} · ' +
+        '{{ template "formatEta" .block.etaMinutes }} to 5h · ' +
+        '{{ template "formatEta" .weekly.etaMinutes }} to wk ',
+      bg: etaHeatBg(
+        ".block.etaMinutes",
+        ".burn.eta.warnMinutes",
+        ".burn.eta.errorMinutes",
+      ),
+      fg: etaHeatFg(".block.etaMinutes", ".burn.eta.warnMinutes"),
+      when: "{{ or (gt .block.resetsAt 0) (gt .weekly.resetsAt 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]
@@ -592,6 +661,16 @@ export const DEFAULT_DSL_CONFIG = {
       '{{ else if ge . 1000 }}{{ printf "%.1f" (divf . 1000) }}K' +
       "{{ else }}{{ . }}{{ end }}",
     formatTokens: '{{ template "formatTokenCount" . }} tokens',
+    // Burn rate: "$X.XX/hr" when projectable, "—/hr" otherwise. The daemon
+    // emits -1 (a structurally-impossible rate) for not-projectable, so the
+    // branch reads a VALUE, never a hidden control-flow flag. Reuses formatCost
+    // so the dollar policy has one home.
+    formatRate:
+      '{{ if lt . 0 }}—/hr{{ else }}{{ template "formatCost" . }}/hr{{ end }}',
+    // ETA to a rate-limit cap: humanized minutes when projectable, "—" when the
+    // daemon could not project (-1 sentinel). Reuses the long-remaining cascade.
+    formatEta:
+      '{{ if lt . 0 }}—{{ else }}{{ template "formatLongTimeRemaining" . }}{{ 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/render-payload.ts

@@ -64,6 +64,7 @@ export interface RenderPayload extends ClaudeHookData {
   // exactly like a missing top-level field.
   readonly session?: SessionPayload;
   readonly today?: TodayPayload;
+  readonly burn?: BurnPayload;
   readonly block?: BlockPayload;
   readonly weekly?: WeeklyPayload;
   readonly cache?: CachePayload;
@@ -105,14 +106,31 @@ export interface TodayPayload {
   readonly tokens?: number;
 }
 
+// [LAW:one-type-per-behavior] The burn rate is the session's spend velocity —
+// dollars per wall-clock hour — a derivative of the same cost the `session`
+// segment totals, so it is its own concept, not a field bolted onto the
+// totals. Optional because a too-young session yields no honest rate
+// ([LAW:no-silent-failure] — absence over a single-turn artifact).
+export interface BurnPayload {
+  readonly costPerHour?: number;
+}
+
 export interface BlockPayload {
   readonly nativeUtilization: number;
   readonly resetsAt: number;
+  // [LAW:types-are-the-program] Linear projection of nativeUtilization → 100%
+  // at the current rate, in whole minutes. Absent (not 0, not a sentinel
+  // in the type) when the window is too young or shows no usage to project
+  // from — the ETA's "we cannot say" state is unrepresentable as a number,
+  // so it travels as a missing field to the DSL default. [LAW:no-silent-failure]
+  readonly etaMinutes?: number;
 }
 
 export interface WeeklyPayload {
   readonly percentage: number;
   readonly resetsAt: number;
+  // Same projection as BlockPayload.etaMinutes over the seven-day window.
+  readonly etaMinutes?: number;
 }
 
 // Prompt-cache warmth. One field — the epoch-seconds expiry instant —
@@ -158,6 +176,64 @@ export interface RenderPayloadDeps {
   // buildRenderPayload is the ONE place lane failures are logged, so the
   // providers' interiors never log and never double-log.
   readonly log: DaemonLogger;
+  // [LAW:single-enforcer] The one clock the projection math reads "now" from —
+  // the same seam threaded to the template engine's `minutesUntilReset`, so
+  // an ETA and the reset countdown beside it agree on the instant. Omitted ⇒
+  // wall clock; tests inject a frozen clock for determinism.
+  readonly clock?: () => Date;
+}
+
+// ─── Rate-limit projection (pure) ──────────────────────────────────────────────
+//
+// [LAW:effects-at-boundaries] The math is pure — utilization, reset instant,
+// window length and `now` in; minutes-to-cap out. The only effect (reading the
+// clock) stays in buildRenderPayload; these stay testable in isolation.
+
+// Window lengths are facts of Claude's rate-limit cadence, not config: the
+// five-hour block and the seven-day window.
+const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+// Below this much elapsed in a window, a linear projection from one early data
+// point is noise — surface no ETA rather than a confidently-wrong number.
+const MIN_PROJECTABLE_ELAPSED_MS = 5 * 60 * 1000;
+// The same floor for the spend rate: under a minute of session wall-clock,
+// $/hr is dominated by a single turn rather than a sustained burn.
+const MIN_BURN_SECONDS = 60;
+
+/**
+ * Linearly extrapolate a rate-limit window's utilization to its 100% cap.
+ * The window started `windowMs` before `resetsAtSec`; elapsed time and the
+ * used-% give a rate, and the remaining headroom divided by that rate is the
+ * minutes-to-cap. Returns undefined when the window is too young to project
+ * or shows no usage yet — the caller drops the field and the segment renders
+ * "—" rather than a fabricated ETA. [LAW:no-silent-failure]
+ */
+export function projectEtaMinutes(
+  usedPercentage: number,
+  resetsAtSec: number,
+  windowMs: number,
+  nowMs: number,
+): number | undefined {
+  const elapsedMs = windowMs - (resetsAtSec * 1000 - nowMs);
+  if (elapsedMs < MIN_PROJECTABLE_ELAPSED_MS || usedPercentage <= 0)
+    return undefined;
+  const pctPerMs = usedPercentage / elapsedMs;
+  const etaMs = (100 - usedPercentage) / pctPerMs;
+  return Math.max(0, Math.round(etaMs / 60000));
+}
+
+/**
+ * Session spend rate in dollars per hour: cost over wall-clock duration.
+ * Returns undefined under a wall-clock floor where the rate is a single-turn
+ * artifact, not a sustained burn. A real $0 over enough time is a true 0/hr,
+ * not absence. [LAW:no-silent-failure]
+ */
+export function projectCostPerHour(
+  cost: number,
+  durationSeconds: number,
+): number | undefined {
+  if (durationSeconds < MIN_BURN_SECONDS) return undefined;
+  return (cost * 3600) / durationSeconds;
 }
 
 // ─── Builder ─────────────────────────────────────────────────────────────────
@@ -376,8 +452,13 @@ export async function buildRenderPayload(
           hookData.workspace?.project_dir,
         ),
       ),
-      lane("session", wants("session.cost") || wants("session.tokens"), () =>
-        deps.usageStore.getUsageInfo(hookData.session_id, hookData),
+      // [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),
@@ -385,7 +466,7 @@ export async function buildRenderPayload(
       lane("context", wants("context"), () =>
         deps.contextProvider.getContextInfo(hookData),
       ),
-      lane("metrics", wants("metrics"), () =>
+      lane("metrics", wants("metrics") || wants("burn"), () =>
         deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
       ),
       lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
@@ -423,6 +504,34 @@ export async function buildRenderPayload(
   // `minutesUntilReset(resets_at)`, which the DSL template composes via
   // 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,
+        fiveHour.resets_at,
+        FIVE_HOUR_MS,
+        nowMs,
+      )
+    : undefined;
+  const weeklyEta = sevenDay
+    ? projectEtaMinutes(
+        sevenDay.used_percentage,
+        sevenDay.resets_at,
+        SEVEN_DAY_MS,
+        nowMs,
+      )
+    : undefined;
+  // [LAW:dataflow-not-control-flow] Gated by `wants("burn")` so the rate is
+  // computed only when a layout segment reads it; absent cost/duration (lane
+  // skipped or provider empty) yields no rate, never a fabricated one.
+  const burnCost = usageValue?.session.cost;
+  const burnDuration = metricsValue?.sessionDuration;
+  const costPerHour =
+    wants("burn") && burnCost != null && burnDuration != null
+      ? projectCostPerHour(burnCost, burnDuration)
+      : 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
@@ -487,6 +596,7 @@ export async function buildRenderPayload(
     ...(theme !== undefined && { theme }),
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
+    ...(costPerHour !== undefined && { burn: { costPerHour } }),
     ...(wants("block") &&
       fiveHour !== undefined && {
         block: {
@@ -496,12 +606,14 @@ export async function buildRenderPayload(
           // projection rule, two segments.
           nativeUtilization: fiveHour.used_percentage,
           resetsAt: fiveHour.resets_at,
+          ...(blockEta !== undefined && { etaMinutes: blockEta }),
         },
       }),
-    ...(hookData.rate_limits?.seven_day !== undefined && {
+    ...(sevenDay !== undefined && {
       weekly: {
-        percentage: hookData.rate_limits.seven_day.used_percentage,
-        resetsAt: hookData.rate_limits.seven_day.resets_at,
+        percentage: sevenDay.used_percentage,
+        resetsAt: sevenDay.resets_at,
+        ...(weeklyEta !== undefined && { etaMinutes: weeklyEta }),
       },
     }),
     ...(cacheValue !== undefined && {

package/src/daemon/server.ts

@@ -1076,6 +1076,9 @@ const payloadDeps = {
   // [LAW:single-enforcer] buildRenderPayload is the one log site for the
   // outcome-carrying provider lanes (git, cache).
   log: dlog,
+  // [LAW:single-enforcer] The daemon's wall clock — the same instant source
+  // the rate-limit ETA projection and the template's reset countdown read.
+  clock: () => new Date(),
 };
 
 function handleClick(verb: string, value: string): Response {