aegis-desktop 0.7.1 → 0.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",

package/renderer/app.js

@@ -14,12 +14,13 @@
  * wrong.
  *
  * `budgetFor`/`maxTokensCeiling`/`FLAT_CEILING`/`EFFORT_TOKEN_BUDGET` come from
- * budget.js and `usageTokens` from usage.js, sibling classic scripts loaded
- * before this one (see index.html). There is no max-tokens control on this
- * surface at all: the ceiling is display-only (what a model says its own output
- * limit is, reported in the Model hint) and `budgetFor` answers — from the
- * Effort rung — what a request actually travels with. The token-usage →
- * displayed-number mapping stays unit-testable without window.aegis/models.
+ * budget.js and `turnAccounting`/`fmtCost` from usage.js, sibling classic
+ * scripts loaded before this one (see index.html). There is no
+ * max-tokens control on this surface at all: the ceiling is display-only (what a
+ * model says its own output limit is, reported in the Model hint) and
+ * `budgetFor` answers — from the Effort rung — what a request actually travels
+ * with. The token-usage → displayed-number mapping stays unit-testable without
+ * window.aegis/models.
  */
 
 // Everything below runs inside an IIFE. preload.js's contextBridge.exposeInMainWorld
@@ -105,6 +106,7 @@ const ELEMENT_IDS = {
   sessionsHint: 'sessions-hint',
   syncNow: 'sync-now',
   syncStatus: 'sync-status',
+  sessionMeter: 'session-meter',
   newChat: 'new-chat',
   memorySearchForm: 'memory-search-form',
   memoryQuery: 'memory-query',
@@ -229,6 +231,83 @@ let threadMessages = [];
 let classOptions = [];
 let modelMeta = new Map(); // model id -> raw model object from listModels() (P2 §6.3 ceiling)
 
+// ------------------------------------------------------- rolling token meter
+//
+// Tokens are accounted the way the CLI accounts them: as a RUNNING SESSION
+// TOTAL, folded turn by turn, not as a per-turn number that resets at the next
+// call. The CLI's `recordTurn` (cli/src/app.js) folds every finished turn into
+// one `session` object and prints that total in the status bar and in `ctrl+t`;
+// this surface printed each turn's count and nothing else, so the only way to
+// answer "what has this session spent" was to add the rows up by eye across the
+// scrollback. That is the accounting difference between two surfaces running
+// the same engine on the same prompt.
+//
+// Keyed by sessionId rather than held in one global, because the window holds
+// several sessions across its life: switching threads must not carry one
+// thread's spend into another's meter, and resuming a thread must not start its
+// total at zero. `rollMessages` rebuilds a resumed session's total from the
+// ledger rows the shared store already keeps.
+const rollsBySession = new Map();
+
+/** The rolling tallies for a session — empty, never undefined, when unseen. */
+function rollFor(sessionId) {
+  const id = sessionId || '';
+  if (!rollsBySession.has(id)) rollsBySession.set(id, emptyRoll());
+  return rollsBySession.get(id);
+}
+
+/**
+ * Fold one finished dispatch into its session's rolling total and refresh the
+ * meter. Returns the turn's own accounting so the caller can still print the
+ * per-turn figure beside the session total (the CLI shows both: the meta row's
+ * `1.5k tok` and the status bar's rolling total).
+ */
+function foldRoll(sessionId, usage, opts = {}) {
+  const id = sessionId || '';
+  const next = rollTurn(rollFor(id), usage, opts);
+  rollsBySession.set(id, next);
+  renderRollMeter(id);
+  return next;
+}
+
+/**
+ * Paint the topbar meter. Hidden while a session has accounted for nothing —
+ * an unused thread must not display a `0 tok` it never measured — and shown
+ * the moment a turn is folded in.
+ */
+function renderRollMeter(sessionId) {
+  const el = els.sessionMeter;
+  if (!el) return;
+  const roll = rollsBySession.get(sessionId || '');
+  const line = roll && currentSessionId === sessionId ? fmtRoll(roll) : '';
+  el.textContent = line;
+  el.hidden = !line;
+  if (line) el.title = 'This session, counted the way the CLI counts it — every turn rolled into one running total';
+}
+
+/**
+ * The ledger fields one finished turn must carry into the session store, so
+ * the rolling total can be REBUILT when the thread is reopened.
+ *
+ * Without this the rolling meter was a one-window illusion: the store kept
+ * `{role, content}` only, so `rollMessages` found no `tokens` on any row this
+ * window had written and a reopened thread came back as a stack of
+ * unaccounted turns while the CLI — whose `recordExchange` does write `tokens`
+ * and `costUsd` into the very same file — came back with its full total. That
+ * asymmetry is the accounting difference, not the rendering of it.
+ *
+ * Nothing is written for a turn that reported no usage: a fabricated
+ * `{input: 0, output: 0}` row would read as a measured zero forever after,
+ * which is the one lie the token meter was built to avoid.
+ */
+function ledgerFields(usage, model, turn) {
+  const fields = {};
+  if (turn && turn.tokens != null) fields.tokens = usageBuckets(usage);
+  if (turn && turn.cost != null && turn.real) fields.costUsd = turn.cost;
+  if (model) fields.model = model;
+  return fields;
+}
+
 // ---------------------------------------------------------- discovery lane
 //
 // The chat flow reads vertically: one prompt, one answer, forever. That makes
@@ -1977,6 +2056,15 @@ async function spawnPath(card, spec) {
         // text nor a tool call would trigger the empty-turn recovery — an
         // extra dispatch this lane has no gathered context to justify.
         tools: false,
+        // `singlePass` is what makes that promise true on the pooled class.
+        // The engine derives the pooled brain flag as
+        // `singlePass ? false : autonomous ? true : undefined`, and this lane
+        // set neither: on a `nexus-brain*` id the flag was `undefined`, so the
+        // model id's own default decided — which is the fan-out. A card that
+        // was meant to be one cheap 1024-token pass could therefore bill a
+        // workers + synthesis dispatch, twice per turn. Explicit `false` =
+        // one provider call, always.
+        singlePass: true,
         sessionId: id,
       },
       onDelta
@@ -1993,8 +2081,29 @@ async function spawnPath(card, spec) {
     const bits = [spec.path.title];
     if (data && data.model) bits.push(data.model);
     else if (spec.model) bits.push(spec.model);
-    const flowTokens = usageTokens(data && data.usage);
-    if (flowTokens != null) bits.push(`${flowTokens} tokens`);
+    // A lane card is a dispatch the same way a turn is, and it was the
+    // un-costed half of the 3x story: it reported tokens with no charge beside
+    // them, so the extra calls were the least visible thing on the screen.
+    const flow = turnAccounting(data && data.usage, spec.model, {
+      costUsd: data && typeof data.costUsd === 'number' ? data.costUsd : undefined,
+    });
+    if (flow.tokens != null) bits.push(`${flow.tokens} tokens`);
+    if (flow.cost != null) bits.push(fmtCost(flow.cost, flow.real));
+    // …and roll it into the session, which is the half that was missing. The
+    // card shows this ONE dispatch; a session total that skipped it would be
+    // the lane's calls — the extra ones this feature's cost story is made of —
+    // being the only calls on screen that never get counted. `turns: 0`
+    // because a discovery path is not a turn the user asked for: it
+    // contributes tokens and calls, and leaves the turn count to real
+    // exchanges.
+    const roll = foldRoll(spec.parentSessionId, data && data.usage, {
+      model: spec.model,
+      costUsd: data && typeof data.costUsd === 'number' ? data.costUsd : undefined,
+      calls: data && data.calls,
+      turns: 0,
+    });
+    const rollLine = fmtRoll(roll);
+    if (rollLine) bits.push(`session: ${rollLine}`);
     meta.textContent = bits.join(' · ');
   } catch (err) {
     const message = err && err.message ? err.message : String(err);
@@ -2845,6 +2954,15 @@ function openSession(id) {
       // its on-screen transcript — continuing it as sessionId reuses the same
       // id and threadMessages carries the prior turns into the next send().
       currentSessionId = s.id;
+      // A resumed thread resumes its spend too. The shared store's ledger rows
+      // carry `tokens`/`costUsd` (client/session-store.js recordExchange writes
+      // exactly the shape rollMessages reads), so the rolling total is rebuilt
+      // from what was really recorded rather than restarting at zero — the
+      // CLI's aggregateSessionUsage, which sums history.jsonl for the same
+      // reason. A row this window wrote before ledgerFields existed carries no
+      // `tokens` and folds as unaccounted, which is stated rather than guessed.
+      rollsBySession.set(s.id, rollMessages(msgs));
+      renderRollMeter(s.id);
       threadMessages = msgs
         .filter((m) => m.role === 'user' || m.role === 'assistant')
         .map((m) => ({ role: m.role, content: m.content || m.text || '' }));
@@ -2899,6 +3017,12 @@ function newChat() {
   currentSessionId = null;
   threadMessages = [];
   flowCount = 0;
+  // A fresh thread opens with an empty meter. The outgoing session's roll is
+  // left in the map (reopening it rebuilds from the store anyway), but the
+  // topbar must not keep showing the thread the user just left — `sessionId`
+  // nulls out here and the new id is minted on the first send, so nothing is
+  // hidden that will not reappear with this thread's own number.
+  renderRollMeter(null);
 }
 
 /**
@@ -3071,12 +3195,41 @@ async function send() {
     // class it is what sized the call, and a user cannot tell a 16k turn from a
     // 64k one by looking at the answer.
     else if (effort) bits.push(`effort: ${effort}`);
-    const turnTokens = usageTokens(data && data.usage);
-    if (turnTokens != null) bits.push(`tokens: ${turnTokens}`);
+    // Tokens AND what they cost, on the CLI's rule: a pooled turn's settled
+    // charge (`costUsd`) is reported verbatim, and only a turn without one is
+    // priced from the local rate table and marked an estimate. Printing tokens
+    // alone left this surface with no comparable meter at all — the desktop
+    // and the CLI run the same engine, so a gap between them had to be
+    // measured on the same prompt, and one side was not measuring.
+    const turn = turnAccounting(data && data.usage, model, {
+      costUsd: data && typeof data.costUsd === 'number' ? data.costUsd : undefined,
+    });
+    if (turn.tokens != null) bits.push(`tokens: ${turn.tokens}`);
+    if (turn.cost != null) bits.push(fmtCost(turn.cost, turn.real));
+    // …AND the running session total beside it, which is the number the CLI
+    // prints. The per-turn figure answers "what did that call cost"; only the
+    // rolling one answers "what has this conversation cost", and it was the
+    // missing half. Folded here rather than only on the meter so a turn that
+    // reported no usage still counts as a turn (rollTurn counts before it
+    // tests the count) instead of vanishing from the session.
+    const roll = foldRoll(sessionId, data && data.usage, {
+      model,
+      costUsd: data && typeof data.costUsd === 'number' ? data.costUsd : undefined,
+      calls: data && data.calls,
+    });
+    const rollLine = fmtRoll(roll);
+    if (rollLine) bits.push(`session: ${rollLine}`);
     addMessage('assistant', text, bits.join(' · ') || undefined, sessionId, toolLog);
 
     try {
-      await sync.append(sessionId, { role: 'assistant', content: text });
+      await sync.append(sessionId, {
+        role: 'assistant',
+        content: text,
+        // The turn's ledger fields, so this window's spend survives the window
+        // — see ledgerFields. This is what makes the rolling meter the same
+        // quantity after a reopen as it was before one.
+        ...ledgerFields(data && data.usage, model, turn),
+      });
       await sync.save({ id: sessionId, title: prompt.slice(0, 60) });
     } catch {
       /* persistence is non-fatal */
@@ -3206,9 +3359,17 @@ async function init() {
   });
   updateAutonomousControlsVisibility();
 
-  // The discovery lane is opt-in per machine, remembered across restarts.
+  // The discovery lane is opt-in, remembered across restarts.
+  //
+  // This used to read `savedExplore === 'off'` against a checkbox that shipped
+  // `checked` in index.html, i.e. the opposite of the comment above it: a fresh
+  // install (no `aegis.explore` key, and nothing had ever written one) landed
+  // with the lane ON and billed two extra model calls after every single turn —
+  // ~3× the tokens of a plain reply, silently, because the lane is
+  // fire-and-forget and never looks slow. Only an explicit 'on' turns it on
+  // now; every other state, including "never asked", means off.
   const savedExplore = localStorage.getItem(EXPLORE_KEY);
-  if (savedExplore === 'off') els.exploreToggle.checked = false;
+  els.exploreToggle.checked = savedExplore === 'on';
   els.exploreToggle.addEventListener('change', () => {
     localStorage.setItem(EXPLORE_KEY, els.exploreToggle.checked ? 'on' : 'off');
     if (!els.exploreToggle.checked) abortBranches();

package/renderer/index.html

@@ -22,6 +22,11 @@
       <span class="dot" id="conn-dot"></span>
       <span id="conn-text">connecting…</span>
     </div>
+    <!-- The rolling session token total, counted the way the CLI counts it:
+         every finished turn folded into one running number rather than a
+         per-turn count that resets. Hidden until a turn has been accounted
+         for, so an untouched thread never shows a `0 tok` it never measured. -->
+    <div class="session-meter" id="session-meter" hidden></div>
     <div class="spacer"></div>
     <button type="button" id="new-chat" class="ghost-btn">New chat</button>
   </header>
@@ -353,9 +358,12 @@
           <label
             class="flow-toggle"
             for="explore-toggle"
-            title="After every answer, send the AI down two extra paths — an alternative angle and an unexpected discovery — shown as a horizontal discovery lane."
+            title="Optional, off by default. After every answer, send the AI down two extra paths — an alternative angle and an unexpected discovery — shown as a horizontal discovery lane. This costs two extra model calls per turn (roughly 3× the tokens of a plain reply)."
           >
-            <input type="checkbox" id="explore-toggle" checked />
+            <!-- Unchecked in the markup on purpose: the lane bills two extra
+                 model calls per turn, so it is opt-in. app.js only ticks this
+                 when the user has explicitly saved 'on' (aegis.explore). -->
+            <input type="checkbox" id="explore-toggle" />
             <span>discovery lane</span>
           </label>
           <button type="submit" id="send">Send</button>

package/renderer/style.css

@@ -114,6 +114,28 @@ body {
   box-shadow: 0 0 6px var(--teal);
 }
 
+/* The rolling session token total — the CLI's status-bar figure, in the
+   topbar. Muted and monospaced so it reads as a meter rather than a heading,
+   and it never wraps: a number that reflows the topbar every turn is worse
+   than no number at all. Hidden via the `hidden` attribute, so the rule below
+   has to win against the flex display the base class would otherwise get. */
+.session-meter {
+  font-size: 12px;
+  font-family: var(--font-mono);
+  color: var(--text2);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 40ch;
+  padding: 2px 8px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+}
+
+.session-meter[hidden] {
+  display: none;
+}
+
 .spacer {
   flex: 1;
 }

package/renderer/usage.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Pure token-usage → display-number mapping.
+ * Pure token-usage → display-number mapping, and the cost half of it.
  *
  * Standalone from app.js (same reason as budget.js/stream-policy.js): it is
  * requireable from a plain Node test without window.aegis. app.js only calls
@@ -18,6 +18,27 @@
  * the call was silently being billed. Accepting both spellings, and deriving
  * the total when the provider doesn't state one, is what makes the spend
  * visible regardless of which endpoint answered.
+ *
+ * ── The cost half, on the CLI's principle ──────────────────────────────────
+ *
+ * The renderer printed a token count and nothing else, so the desktop had no
+ * meter to compare against `aegiscodex` on the same engine and the same
+ * prompt — the comparison that started this whole line of work. The CLI's
+ * rule (cli/src/tokens.js, ported here) has three parts, and all three matter:
+ *
+ *   1. A pooled turn's bill is settled SERVER-side and carries a margin and a
+ *      prompt-cache discount the client cannot see. When the response states
+ *      `costUsd`, that figure wins verbatim — it is the truth about the
+ *      charge, not an estimate of it.
+ *   2. Only in the absence of a settled charge does the local rate table
+ *      apply, and the result is labeled an estimate so nobody reads a guess as
+ *      a bill.
+ *   3. The rate table is resolved by exact id, then longest prefix. The
+ *      DeepSeek row is load-bearing: without it every direct DeepSeek turn
+ *      fell through to Sonnet's $3.00/$15.00 per M against a real
+ *      $0.14/$0.28 — 21x the input rate and 54x the output rate — which made
+ *      the *meter* the largest single contributor to the apparent cost gap
+ *      between two surfaces running identical code.
  */
 
 /**
@@ -25,18 +46,352 @@
  * reported none (an unknown count must render as nothing, never as `0`).
  *
  * @param {{total_tokens?: number, prompt_tokens?: number, completion_tokens?: number,
- *          input_tokens?: number, output_tokens?: number}|null|undefined} usage
+ *          input_tokens?: number, output_tokens?: number,
+ *          input?: number, output?: number}|null|undefined} usage
  * @returns {number|null}
  */
 function usageTokens(usage) {
   if (!usage || typeof usage !== 'object') return null;
   if (typeof usage.total_tokens === 'number') return usage.total_tokens;
-  const input = usage.input_tokens ?? usage.prompt_tokens;
-  const output = usage.output_tokens ?? usage.completion_tokens;
+  // Three spellings of the same quantity: OpenAI's, Anthropic's, and this
+  // file's own bucket shape — which is also the shape a LEDGER row carries
+  // (cli/src/history.js writes `{input, output, cacheRead, cacheWrite}` into
+  // sessions.json, and the CLI's demo path writes `{input, output}`). Reading
+  // only the two wire spellings left every stored row uncountable, so a
+  // resumed session's rolling total started at zero even though its ledger
+  // said otherwise.
+  const input = usage.input_tokens ?? usage.prompt_tokens ?? usage.input;
+  const output = usage.output_tokens ?? usage.completion_tokens ?? usage.output;
   if (typeof input !== 'number' && typeof output !== 'number') return null;
   return (input || 0) + (output || 0);
 }
 
+// Per-million-token USD rates. Cache-read/write matter for long sessions.
+//
+// These are the PROVIDER's rates, for the fallback path where a turn has no
+// server-settled charge (a direct provider, ollama, a custom endpoint). A
+// pooled turn reports the ledger figure instead — see turnAccounting's
+// `costUsd` — because the pool's bill carries a margin and a prompt-cache
+// discount this table cannot see.
+//
+// Keys are matched by exact id first, then by prefix (ratesFor below), so a
+// family row covers every dated variant of it.
+const RATES = {
+  sonnet:  { input: 3.00, output: 15.00, cacheRead: 0.30, cacheWrite: 3.75 },
+  default: { input: 3.00, output: 15.00, cacheRead: 0.30, cacheWrite: 3.75 },
+  fable:   { input: 5.00, output: 25.00, cacheRead: 0.50, cacheWrite: 6.25 },
+  opus:    { input: 5.00, output: 25.00, cacheRead: 0.50, cacheWrite: 6.25 },
+  // DeepSeek V4 — the provider's published rate, independently corroborated by
+  // aegis1 services/nexus_provider/catalog.py (cost_per_1k_input=0.00014,
+  // cost_per_1k_output=0.00028) and referenced in services/pricing.py.
+  //
+  // This row was MISSING upstream, and usageCost fell through to RATES.sonnet
+  // for every DeepSeek turn: $3.00/$15.00 per M against a real $0.14/$0.28 —
+  // 21x the input rate and 54x the output rate, on every direct DeepSeek call.
+  //
+  // cacheRead is 0.1x input (aegis1 services/pricing.py
+  // CACHE_READ_FRACTION_BY_COMPANY["deepseek"] = 0.1 -> $0.014/M).
+  // cacheWrite is the input rate: DeepSeek bills a cache write as ordinary
+  // input tokens and charges no separate write premium, unlike Anthropic's
+  // 1.25x. A zero here would understate a session that writes cache.
+  deepseek: { input: 0.14, output: 0.28, cacheRead: 0.014, cacheWrite: 0.14 },
+};
+
+/**
+ * The rate row for a model id, provider, or alias. Exact id wins, then the
+ * longest matching prefix, then the Sonnet-class default.
+ */
+function ratesFor(model) {
+  const id = String(model || '').toLowerCase();
+  if (!id) return RATES.default;
+  if (RATES[id]) return RATES[id];
+  let best = null;
+  let bestLen = 0;
+  for (const [prefix, rates] of Object.entries(RATES)) {
+    if (id.startsWith(prefix) && prefix.length > bestLen) {
+      best = rates;
+      bestLen = prefix.length;
+    }
+  }
+  return best || RATES.default;
+}
+
+/**
+ * The four billable buckets from a wire usage object, accepting both provider
+ * spellings. Cache fields have no Anthropic-compatible short form here because
+ * the desktop's transport normalises them (desktop/lib/local/providers.js).
+ *
+ * @param {object|null|undefined} usage
+ * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number}}
+ */
+function usageBuckets(usage) {
+  const u = usage && typeof usage === 'object' ? usage : {};
+  const num = (...candidates) => {
+    for (const c of candidates) if (typeof c === 'number') return c;
+    return 0;
+  };
+  const input = num(u.input_tokens, u.prompt_tokens, u.input);
+  const output = num(u.output_tokens, u.completion_tokens, u.output);
+  // A stated total larger than the split means the provider counted tokens the
+  // split does not name (thinking, cached reads). Attribute the remainder to
+  // input rather than dropping it: dropping it would understate the bill.
+  const total = num(u.total_tokens);
+  const cacheRead = num(u.cache_read_input_tokens, u.cacheRead);
+  const cacheWrite = num(u.cache_creation_input_tokens, u.cacheWrite);
+  const accounted = input + output + cacheRead + cacheWrite;
+  return {
+    input: total > accounted ? input + (total - accounted) : input,
+    output,
+    cacheRead,
+    cacheWrite,
+  };
+}
+
+/** Dollar cost of a usage record at the given model's rates (USD, estimate). */
+function usageCost(usage, model = 'sonnet') {
+  const r = ratesFor(model);
+  const u = usageBuckets(usage);
+  const toD = (n, rate) => (n / 1_000_000) * rate;
+  return toD(u.input, r.input)
+    + toD(u.output, r.output)
+    + toD(u.cacheRead, r.cacheRead)
+    + toD(u.cacheWrite, r.cacheWrite);
+}
+
+/**
+ * What one turn cost, as the CLI reports it: the server's settled charge when
+ * the response carries one, otherwise the rate table's estimate, always with
+ * the distinction preserved so it can be labeled.
+ *
+ * @param {object|null|undefined} usage  the response's `usage` object
+ * @param {string} model                 the model id that answered
+ * @param {{costUsd?: number}} [opts]    the server-settled charge, if any
+ * @returns {{tokens: number|null, cost: number|null, real: boolean, estimated: boolean}}
+ *          `real` is true only when `cost` is the settled charge. `cost` is
+ *          `null` when nothing was reported and no model was named — an
+ *          unpriced turn must render as nothing, never as $0.0000.
+ */
+function turnAccounting(usage, model, opts = {}) {
+  const tokens = usageTokens(usage);
+  const u = usage && typeof usage === 'object' ? usage : {};
+  // The settled charge can arrive either on the response or folded into the
+  // usage object — aegiscodex-dev/src/main.js does the latter
+  // (`{ ...result.usage, costUsd: result.costUsd }`), so both are accepted.
+  const settled = typeof opts.costUsd === 'number'
+    ? opts.costUsd
+    : (typeof u.costUsd === 'number' ? u.costUsd : undefined);
+  if (typeof settled === 'number') {
+    return { tokens, cost: settled, real: true, estimated: false };
+  }
+  if (tokens == null) return { tokens, cost: null, real: false, estimated: false };
+  const priced = usageCost(u, model);
+  // A model the table cannot place is still priced at the Sonnet-class default
+  // (ratesFor never returns nothing), so this is always an estimate.
+  return { tokens, cost: priced, real: false, estimated: true };
+}
+
+/**
+ * ── The rolling session tallies, on the CLI's rule ─────────────────────────
+ *
+ * The two surfaces did not merely print different numbers — they counted
+ * differently. The CLI never shows a turn's tokens in isolation: `recordTurn`
+ * (cli/src/app.js) folds each finished turn's usage into one `session` object
+ * — `tokens`, `inputTokens`, `outputTokens`, `calls` — and what the user reads
+ * back is that RUNNING TOTAL. The status bar prints `state.tokens`
+ * (renderStatus), and `ctrl+t` prints the tallies in one line
+ * (`tokenSummary`: `12,400 tok (10,100 in / 2,300 out) · 4 calls · €0.03`).
+ *
+ * The desktop counted per turn only. Every meta row was a fresh count that
+ * reset at the next call, so "what has this session spent" was answerable only
+ * by adding the rows up by eye across a scrollback — which is most of why the
+ * desktop looked like it accounted differently from the CLI on identical
+ * engine code and an identical prompt.
+ *
+ * Three properties of the CLI's fold are load-bearing and are reproduced here
+ * exactly, because dropping any one of them reintroduces a specific lie:
+ *
+ *   1. `turns` and `calls` are incremented BEFORE the "did usage come back?"
+ *      gate (recordTurn counts first, then tests `tokens != null`). A turn
+ *      that reported nothing still happened; a tally that skipped it would
+ *      report the session as shorter and cheaper than it was.
+ *   2. `tokens`, `input` and `output` accumulate — never reset. A rolling
+ *      total that resets per turn is the per-turn count it replaced.
+ *   3. A `null` count contributes nothing and is counted in `unknown`, so
+ *      `tokens: 0` is only ever read as a real zero. Nothing is ever added as
+ *      a fabricated 0 to make the arithmetic look complete.
+ *
+ * The money split is the CLI's too: a settled charge (the pool's ledger
+ * figure) rolls into `cost`, and a locally priced turn rolls into `estimate`.
+ * They are kept apart rather than summed so a `~`-estimate can never be read
+ * as part of the bill — the distinction `fmtCost` marks on a single turn, held
+ * across the session.
+ */
+
+/** A session with nothing accounted for yet. */
+function emptyRoll() {
+  return {
+    turns: 0,
+    calls: 0,
+    tokens: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    /** Dispatches that reported no usage at all — the honest gap in `tokens`. */
+    unknown: 0,
+    /** Settled charges (server-settled `costUsd`), rolled. */
+    cost: 0,
+    /** Locally priced turns, rolled. Never mixed into `cost`. */
+    estimate: 0,
+  };
+}
+
+/**
+ * Fold one completed dispatch into a session's rolling tallies. Pure: it
+ * returns a NEW roll and never mutates the one it was handed, so a half-applied
+ * fold cannot exist.
+ *
+ * @param {object} [roll]      the roll so far (emptyRoll() when omitted)
+ * @param {object} [usage]     the response's `usage` object
+ * @param {{model?: string, costUsd?: number, calls?: number, turns?: number}} [opts]
+ *        `calls` defaults to 1; a pooled turn may report how many provider
+ *        calls it actually made. `turns: 0` folds a dispatch that is not a
+ *        turn of its own — the discovery-lane card, which bills like any other
+ *        call but is not something the user asked for.
+ * @returns {object} the new roll
+ */
+function rollTurn(roll, usage, opts = {}) {
+  const next = Object.assign(emptyRoll(), roll || {});
+  next.turns += opts.turns === undefined ? 1 : Number(opts.turns) || 0;
+  next.calls += opts.calls === undefined ? 1 : Number(opts.calls) || 0;
+  const turn = turnAccounting(usage, opts.model, { costUsd: opts.costUsd });
+  if (turn.tokens == null) {
+    next.unknown += 1;
+    return next;
+  }
+  const b = usageBuckets(usage);
+  next.tokens += turn.tokens;
+  next.input += b.input;
+  next.output += b.output;
+  next.cacheRead += b.cacheRead;
+  next.cacheWrite += b.cacheWrite;
+  if (turn.real) next.cost += turn.cost;
+  else if (turn.cost != null) next.estimate += turn.cost;
+  return next;
+}
+
+/**
+ * Rebuild a session's rolling total from stored exchanges — the desktop's
+ * counterpart of the CLI's `aggregateSessionUsage`, which sums history.jsonl so
+ * a resumed session (and a compacted one) still reports everything it spent.
+ *
+ * Reads the shapes the shared store writes: an assistant message carrying
+ * `tokens: {input, output, cacheRead, cacheWrite}` and, when the pool settled
+ * the turn, `costUsd` (cli/src/history.js → session-store.recordExchange).
+ * Messages the desktop itself appended carry no `tokens` and fold as `unknown`
+ * — a resumed thread states what is known and does not invent the rest.
+ *
+ * @param {Array<{role?: string, tokens?: object, costUsd?: number, model?: string}>} [messages]
+ * @returns {object} the roll
+ */
+function rollMessages(messages) {
+  let roll = emptyRoll();
+  for (const m of Array.isArray(messages) ? messages : []) {
+    if (!m || m.role !== 'assistant') continue;
+    roll = rollTurn(roll, m.tokens, {
+      model: m.model,
+      costUsd: typeof m.costUsd === 'number' ? m.costUsd : undefined,
+      calls: m.calls,
+    });
+  }
+  return roll;
+}
+
+/**
+ * The CLI's rendering of a session tally — `cli/src/format.js fmtTokens`, which
+ * is the one `tokenSummary` actually imports (`cli/src/app.js:50`). NOT the
+ * `1.5k`/`12.3k` form in `cli/src/tokens.js`: that one belongs to the /cost
+ * panels, and using it here would print `12.4k` on the very total the CLI
+ * prints as `12,400` — a rendering difference stacked on top of the accounting
+ * difference this change exists to remove.
+ *
+ * Comma-grouped integer. Anything not finite and positive renders `0`, which is
+ * the CLI's rule and keeps a stray NaN from reaching the topbar.
+ */
+function fmtTokens(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v) || v <= 0) return '0';
+  return Math.round(v)
+    .toString()
+    .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+/**
+ * The rolling session total as one line — the desktop's counterpart of the
+ * CLI's `tokenSummary`. Empty string when nothing has been accounted for, so
+ * an untouched session adds no noise to a turn's meta line.
+ *
+ * @param {object} [roll]
+ * @returns {string} e.g. `12,400 tok (10,100 in / 2,300 out) · 4 calls · $0.0310`
+ */
+function fmtRoll(roll) {
+  const r = roll || emptyRoll();
+  if (!r.turns && !r.calls) return '';
+  // The first two fields are `tokenSummary` (cli/src/app.js:1413) verbatim,
+  // separator and all: `12,400 tok (10,100 in / 2,300 out) · 4 calls`. There the
+  // parenthetical is unconditional and the call count is singular at one; both
+  // are kept, because a line that is only *sometimes* shaped like the CLI's is a
+  // lookalike rather than the same quantity. The call count is also the number
+  // that reveals a fan-out, which is why it is not hidden at 1.
+  const bits = [
+    `${fmtTokens(r.tokens)} tok (${fmtTokens(r.input)} in / ${fmtTokens(r.output)} out)`,
+    `${r.calls} call${r.calls === 1 ? '' : 's'}`,
+  ];
+  // Money is where this line departs from `tokenSummary`, deliberately: that
+  // one sums a single `session.cost` in EUR via fmtEur, while this surface keeps
+  // a settled charge and a local estimate apart so a `~`-estimate can never be
+  // read as part of the bill. Desktop's pre-existing fmtCost renders both, and
+  // its `$` convention is left exactly as it was.
+  if (r.cost > 0 || r.estimate > 0) {
+    const money = [];
+    if (r.cost > 0) money.push(fmtCost(r.cost, true));
+    if (r.estimate > 0) money.push(fmtCost(r.estimate, false));
+    bits.push(money.join(' + '));
+  }
+  // No counterpart in `tokenSummary`, which folds a usage-less turn silently and
+  // so reports a total short of the truth without saying so. Named here instead:
+  // the count appears only when something went unreported, and it never changes
+  // a number — it only says the number is not the whole story.
+  if (r.unknown) bits.push(`${r.unknown} unrpt`);
+  return bits.join(' · ');
+}
+
+/**
+ * A cost for display. Estimates are marked with `~` so an estimate is never
+ * mistaken for a settled charge.
+ *
+ * @param {number} cost
+ * @param {boolean} [real]
+ * @returns {string}
+ */
+function fmtCost(cost, real) {
+  if (typeof cost !== 'number' || !isFinite(cost)) return '';
+  return `${real ? '' : '~'}$${cost.toFixed(4)}`;
+}
+
 if (typeof module !== 'undefined' && module.exports) {
-  module.exports = { usageTokens };
+  module.exports = {
+    RATES,
+    usageTokens,
+    ratesFor,
+    usageBuckets,
+    usageCost,
+    turnAccounting,
+    emptyRoll,
+    rollTurn,
+    rollMessages,
+    fmtTokens,
+    fmtRoll,
+    fmtCost,
+  };
 }