@promptctl/cc-candybar 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.4.0",
+  "version": "1.6.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.6.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.6.0",
+    "@promptctl/cc-candybar-linux-x64": "1.6.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.6.0"
   },
   "pnpm": {
     "supportedArchitectures": {

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

@@ -280,6 +280,21 @@ export const DEFAULT_DSL_CONFIG = {
       default: 0,
     },
 
+    // Forge PR/MR — the daemon's git provider resolves the branch's open PR via
+    // gh/glab and projects it here. Declaring any of these turns on the network
+    // lookup. [LAW:no-silent-failure] prError is non-empty ONLY when the forge
+    // was asked but couldn't answer (auth/network) — distinct from "no PR"
+    // (every field empty). prNumber 0 (default) ⇒ no open PR.
+    "git.prNumber": {
+      kind: "input",
+      path: "git.prNumber",
+      type: "number",
+      default: 0,
+    },
+    "git.prState": { kind: "input", path: "git.prState", default: "" },
+    "git.prUrl": { kind: "input", path: "git.prUrl", default: "" },
+    "git.prError": { kind: "input", path: "git.prError", default: "" },
+
     // Prompt-cache expiry — epoch seconds, projected by the cache provider.
     // Same unit/shape as block/weekly resetsAt so the cacheTimer segment
     // composes `minutesUntilReset` identically. 0 (default) ⇒ no cache
@@ -386,6 +401,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",
@@ -517,6 +557,24 @@ export const DEFAULT_DSL_CONFIG = {
       fg: "foreground",
       when: '{{ ne .git.branch "" }}',
     },
+    // Git PR/MR — the branch's open pull/merge request as a clickable link.
+    // OPT-IN: declared but NOT in the default root (it adds a network gh/glab
+    // call). Add "gitPr" to a container's children to enable it. The `{{ link
+    // url text }}` emits ONE OSC-8 region carrying the https PR url, so the
+    // CLICK is handled by the terminal/OS (opens the browser) — no daemon verb.
+    // [LAW:no-silent-failure] Three render states from the data: an open PR
+    // (prUrl set) renders the link; a lookup FAILURE (prError set, prUrl empty)
+    // renders a distinct ⚠ marker so an outage is not mistaken for "no PR";
+    // no PR (both empty) leaves the `when` gate false and the segment absent.
+    gitPr: {
+      template:
+        '{{ if ne .git.prUrl "" }}' +
+        '{{ link .git.prUrl (printf " ⇆ #%v " .git.prNumber) }}' +
+        "{{ else }} ⚠ PR {{ end }}",
+      bg: "surface-active",
+      fg: "foreground",
+      when: '{{ or (ne .git.prUrl "") (ne .git.prError "") }}',
+    },
     // Quick-action tray — copy the session id / cwd, open the project dir /
     // transcript in the editor. [LAW:locality-or-seam] The glyph is the
     // REPRESENTATION; the named action (below) is the BEHAVIOR; the action
@@ -581,6 +639,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 +834,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/git.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { GitService, type GitInfo } from "../../segments/git";
-import { ok, type Outcome } from "../../utils/outcome";
+import { GitService, type GitInfo, type PullRequest } from "../../segments/git";
+import { ABSENT, ok, type Outcome } from "../../utils/outcome";
 import { debug } from "../../utils/logger";
 import { WatcherRegistry, type WatcherHandle } from "./watchers";
 
@@ -44,6 +44,17 @@ const DEFAULT_TTL_MS = 30_000;
 const DEFAULT_MAX_ENTRIES = 64;
 const SANITY_INTERVAL_MS = 5 * 60_000;
 
+// [LAW:decomposition] The forge PR lookup is a network resource with a
+// different lifecycle than local git state: it changes ~twice in a PR's life
+// and the fs watchers on .git/HEAD|index say nothing about remote PR state. So
+// it gets its OWN cache + TTL — independent of the 30s GitInfo TTL — so the
+// per-render git fetch stays all-local and the gh/glab spawn happens at most
+// once per window (or on branch switch, via the branch in the key). A `failed`
+// lookup caches for a SHORTER window so a transient forge outage is retried
+// soon, not pinned to the bar for the full ok-TTL.
+const PR_TTL_OK_MS = 5 * 60_000;
+const PR_TTL_FAIL_MS = 45_000;
+
 // Options applied to subscribe()'s internal getInfo() call. var-system's six
 // GitField values (branch, sha, dirty, ahead, behind, stash) all project from
 // these flags — keep them in lockstep with the projection in
@@ -60,6 +71,11 @@ interface MtimeSnapshot {
   index: number;
 }
 
+interface PrCacheEntry {
+  pr: Outcome<PullRequest>;
+  computedAt: number;
+}
+
 interface GitCacheEntry {
   info: GitInfo;
   computedAt: number;
@@ -147,6 +163,16 @@ export class GitDataProvider extends GitService {
   // here; subsequent concurrent callers await the same promise and resolve in
   // lockstep.
   private readonly fetchInFlight = new Map<string, Promise<Outcome<GitInfo>>>();
+  // [LAW:one-source-of-truth] The forge PR cache, keyed by `repoRoot|branch`
+  // (a branch switch is a new key, so its PR is fetched fresh; the old branch's
+  // entry ages out). Separate from `entries` because it carries its own TTL.
+  private readonly prCache = new Map<string, PrCacheEntry>();
+  // [LAW:single-enforcer] Coalesce concurrent PR misses on the same key — same
+  // role as fetchInFlight for the GitInfo path, but for the network forge call.
+  private readonly prFetchInFlight = new Map<
+    string,
+    Promise<Outcome<PullRequest>>
+  >();
   // [LAW:single-enforcer] Coalesce overlapping refreshes for the same repo.
   // `refreshing` holds the repoRoots whose refresh loop is currently
   // executing; `refreshAgain` is the trailing-edge flag: if a new
@@ -292,6 +318,15 @@ export class GitDataProvider extends GitService {
     if (outcome.kind !== "ok") return outcome;
     const info = outcome.value;
 
+    // [LAW:decomposition] The inner GitService never resolves the PR — the
+    // cache layer owns that lookup so it can give it an independent TTL. On the
+    // 30s GitInfo refetch the prCache is almost always warm, so attaching the
+    // PR here is a memory read; the gh/glab spawn only fires when the prCache
+    // entry has aged past its (outcome-dependent) TTL or the branch changed.
+    if (options.showPullRequest) {
+      info.pullRequest = await this.getPullRequestCached(repoRoot, info.branch);
+    }
+
     // Drop any prior entry for this exact key before re-inserting (so we
     // release its watcher refcount cleanly).
     this.dropEntry(key);
@@ -315,6 +350,63 @@ export class GitDataProvider extends GitService {
     return outcome;
   }
 
+  // [LAW:single-enforcer] The one read path for a branch's PR. Reads the remote
+  // (cheap local git) so the cache key reflects every input the PR value
+  // depends on — `repoRoot|branch|remote` — and a re-pointed origin is a fresh
+  // key, not a stale hit ([LAW:one-source-of-truth]). TTL is outcome-dependent
+  // (a `failed` retries sooner). Concurrent misses coalesce through
+  // prFetchInFlight. The forge dispatch delegates to inner.resolvePullRequest —
+  // this layer is cache + lifecycle only, never forge knowledge.
+  private async getPullRequestCached(
+    repoRoot: string,
+    branch: string,
+  ): Promise<Outcome<PullRequest>> {
+    // [LAW:no-silent-failure] A `failed` remote read (git couldn't run) must
+    // surface; only `absent` (no remote configured) means "no forge PR".
+    const remote = await this.inner.getRemoteOriginUrl(repoRoot);
+    if (remote.kind === "failed") return remote;
+    if (remote.kind === "absent") return ABSENT;
+    const remoteUrl = remote.value;
+
+    const key = `${repoRoot}|${branch}|${remoteUrl}`;
+    const now = Date.now();
+
+    const existing = this.prCache.get(key);
+    if (existing) {
+      const ttl = existing.pr.kind === "failed" ? PR_TTL_FAIL_MS : PR_TTL_OK_MS;
+      if (now - existing.computedAt < ttl) {
+        // LRU touch so the active branch's PR survives eviction.
+        this.prCache.delete(key);
+        this.prCache.set(key, existing);
+        return existing.pr;
+      }
+    }
+
+    const pending = this.prFetchInFlight.get(key);
+    if (pending) return pending;
+
+    const promise = this.inner
+      .resolvePullRequest(repoRoot, remoteUrl)
+      .then((pr) => {
+        this.prCache.set(key, { pr, computedAt: Date.now() });
+        this.evictPrIfNeeded();
+        return pr;
+      })
+      .finally(() => {
+        this.prFetchInFlight.delete(key);
+      });
+    this.prFetchInFlight.set(key, promise);
+    return promise;
+  }
+
+  private evictPrIfNeeded(): void {
+    while (this.prCache.size > this.maxEntries) {
+      const oldest = this.prCache.keys().next().value;
+      if (oldest === undefined) break;
+      this.prCache.delete(oldest);
+    }
+  }
+
   // [LAW:effects-at-boundaries] The subscribe surface's edge: fold the typed
   // outcome into the GitInfo|null the var-system callback contract expects.
   // `failed` is logged HERE — the one log site for this consumption path
@@ -548,6 +640,10 @@ export class GitDataProvider extends GitService {
     this.refreshing.clear();
     this.refreshAgain.clear();
     this.fetchInFlight.clear();
+    // In-flight PR fetches resolve naturally; clearing the maps means the next
+    // caller starts fresh (the prCache is rebuilt cold like every other cache).
+    this.prCache.clear();
+    this.prFetchInFlight.clear();
     if (this.ownsWatchers) this.watchers.closeAll();
   }
 }

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();
   }
 }