@giladbarnea/pi-custom-footer 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +6 -2
  2. package/index.ts +292 -14
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- last_updated: 2026-11-11T15-30
2
+ last_updated: 2026-11-12T09-30
3
3
  ---
4
4
 
5
5
  <div align="center">
@@ -31,9 +31,11 @@ Below the editor, see:
31
31
  - **Context remaining at a glance:** a color-graded gauge and used/window tokens.
32
32
  - **Cost across the conversation:** cumulative cost and average cost per assistant turn.
33
33
  - **Cache behavior:** session hit rate, latest hit or miss, and reused/new token totals. Like Pi’s own notice, a miss shows what it cost and why it happened: an idle gap or a model switch.
34
+ - **How long the cache stays warm:** `warm for 26m`, live: the footer redraws once a minute. It counts down to the latest of three times: the last request or cache warm plus the model’s cache lifetime; the end of Pi’s own idle warming, when Pi will refresh this context; and a deadline set with pi-keep-cache-warm in this Pi session. Once that time has passed, the fact hides. Pi’s idle warming counts on Pi 1.5.1 and later; earlier versions show last touch plus lifetime. Models without a declared cache lifetime, such as OpenAI and Codex, show nothing.
34
35
  - **Where you are:** Git branch, dirty marker, directory, and other extensions’ status messages.
36
+ - **Subscription pace:** this week’s burn rate against the target rate, as `burn ━━━━●┊─── 1.07× ≤ target 1.18× · resets in 12h`. The sign turns to `>` when you are over budget, and the dot passes the time marker. A reading more than 30 minutes old adds its age, such as `· 2h old`. The age outlasts the pace bar and goes before the rest of the pace. Optional: shown only when a `quota` cache file exists.
35
37
 
36
- The layout follows your Pi theme. The header and the footer each take the fewest lines they can. To fit, they first drop labels, round readings, remove whitespace, and drop the branch icon. Only then does the footer hide facts: the reused/new split, the session hit rate, the token counts, and last the cost per turn. A cache miss drops its re-billed tokens early. It keeps its cause until every one of those facts has hidden, and keeps its cost to the end.
38
+ The layout follows your Pi theme. The header and the footer each take the fewest lines they can. To fit, they first drop the pace bar and labels, round readings, remove whitespace, and drop the branch icon. The cache time drops its label (`26m`). Only then does the footer hide facts: a stale reading's age, the burn rate with its reset time, the reused/new split, the session hit rate, the token counts, the word `target`, the cache time, and last the cost per turn. The target rate stays down to `≤ 1.18×`. A cache miss drops its re-billed tokens early. It keeps its cause until every one of those facts has hidden, and keeps its cost to the end. Last, the target rate hides only where it alone would add a line.
37
39
 
38
40
  Skills get one row for every eight terminal rows past the first six, with a minimum of one. A 21-row phone screen gets one row, a 27-row screen two, and a 34-row screen three. To fit, the row first drops token ages, then separators, then shortens long names in the middle (`caut…ctor`). Only then does it hide skills from the end, behind a `+N` count at the end of the last row.
39
41
 
@@ -41,6 +43,8 @@ Skills get one row for every eight terminal rows past the first six, with a mini
41
43
 
42
44
  Skill age measures context-token growth since the first response after a skill load. Cache misses mirror Pi’s own miss accounting: the tokens re-billed since the last request or cache warm, their extra cost over cache reads, and the idle time. Costs use the model’s reported pricing, including when you use a subscription.
43
45
 
46
+ The pace comes from `~/.cache/quota/provider-usage.json` (or under `XDG_CACHE_HOME`), which the author’s `quota` tool writes. That tool is not public yet, and without the file the footer shows no pace. The reading is for the pool of the session’s model: Claude, Fable or Codex. The footer only reads that file. It never runs `quota` and never fetches. Burn and target each take a color from `quota`’s heat map: green near 1.0×, cool where allowance goes unused, amber then red where it runs out early. A Fable session shows Fable’s target capped by the room left in the shared Claude week.
47
+
44
48
  ## Development
45
49
 
46
50
  ```sh
package/index.ts CHANGED
@@ -33,8 +33,13 @@
33
33
  * scan includes them.
34
34
  * - The footer scans the current branch. Pi scans every session entry.
35
35
  */
36
- import type { AssistantMessage } from "@earendil-works/pi-ai";
37
- import type { ExtensionAPI, ExtensionContext, SessionEntry, Theme } from "@earendil-works/pi-coding-agent";
36
+ import { readFileSync } from "node:fs";
37
+ import { homedir } from "node:os";
38
+ import { join } from "node:path";
39
+
40
+ import * as piAi from "@earendil-works/pi-ai";
41
+ import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
42
+ import { SettingsManager, type ExtensionAPI, type ExtensionContext, type SessionEntry, type Theme } from "@earendil-works/pi-coding-agent";
38
43
  import { truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
39
44
 
40
45
  import {
@@ -65,6 +70,15 @@ const CACHE_TTL_MS = 5 * 60 * 1000;
65
70
  // hole in any background the caller has already opened, such as the cwd pill.
66
71
  const ANSI_FG_RESET = "\x1b[39m";
67
72
  const QUIET_BLEND = 0.38;
73
+ const PACE_BAR_CELLS = 9;
74
+ const MINUTE_MS = 60_000;
75
+ // pi-keep-cache-warm's session entries and tool, read only while that extension is loaded.
76
+ const KEEP_CACHE_WARM_ENTRY = "keep-cache-warm";
77
+ const KEEP_CACHE_WARM_TOOL = "keep_cache_warm";
78
+ // The quota tool refreshes its cache every 5 minutes while in use. A reading older than half an hour has gone stale.
79
+ const PACE_STALE_AFTER_MS = 30 * 60 * 1000;
80
+ // The quota tool's own rule (FABLE_SHARE_OF_WEEKLY in its pick.py): Fable use counts at half weight against the shared Claude week.
81
+ const FABLE_SHARE_OF_WEEKLY = 0.5;
68
82
 
69
83
  // ── Colour rules ────────────────────────────────────────────────────────────
70
84
  // Hue means one of two things here and nothing else.
@@ -72,7 +86,9 @@ const QUIET_BLEND = 0.38;
72
86
  // 1. A RAMP is a measurement. Its colour moves with the value, and it is loud
73
87
  // only where there is something to act on. CONTEXT_STOPS runs quiet to loud
74
88
  // as the window fills. CACHE_STOPS is that same scale mirrored, because a
75
- // full cache is the good end and an empty one is the problem.
89
+ // full cache is the good end and an empty one is the problem. PACE_STOPS is
90
+ // the quota tool's heat map: green at the ideal 1.0×, cool where allowance
91
+ // goes unused, amber then red where it runs out early.
76
92
  // 2. A FAMILY is a category. One token per kind of fact, held everywhere it
77
93
  // appears, so the shape of the footer becomes learnable:
78
94
  // accent place cwd, branch, dirty marker
@@ -95,6 +111,14 @@ const CONTEXT_STOPS: readonly Stop[] = [
95
111
  /** The context ramp mirrored, so a full cache is quiet and an empty one is loud. */
96
112
  const CACHE_STOPS: readonly Stop[] = CONTEXT_STOPS.map((stop) => ({ ...stop, at: 100 - stop.at })).reverse();
97
113
 
114
+ /** The quota tool's pace heat map (DashboardPalette.pace) on theme tokens, over pacePosition's scale. `mdLink` is the theme's cool blue. */
115
+ const PACE_STOPS: readonly Stop[] = [
116
+ { at: -1, token: "mdLink" },
117
+ { at: 0, token: "success" },
118
+ { at: 0.5, token: "warning" },
119
+ { at: 1, token: "error" },
120
+ ];
121
+
98
122
  const PLACE_TOKEN = "accent";
99
123
  const SPEND_TOKEN = "warning";
100
124
  const MACHINE_TOKEN = "syntaxKeyword";
@@ -117,9 +141,9 @@ const THINKING_LEVELS: Record<string, { full: string; short: string; token: stri
117
141
  // up a kind of detail that matters more than the phase before it, and within a
118
142
  // phase the least needed fact goes first.
119
143
 
120
- type Form = "full" | "short" | "bare" | "hidden";
144
+ type Form = "full" | "short" | "brief" | "bare" | "least" | "hidden";
121
145
  /** A fact's text in each form it has. A step names only forms its fact has. */
122
- type FactForms = { full: string } & Partial<Record<"short" | "bare", string>>;
146
+ type FactForms = { full: string } & Partial<Record<"short" | "brief" | "bare" | "least", string>>;
123
147
  /** One row of facts. Each inner list is one group, joined by the narrow joiner. */
124
148
  type Row<Key extends string> = readonly (readonly Key[])[];
125
149
  type Ladder<Key extends string> = {
@@ -127,7 +151,7 @@ type Ladder<Key extends string> = {
127
151
  steps: readonly (readonly [Key | "spacing", Form])[];
128
152
  };
129
153
  type HeaderFact = "model" | "thinking" | "sessionName" | "sessionId";
130
- type FooterFact = "branch" | "cwd" | "context" | "tokens" | "cost" | "perTurn" | "cacheSession" | "latest" | "reuse";
154
+ type FooterFact = "branch" | "cwd" | "context" | "tokens" | "cost" | "perTurn" | "cacheSession" | "latest" | "expiry" | "reuse" | "pace";
131
155
 
132
156
  const SPACING = {
133
157
  full: { separator: WIDE_SEPARATOR, joiner: " " },
@@ -151,24 +175,41 @@ const FOOTER_LADDER: Ladder<FooterFact> = {
151
175
  rows: [
152
176
  [["branch"], ["cwd"]],
153
177
  [["context", "tokens"], ["cost", "perTurn"]],
154
- [["cacheSession"], ["latest"], ["reuse"]],
178
+ [["cacheSession"], ["latest"], ["expiry"], ["reuse"]],
179
+ [["pace"]],
155
180
  ],
156
181
  steps: [
157
- // 1. Drop the labels the values already imply.
158
- ["tokens", "short"], ["context", "bare"], ["cacheSession", "bare"],
182
+ // 1. Drop what the values already imply. First the pace bar and the words
183
+ // "resets in": the bar draws what the two rates say. Then the labels.
184
+ ["pace", "short"],
185
+ ["tokens", "short"], ["context", "bare"], ["cacheSession", "bare"], ["expiry", "short"],
159
186
  // 2. Shorten the readings: the latest cache figure, then the cost, rounded twice.
160
187
  ["latest", "short"], ["cost", "short"], ["cost", "bare"],
161
188
  // 3. Remove whitespace: the padding inside the cwd pill, then the separators.
162
189
  ["cwd", "short"], ["spacing", "bare"],
163
190
  // 4. Drop the branch icon.
164
191
  ["branch", "bare"],
165
- // 5. Hide whole facts. The cost per turn goes last of them, because
166
- // seeing what each turn costs is half of what the footer is for.
167
- ["reuse", "hidden"], ["cacheSession", "hidden"], ["tokens", "hidden"], ["perTurn", "hidden"],
192
+ // 5. Hide whole facts. First a stale quota reading's age: it outlasts the
193
+ // bar, the labels and the whitespace, so a laptop still sees that the
194
+ // rates are old, and it goes before every other part of the pace left.
195
+ // Then the burn rate and the reset time: the sign keeps the verdict,
196
+ // and the target is the number to act on. The word
197
+ // "target" outlasts the cache and token facts, because it names that
198
+ // number once the burn rate is gone. The time left on the cache
199
+ // outlasts it: it says whether to hurry back before a cold restart.
200
+ // The cost per turn goes last of them, because seeing what each turn
201
+ // costs is half of what the footer is for. The target rate hides only
202
+ // at the very end, in step 7.
203
+ ["pace", "brief"], ["pace", "bare"],
204
+ ["reuse", "hidden"], ["cacheSession", "hidden"], ["tokens", "hidden"], ["pace", "least"], ["expiry", "hidden"], ["perTurn", "hidden"],
168
205
  // 6. Drop the cause of a cache miss, keeping its cost. It outranks every
169
206
  // hidden fact: it shows only on the turn that missed, and says what to
170
207
  // do about the cost (an idle gap or a model switch).
171
208
  ["latest", "bare"],
209
+ // 7. Last, hide the target rate. Because the footer takes the fullest
210
+ // state with the fewest lines, this fires only where the target alone
211
+ // would add a line, as on a phone with the keyboard up.
212
+ ["pace", "hidden"],
172
213
  ],
173
214
  };
174
215
 
@@ -528,7 +569,7 @@ function detectCacheMiss(previous: PreviousRequest | undefined, message: Assista
528
569
  * cacheMissForms({ missedTokens: 199_000, missedCost: 0.38, idleMs: 360_000, modelChanged: false })
529
570
  * // { full: "latest miss after 6m idle: 199k re-billed $0.38", short: "miss 6m idle $0.38", bare: "miss $0.38" }
530
571
  */
531
- function cacheMissForms(miss: CacheMiss): Required<FactForms> {
572
+ function cacheMissForms(miss: CacheMiss): Record<"full" | "short" | "bare", string> {
532
573
  // Pi's notice shows a cost from one cent, rounded to cents, and an idle gap from the TTL, in whole minutes.
533
574
  const cost = miss.missedCost >= 0.01 ? `$${miss.missedCost.toFixed(2)}` : null;
534
575
  const cause = miss.modelChanged ? "model switch" : miss.idleMs >= CACHE_TTL_MS ? `${Math.round(miss.idleMs / 60_000)}m idle` : null;
@@ -541,6 +582,198 @@ function cacheMissForms(miss: CacheMiss): Required<FactForms> {
541
582
  };
542
583
  }
543
584
 
585
+ // ── Quota pace ──────────────────────────────────────────────────────────────
586
+ // Read from the cache file the author's `quota` tool writes. The footer never
587
+ // runs the tool and never fetches: it shows the last reading any quota run
588
+ // left there, and adds the reading's age once it is stale. It reads the file
589
+ // once per snapshot, not per redraw.
590
+
591
+ type QuotaPool = "CLAUDE" | "FABLE" | "CODEX";
592
+ type WeeklyWindow = { used_pct: number; window_start: string; window_duration_seconds: number };
593
+ type QuotaCache = Record<string, { written_at?: string; usages?: { name: string; weekly: WeeklyWindow }[] }>;
594
+ /** One weekly limit's pace. `used` and `elapsed` are shares of the window, 0 to 1. `ageMs` is how old the reading is. */
595
+ type Pace = { burn: number; target: number; used: number; elapsed: number; resetsInMs: number; ageMs: number };
596
+
597
+ function quotaCacheFile(): string {
598
+ return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "quota", "provider-usage.json");
599
+ }
600
+
601
+ /** The weekly pool a model spends from.
602
+ * @example
603
+ * quotaPool({ provider: "anthropic", id: "claude-fable-5-2" }) // "FABLE"
604
+ */
605
+ function quotaPool(model: ExtensionContext["model"]): QuotaPool | null {
606
+ if (model?.provider === "openai-codex") return "CODEX";
607
+ if (model?.provider !== "anthropic") return null;
608
+ return model.id.includes("fable") ? "FABLE" : "CLAUDE";
609
+ }
610
+
611
+ /** Burn and target rate of one weekly window, as the quota tool computes them. Null outside the window.
612
+ * @example
613
+ * windowPace({ used_pct: 15, window_start: "2026-01-01T00:00:00Z", window_duration_seconds: 1000 }, Date.parse("2026-01-01T00:01:40Z"))
614
+ * // { burn: 1.5, target: 0.944…, used: 0.15, elapsed: 0.1, resetsInMs: 900_000 }
615
+ * The age is the caller's: it comes from the provider entry, not the window.
616
+ */
617
+ function windowPace(weekly: WeeklyWindow, now: number): Omit<Pace, "ageMs"> | null {
618
+ const durationMs = weekly.window_duration_seconds * 1000;
619
+ const elapsedMs = now - Date.parse(weekly.window_start);
620
+ if (elapsedMs <= 0 || elapsedMs >= durationMs) return null;
621
+ const used = weekly.used_pct / 100;
622
+ const elapsed = elapsedMs / durationMs;
623
+ return { burn: used / elapsed, target: Math.max(0, 1 - used) / (1 - elapsed), used, elapsed, resetsInMs: durationMs - elapsedMs };
624
+ }
625
+
626
+ /** The pace of the model's pool, from the quota cache. Fable's target is the quota tool's pick score:
627
+ * its own target rate, capped by the room left in the shared Claude week. The age is that of the
628
+ * provider entry holding the pool, which Claude and Fable share.
629
+ */
630
+ function readPace(model: ExtensionContext["model"], now: number): Pace | null {
631
+ const pool = quotaPool(model);
632
+ if (!pool) return null;
633
+ // The file belongs to another tool. A missing file, another shape or a missing pool all mean no reading.
634
+ try {
635
+ const cache: QuotaCache = JSON.parse(readFileSync(quotaCacheFile(), "utf8"));
636
+ const providerOf = (name: QuotaPool) => Object.values(cache).find((provider) => provider.usages?.some((usage) => usage.name === name))!;
637
+ const paceOf = (name: QuotaPool): Omit<Pace, "ageMs"> | null => windowPace(providerOf(name).usages!.find((usage) => usage.name === name)!.weekly, now);
638
+ const ageMs = Math.max(0, now - Date.parse(providerOf(pool).written_at!));
639
+ const pace = paceOf(pool);
640
+ if (!pace || Number.isNaN(ageMs)) return null;
641
+ if (pool !== "FABLE") return { ...pace, ageMs };
642
+ const claude = paceOf("CLAUDE");
643
+ return claude && { ...pace, target: Math.min(pace.target, claude.target / FABLE_SHARE_OF_WEEKLY), ageMs };
644
+ } catch {
645
+ return null;
646
+ }
647
+ }
648
+
649
+ /** Where a rate sits on PACE_STOPS, by its distance from the ideal 1.0×. Mirrors the quota tool's
650
+ * DashboardPalette.pace: a burn rate heats above 1.0× (amber at 1.25×, red at 2×) and cools below it;
651
+ * a target rate runs the other way. Both are ideal within 5% of 1.0×.
652
+ * @example
653
+ * [pacePosition(1, false), pacePosition(1.25, false), pacePosition(2, false), pacePosition(0.25, false)] // [0, 0.5, 1, -1]
654
+ * [pacePosition(0.8, true), pacePosition(4, true)] // [0.5, -1]
655
+ */
656
+ function pacePosition(rate: number, isTarget: boolean): number {
657
+ const pressure = (isTarget ? -1 : 1) * Math.log2(rate);
658
+ const idealBand = Math.log2(1.05);
659
+ const amberPoint = Math.log2(1.25);
660
+ if (pressure < -idealBand) return -Math.min(1, (-pressure - idealBand) / (2 - idealBand));
661
+ if (pressure <= idealBand) return 0;
662
+ if (pressure <= amberPoint) return 0.5 * (pressure - idealBand) / (amberPoint - idealBand);
663
+ return 0.5 + 0.5 * Math.min(1, (pressure - amberPoint) / (1 - amberPoint));
664
+ }
665
+
666
+ /** The used share (●) against the elapsed share (┊) of the window. The dot passes the marker when use is ahead of time.
667
+ * @example
668
+ * paceBar(0.55, 0.6, String, String) // "━━━━●┊───"
669
+ * paceBar(0.9, 0.85, String, String) // "━━━━━━┊●─"
670
+ */
671
+ function paceBar(used: number, elapsed: number, heat: (text: string) => string, quiet: (text: string) => string): string {
672
+ const first = Math.round(Math.min(used, elapsed) * (PACE_BAR_CELLS - 2));
673
+ const second = Math.max(first + 1, Math.round(Math.min(1, Math.max(used, elapsed)) * (PACE_BAR_CELLS - 1)));
674
+ const between = second - first - 1;
675
+ const after = "─".repeat(PACE_BAR_CELLS - 1 - second);
676
+ return used > elapsed
677
+ ? `${heat("━".repeat(first))}${quiet("┊")}${heat(`${"━".repeat(between)}●`)}${quiet(after)}`
678
+ : `${heat(`${"━".repeat(first)}●`)}${quiet(`${"─".repeat(between)}┊${after}`)}`;
679
+ }
680
+
681
+ /** A duration in the quota tool's own format: time left, or a reading's age.
682
+ * @example
683
+ * [formatRemaining(45_000_000), formatRemaining(110_000_000), formatRemaining(1_800_000)] // ["12h", "1d 6h", "30m"]
684
+ */
685
+ function formatRemaining(milliseconds: number): string {
686
+ const hours = Math.floor(milliseconds / 3_600_000);
687
+ if (hours >= 24) return `${Math.floor(hours / 24)}d ${hours % 24}h`;
688
+ if (hours > 0) return `${hours}h`;
689
+ return `${Math.floor(milliseconds / 60_000)}m`;
690
+ }
691
+
692
+ // ── Cache expiry ────────────────────────────────────────────────────────────
693
+ // When the prompt cache is really gone: the latest of three times. The last
694
+ // touch plus the model's cache lifetime. Pi's own idle-warming horizon, when Pi
695
+ // will refresh this context. And an armed pi-keep-cache-warm deadline, when
696
+ // that extension runs in this Pi process. Pi's warming policy comes from pi-ai,
697
+ // which exports it since Pi 1.5.1. Without it, or without idle warming (the
698
+ // default since Pi 1.5.1), the time is last touch plus lifetime.
699
+
700
+ /** Pi's idle cache-warming policy, exported by pi-ai since Pi 1.5.1. */
701
+ type PiWarmingPolicy = {
702
+ evaluateCacheWarming(model: Model<Api>, promptTokens: number, phase: "idle"): { action: "warm" | "stop" };
703
+ getCacheWarmingDelayMs(ttlMs: number): number | undefined;
704
+ getPromptCacheTtlMs(model: Model<Api>): number | undefined;
705
+ CACHE_WARMING_MAX_IDLE_AGE_MS: number;
706
+ };
707
+ const piWarming = piAi as unknown as Partial<PiWarmingPolicy>;
708
+ /** Pi's own lifetime lookup where pi-ai exports it, else the same lookup on the model's `promptCache`. */
709
+ const promptCacheTtlMs = piWarming.getPromptCacheTtlMs ?? ((model: Model<Api>): number | undefined => {
710
+ const seconds = model.promptCache?.[process.env.PI_CACHE_RETENTION === "long" ? "long" : "short"];
711
+ return seconds === undefined ? undefined : seconds * 1000;
712
+ });
713
+
714
+ type KeepCacheWarmData = { kind: "arm"; deadline: string } | { kind: "warm"; provider: string; model: string } | { kind: "stop" };
715
+ type CacheExpiryInputs = {
716
+ model: Model<Api>;
717
+ /** Pi's effective `cacheWarming` mode. */
718
+ warmingMode: string;
719
+ /** When this process loaded pi-keep-cache-warm's tool; null when it is not loaded. Older entries are ignored. */
720
+ keepCacheWarmSince: number | null;
721
+ };
722
+
723
+ /** When the session's prompt cache is really gone, or null when Pi knows no cache lifetime for the model or nothing cached yet.
724
+ * A compaction or branch summary starts over: the next request misses anyway.
725
+ */
726
+ function cacheExpiresAt(branch: readonly SessionEntry[], { model, warmingMode, keepCacheWarmSince }: CacheExpiryInputs): number | null {
727
+ const lifetimeMs = promptCacheTtlMs(model);
728
+ if (lifetimeMs === undefined) return null;
729
+ const isCurrentModel = (provider: string, id: string) => provider === model.provider && id === model.id;
730
+ let lastTouch: number | undefined;
731
+ let lastRequest: { at: number; promptTokens: number } | undefined;
732
+ let keepWarmDeadline: number | undefined;
733
+ for (const entry of branch) {
734
+ if (entry.type === "compaction" || entry.type === "branch_summary") {
735
+ lastTouch = lastRequest = keepWarmDeadline = undefined;
736
+ } else if (entry.type === "message" && entry.message.role === "assistant") {
737
+ const message = entry.message as AssistantMessage;
738
+ if (message.stopReason === "error" || message.stopReason === "aborted") continue;
739
+ const { input, cacheRead, cacheWrite } = message.usage;
740
+ // Pi warms only the last request, and only for the selected model.
741
+ lastRequest = isCurrentModel(message.provider, message.model) ? { at: message.timestamp, promptTokens: input + cacheRead + cacheWrite } : undefined;
742
+ if (lastRequest) lastTouch = message.timestamp;
743
+ } else if (entry.type === "usage" && entry.kind === "cache_warm" && isCurrentModel(entry.provider, entry.model)) {
744
+ lastTouch = Date.parse(entry.timestamp);
745
+ } else if (entry.type === "custom" && entry.customType === KEEP_CACHE_WARM_ENTRY && keepCacheWarmSince !== null && Date.parse(entry.timestamp) >= keepCacheWarmSince) {
746
+ const data = entry.data as KeepCacheWarmData;
747
+ if (data.kind === "arm") keepWarmDeadline = Date.parse(data.deadline);
748
+ if (data.kind === "stop") keepWarmDeadline = undefined;
749
+ if (data.kind === "warm" && isCurrentModel(data.provider, data.model)) lastTouch = Date.parse(entry.timestamp);
750
+ }
751
+ }
752
+ if (lastTouch === undefined) return null;
753
+ return Math.max(lastTouch + lifetimeMs, keepWarmDeadline ?? 0, piIdleHorizon(model, warmingMode, lifetimeMs, lastRequest) ?? 0);
754
+ }
755
+
756
+ /** When Pi's own idle warming lets the cache go: the last refresh inside Pi's idle limit after the last request, plus the lifetime.
757
+ * Null when Pi will not refresh this context: no exported policy, a mode other than "idle", or Pi's cost rule says stop.
758
+ */
759
+ function piIdleHorizon(model: Model<Api>, warmingMode: string, lifetimeMs: number, lastRequest: { at: number; promptTokens: number } | undefined): number | null {
760
+ const { evaluateCacheWarming, getCacheWarmingDelayMs, CACHE_WARMING_MAX_IDLE_AGE_MS } = piWarming;
761
+ if (!lastRequest || warmingMode !== "idle" || !evaluateCacheWarming || !getCacheWarmingDelayMs || CACHE_WARMING_MAX_IDLE_AGE_MS === undefined) return null;
762
+ const delayMs = getCacheWarmingDelayMs(lifetimeMs);
763
+ if (delayMs === undefined || evaluateCacheWarming(model, lastRequest.promptTokens, "idle").action !== "warm") return null;
764
+ return lastRequest.at + Math.floor(CACHE_WARMING_MAX_IDLE_AGE_MS / delayMs) * delayMs + lifetimeMs;
765
+ }
766
+
767
+ /** Time left, in the shortest clear form, rounded up so a live cache never reads 0m.
768
+ * @example
769
+ * [formatTimeLeft(26 * 60_000), formatTimeLeft(30_000), formatTimeLeft(65 * 60_000), formatTimeLeft(120 * 60_000)] // ["26m", "1m", "1h5m", "2h"]
770
+ */
771
+ function formatTimeLeft(milliseconds: number): string {
772
+ const minutes = Math.ceil(milliseconds / MINUTE_MS);
773
+ if (minutes < 60) return `${minutes}m`;
774
+ return `${Math.floor(minutes / 60)}h${minutes % 60 ? `${minutes % 60}m` : ""}`;
775
+ }
776
+
544
777
  interface SessionStats {
545
778
  totalCost: number;
546
779
  totalReused: number;
@@ -655,11 +888,16 @@ interface FooterSnapshot {
655
888
  stats: SessionStats;
656
889
  context: ReturnType<typeof getContextPercent>;
657
890
  session: DisplaySession;
891
+ pace: Pace | null;
892
+ cacheExpiresAt: number | null;
658
893
  }
659
894
 
660
895
  // ── Extension entry point ───────────────────────────────────────────────────
661
896
 
662
897
  export default function (pi: ExtensionAPI) {
898
+ const loadedAt = Date.now();
899
+ // Redraws the footer once a minute, so the cache's time left stays live without session events.
900
+ let minuteTimer: ReturnType<typeof setInterval> | undefined;
663
901
  let currentCtx: any = null;
664
902
  let tuiRef: any = null;
665
903
  let gitBranch: string | null = null;
@@ -707,6 +945,14 @@ export default function (pi: ExtensionAPI) {
707
945
  manager, sessionId, leafId, model, stats,
708
946
  context: getContextPercent(currentCtx, stats.lastContextTokens, usage),
709
947
  session: getDisplaySession(currentCtx, currentCtx.cwd || ".", pi),
948
+ pace: readPace(model, Date.now()),
949
+ // Read Pi's settings and tools only for a model with a known cache lifetime.
950
+ cacheExpiresAt: model && promptCacheTtlMs(model) !== undefined ? cacheExpiresAt(branch, {
951
+ model,
952
+ // Pi's own default for the setting, which changed to "idle" in Pi 1.5.1.
953
+ warmingMode: SettingsManager.inMemory(pi.getSettings()).getCacheWarmingMode(),
954
+ keepCacheWarmSince: pi.getAllTools().some((tool) => tool.name === KEEP_CACHE_WARM_TOOL) ? loadedAt : null,
955
+ }) : null,
710
956
  };
711
957
  return snapshot;
712
958
  }
@@ -753,7 +999,7 @@ export default function (pi: ExtensionAPI) {
753
999
 
754
1000
  function renderBelow(width: number, theme: any): string[] {
755
1001
  if (!currentCtx) return [];
756
- const { stats, context: { pct, window, tokens } } = getSnapshot();
1002
+ const { stats, context: { pct, window, tokens }, pace, cacheExpiresAt: expiresAt } = getSnapshot();
757
1003
  const paint = makePainter(theme);
758
1004
  const label = (text: string) => theme.fg("dim", `${text} `);
759
1005
  const pill = (text: string) => theme.bg("selectedBg", paint.token(PLACE_TOKEN, theme.bold(text)));
@@ -777,6 +1023,24 @@ export default function (pi: ExtensionAPI) {
777
1023
  : theme.fg("dim", "no cache yet");
778
1024
  const latestHit = stats.latestCacheHitRate;
779
1025
  const missForms = stats.latestCacheMiss && cacheMissForms(stats.latestCacheMiss);
1026
+ const paceForms = (reading: Pace): FactForms => {
1027
+ const dim = (text: string) => theme.fg("dim", text);
1028
+ const burnHeat = (text: string) => paint.ramp(PACE_STOPS, pacePosition(reading.burn, false), text);
1029
+ const burn = burnHeat(`${reading.burn.toFixed(2)}×`);
1030
+ const target = paint.ramp(PACE_STOPS, pacePosition(reading.target, true), `${reading.target.toFixed(2)}×`);
1031
+ // The sign carries the verdict, and colour repeats it.
1032
+ const sign = reading.burn > reading.target ? theme.fg("error", ">") : dim("≤");
1033
+ const resets = formatRemaining(reading.resetsInMs);
1034
+ // A stale reading keeps showing, with its age until "brief", the form without it.
1035
+ const age = reading.ageMs > PACE_STALE_AFTER_MS ? dim(` · ${formatRemaining(reading.ageMs)} old`) : "";
1036
+ return {
1037
+ full: `${label("burn")}${paceBar(reading.used, reading.elapsed, burnHeat, dim)} ${burn} ${sign} ${label("target")}${target}${dim(` · resets in ${resets}`)}${age}`,
1038
+ short: `${label("burn")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}${age}`,
1039
+ brief: `${label("burn")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}`,
1040
+ bare: `${sign} ${label("target")}${target}`,
1041
+ least: `${sign} ${target}`,
1042
+ };
1043
+ };
780
1044
  const footerFacts: Partial<Record<FooterFact, FactForms>> = {
781
1045
  branch: gitBranch
782
1046
  ? { full: `${paint.token(PLACE_TOKEN, `${BRANCH_GLYPH} ${gitBranch}`)}${dirty}`, bare: `${paint.token(PLACE_TOKEN, gitBranch)}${dirty}` }
@@ -803,6 +1067,15 @@ export default function (pi: ExtensionAPI) {
803
1067
  full: paint.ramp(CACHE_STOPS, sessionHit ?? 0, formatTokens(stats.totalReused)) +
804
1068
  theme.fg("dim", ` reused / ${formatTokens(stats.totalFresh)} new`),
805
1069
  },
1070
+ // Once the time has passed the fact hides: there is nothing left to hurry back for,
1071
+ // and the next request's miss shows what it cost.
1072
+ expiry: expiresAt !== null && expiresAt > Date.now()
1073
+ ? {
1074
+ full: `${label("warm for")}${theme.fg("muted", formatTimeLeft(expiresAt - Date.now()))}`,
1075
+ short: theme.fg("muted", formatTimeLeft(expiresAt - Date.now())),
1076
+ }
1077
+ : undefined,
1078
+ pace: pace ? paceForms(pace) : undefined,
806
1079
  };
807
1080
  return fitFacts(footerFacts, FOOTER_LADDER, width, theme);
808
1081
  }
@@ -854,6 +1127,9 @@ export default function (pi: ExtensionAPI) {
854
1127
  snapshot = undefined;
855
1128
  skillsDirty = true;
856
1129
  thinkingLevel = pi.getThinkingLevel() ?? "off";
1130
+ clearInterval(minuteTimer);
1131
+ minuteTimer = setInterval(requestRender, MINUTE_MS);
1132
+ minuteTimer.unref();
857
1133
  await refreshGit();
858
1134
 
859
1135
  ctx.ui.setFooter((tui: any, theme: any, footerData: any) => {
@@ -885,6 +1161,8 @@ export default function (pi: ExtensionAPI) {
885
1161
  });
886
1162
 
887
1163
  pi.on("session_shutdown", async () => {
1164
+ clearInterval(minuteTimer);
1165
+ minuteTimer = undefined;
888
1166
  currentCtx = null;
889
1167
  tuiRef = null;
890
1168
  gitBranch = null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-custom-footer",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "Context, cache, cost, and loaded skills at a glance in Pi.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -28,7 +28,7 @@
28
28
  "LICENSE"
29
29
  ],
30
30
  "scripts": {
31
- "test": "node tests/skills.mjs && node tests/cache.mjs && node tests/layout.mjs && node tests/load.mjs && node tests/miss-parity.mjs && node --test tests/context.mjs",
31
+ "test": "node tests/skills.mjs && node tests/cache.mjs && node tests/layout.mjs && node tests/load.mjs && node tests/miss-parity.mjs && node tests/expiry.mjs && node --test tests/context.mjs",
32
32
  "check": "tsc --noEmit"
33
33
  },
34
34
  "engines": {