token-weather

1// Token Weather: a live forecast of the context window, above the prompt.
2//
3// turn.complete: after each main-loop turn, read the context window's fill
4// from $.session.usage() (the same figures the status line shows) and keep
5// the last HISTORY readings.
6// session.start: take a first reading, so the band shows before any turn.
7// ui.render (AbovePrompt): one line: icon, forecast word, percent, tokens
8// used of the window, and a block-character chart of the recent turns.
9//
10// The host reads on(...) and $.noun.method(...) from source, so they are
11// spelled literally, and helpers that take $ are top-level functions.
12
13const HISTORY = 12;
14const BARS = "▁▂▃▄▅▆▇█";
15
16// Forecast bands, by percent of the window used.
17const FORECAST = [
18// Single-width text symbols, not emoji: they line up in every terminal font.
19  { upTo: 25, icon: "☀", word: "Clear", color: "yellow" },
20  { upTo: 50, icon: "☁", word: "Cloudy", color: "cyan" },
21  { upTo: 75, icon: "☂", word: "Showers", color: "blue" },
22  { upTo: 90, icon: "☇", word: "Storm", color: "magenta" },
23  { upTo: Infinity, icon: "↯", word: "Compact soon", color: "red" },
24];
25
26// Readings: { tokens, window, percent }, oldest first.
27let readings = [];
28
29export function register(on) {
30  on("session.start", async ($, e, next) => {
31    const result = await next(e);
32    readings = [];
33    await takeReading($);
34    return result;
35  });
36
37  on("turn.complete", async ($, e, next) => {
38    const result = await next(e);
39    if (e.agentId) {
40      return result;
41    }
42    await takeReading($);
43    return result;
44  });
45
46  on("ui.render", { component: "AbovePrompt" }, ($, e, next) => {
47    if (e.hasSurvey || readings.length === 0) {
48      return next(e);
49    }
50    const { Box, Text } = $.ui.resolve(e);
51    return band(Box, Text, e.bodyColumns ?? 80);
52  });
53}
54
55async function takeReading($) {
56  try {
57    const { context } = await $.session.usage();
58    if (!context || !context.window) {
59      return;
60    }
61    const tokens = context.tokens ?? 0;
62    const percent = Math.round(context.percent ?? (tokens / context.window) * 100);
63    // The session.start reading is 0 before any response; drop it once real readings arrive.
64    readings = readings.filter((r) => r.tokens > 0);
65    readings.push({ tokens, window: context.window, percent });
66    if (readings.length > HISTORY) {
67      readings = readings.slice(-HISTORY);
68    }
69    $.ui.invalidate("ui.render");
70  } catch {
71    // No reading this turn; the band keeps the last one.
72  }
73}
74
75function band(Box, Text, columns) {
76  const now = readings[readings.length - 1];
77  const f = forecastFor(now.percent);
78  const trend = trendWord();
79  const parts = [
80    Text({ color: f.color, bold: true, children: `${f.icon}  ${f.word}` }),
81    Text({ children: `  ${now.percent}% of context` }),
82    Text({ dimColor: true, children: `  ${short(now.tokens)} / ${short(now.window)}` }),
83  ];
84  if (columns >= 60) {
85    parts.push(Text({ dimColor: true, children: "   last turns " }));
86    parts.push(Text({ color: f.color, children: chart() }));
87    if (trend) {
88      parts.push(Text({ dimColor: true, children: `  ${trend}` }));
89    }
90  }
91  return Box({ flexDirection: "row", paddingX: 1, children: parts });
92}
93
94function forecastFor(percent) {
95  return FORECAST.find((band) => percent < band.upTo) ?? FORECAST[FORECAST.length - 1];
96}
97
98// Bars scale to the busiest reading shown, so growth shows at any fill level.
99function chart() {
100  const top = Math.max(...readings.map((r) => r.tokens), 1);
101  const bars = readings.map((r) => BARS[Math.min(BARS.length - 1, Math.floor((r.tokens / top) * (BARS.length - 1)))]);
102  return bars.join("");
103}
104
105function trendWord() {
106  if (readings.length < 2) {
107    return "";
108  }
109  const delta = readings[readings.length - 1].tokens - readings[readings.length - 2].tokens;
110  if (delta > 0) return `▲ +${short(delta)} last turn`;
111  if (delta < 0) return `▼ ${short(-delta)} last turn`;
112  return "steady";
113}
114
115function short(n) {
116  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
117  if (n >= 1_000) return `${(n / 1_000).toFixed(n % 1_000 === 0 ? 0 : 1)}k`;
118  return String(n);
119}
120