aegiscode 6.8.2 → 6.8.4

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.
@@ -74,6 +74,17 @@ const CONFIRM_MODE_NAMESPACE = '__confirmMode';
74
74
  * what turns it off. Nothing secret lives here, so no encryption. */
75
75
  const MEMORY_PERSIST_NAMESPACE = '__memoryPersist';
76
76
 
77
+ /** Reserved namespace for the avatar/companion preferences (Phase 21):
78
+ * `{ enabled, showLevel, motion }` — app-level, not a provider, so it stays out
79
+ * of the provider CRUD surface for the same reason the AEGIS key does. The
80
+ * persona itself is deliberately NOT stored here: it is a document, not a
81
+ * preference, and it lives at `<userData>/avatar/persona.json`, read and
82
+ * written by main through lib/avatar/store.js so a hand-edited or imported
83
+ * persona is validated on the way in (see docs/avatar-plan.md §3).
84
+ * Defaults are the shipped behaviour: the avatar is ON, the level readout is
85
+ * shown, and motion follows the OS `prefers-reduced-motion` setting. */
86
+ const AVATAR_NAMESPACE = '__avatar';
87
+
77
88
  /** Namespaces the provider-config surface must never see or mutate. */
78
89
  const RESERVED_NAMESPACES = Object.freeze([
79
90
  AEGIS_KEY_NAMESPACE,
@@ -81,8 +92,12 @@ const RESERVED_NAMESPACES = Object.freeze([
81
92
  QUICK_LAUNCHER_NAMESPACE,
82
93
  CONFIRM_MODE_NAMESPACE,
83
94
  MEMORY_PERSIST_NAMESPACE,
95
+ AVATAR_NAMESPACE,
84
96
  ]);
85
97
 
98
+ /** Motion modes the renderer understands (`system` = follow the OS). */
99
+ const AVATAR_MOTION_MODES = Object.freeze(['system', 'full', 'minimal']);
100
+
86
101
  /** True for the AEGIS-key namespace(s) — provider CRUD must refuse these. */
87
102
  function isReservedNamespace(provider) {
88
103
  return RESERVED_NAMESPACES.includes(provider);
@@ -359,6 +374,53 @@ function createSettingsStore({ dir, safeStorage } = {}) {
359
374
  return memoryPersistState();
360
375
  }
361
376
 
377
+ // --- Avatar: reserved namespace, plain preferences (Phase 21) ------------
378
+ // The companion's on/off switch, its level readout, and its motion mode.
379
+ // Nothing secret lives here, so no encryption — same reasoning as the quick
380
+ // launcher and memory-persist namespaces above.
381
+ //
382
+ // Deliberately narrow: `setAvatar()` stores only these three known keys, so a
383
+ // renderer (or a hand-edited settings.json) cannot park arbitrary state — a
384
+ // persona document, a capability override — in a namespace main reads back.
385
+ // The persona is a separate, validated file (lib/avatar/store.js) for exactly
386
+ // that reason.
387
+
388
+ function getAvatar() {
389
+ const cfg = load()[AVATAR_NAMESPACE] || {};
390
+ return {
391
+ // Unset === true: the companion ships on; an explicit `false` is the only
392
+ // thing that turns it off (and it must survive a reload).
393
+ enabled: cfg.enabled === undefined ? true : Boolean(cfg.enabled),
394
+ showLevel: cfg.showLevel === undefined ? true : Boolean(cfg.showLevel),
395
+ motion: AVATAR_MOTION_MODES.includes(cfg.motion) ? cfg.motion : 'system',
396
+ };
397
+ }
398
+
399
+ /** `{ ...preferences, source }` — mirrors memoryPersistState() so "off" and
400
+ * "never set" stay distinguishable in the UI and in tests. */
401
+ function avatarState() {
402
+ const cfg = load()[AVATAR_NAMESPACE] || {};
403
+ return {
404
+ ...getAvatar(),
405
+ source: cfg.enabled === undefined ? 'default' : 'config',
406
+ };
407
+ }
408
+
409
+ /** Partial merge of the three known keys. Unknown keys are dropped, not saved. */
410
+ function setAvatar(patch = {}) {
411
+ const current = getAvatar();
412
+ const p = patch && typeof patch === 'object' ? patch : {};
413
+ const next = {
414
+ enabled: p.enabled === undefined ? current.enabled : Boolean(p.enabled),
415
+ showLevel: p.showLevel === undefined ? current.showLevel : Boolean(p.showLevel),
416
+ motion: AVATAR_MOTION_MODES.includes(p.motion) ? p.motion : current.motion,
417
+ };
418
+ const data = load();
419
+ data[AVATAR_NAMESPACE] = next;
420
+ save(data);
421
+ return avatarState();
422
+ }
423
+
362
424
  return {
363
425
  file,
364
426
  get,
@@ -379,6 +441,9 @@ function createSettingsStore({ dir, safeStorage } = {}) {
379
441
  getMemoryPersist,
380
442
  memoryPersistState,
381
443
  setMemoryPersist,
444
+ getAvatar,
445
+ avatarState,
446
+ setAvatar,
382
447
  };
383
448
  }
384
449
 
@@ -389,6 +454,8 @@ module.exports = {
389
454
  QUICK_LAUNCHER_NAMESPACE,
390
455
  CONFIRM_MODE_NAMESPACE,
391
456
  MEMORY_PERSIST_NAMESPACE,
457
+ AVATAR_NAMESPACE,
458
+ AVATAR_MOTION_MODES,
392
459
  DEFAULT_QUICK_LAUNCHER_SHORTCUT,
393
460
  RESERVED_NAMESPACES,
394
461
  isReservedNamespace,
@@ -143,22 +143,104 @@ const RATES = {
143
143
  default: { input: 3.00, output: 15.00, cacheRead: 0.30, cacheWrite: 3.75 },
144
144
  fable: { input: 5.00, output: 25.00, cacheRead: 0.50, cacheWrite: 6.25 },
145
145
  opus: { input: 5.00, output: 25.00, cacheRead: 0.50, cacheWrite: 6.25 },
146
- // DeepSeek V4 — the provider's published rate, independently corroborated by
147
- // aegis1 services/nexus_provider/catalog.py (cost_per_1k_input=0.00014,
148
- // cost_per_1k_output=0.00028) and referenced in services/pricing.py.
146
+ // Haiku — the same class of hole as the DeepSeek row below, on the provider
147
+ // whose prices we already thought we knew. The three rows above price Sonnet,
148
+ // Opus and Fable; a Haiku turn matched no exact key, no prefix
149
+ // ("claude-haiku-4-5" starts with none of them) and no family name, so it
150
+ // fell to the Sonnet-class default at 3x its real input and output rate.
149
151
  //
150
- // This row was MISSING upstream, and usageCost fell through to RATES.sonnet
151
- // for every DeepSeek turn: $3.00/$15.00 per M against a real $0.14/$0.28 —
152
- // 21x the input rate and 54x the output rate, on every direct DeepSeek call.
152
+ // $1.00/$5.00 per M (Anthropic's published rate). cacheRead/cacheWrite
153
+ // follow the convention the three rows above already encode — 0.1x and 1.25x
154
+ // input — rather than being quoted independently, so the Anthropic rows
155
+ // cannot drift apart from each other.
156
+ haiku: { input: 1.00, output: 5.00, cacheRead: 0.10, cacheWrite: 1.25 },
157
+ // `claude-haiku-4-5` names its family after the vendor prefix, so the
158
+ // family-scan fallback (raw.includes(key)) would find it — but only after the
159
+ // prefix loop, and the prefix `claude` is not a key. Listed explicitly so the
160
+ // match is EXACT and cannot be reordered away.
161
+ 'claude-haiku': { input: 1.00, output: 5.00, cacheRead: 0.10, cacheWrite: 1.25 },
162
+
163
+ // DeepSeek — read off the vendor's own pricing table
164
+ // (api-docs.deepseek.com/quick_start/pricing), not from a secondary blog and
165
+ // not from a mirror of our own catalog.
166
+ //
167
+ // The row this replaces said $0.14/$0.28, sourced from aegis1's
168
+ // catalog.py (cost_per_1k_input=0.00014) and referenced in pricing.py. That
169
+ // figure is the retired **V4-Flash** tier, and the vendor's own footnote (1)
170
+ // retires it explicitly: "The legacy names deepseek-v4-flash and
171
+ // deepseek-v4-flash-vision-exp are still accepted, but the corresponding
172
+ // models have been retired, their requests are served by the
173
+ // DeepSeek-V4.1-Flash model and billed at the Flash price." So every legacy
174
+ // id — which is what the picker advertises and what a user pins — bills at
175
+ // the V4.1 figures below, ~2.1x the old row.
153
176
  //
154
- // cacheRead is 0.1x input (aegis1 services/pricing.py
155
- // CACHE_READ_FRACTION_BY_COMPANY["deepseek"] = 0.1 -> $0.014/M).
177
+ // The rate is TIME-DEPENDENT (peak 01:00-04:00 and 06:00-10:00 UTC Mon-Fri),
178
+ // so one flat row cannot state the price — it can only state one of the two.
179
+ // `offPeak` carries the other and ratesFor() picks by the wall clock.
180
+ //
181
+ // cacheRead is the CACHE HIT price the vendor quotes directly ($0.006 peak),
182
+ // not a fraction of input: it is 50x cheaper than input, which is what makes
183
+ // the cache-hit rate worth measuring at all. Deriving it as 0.1x input — the
184
+ // convention aegis1/pricing.py used — overstated it 2.3x.
156
185
  // cacheWrite is the input rate: DeepSeek bills a cache write as ordinary
157
- // input tokens and charges no separate write premium, unlike Anthropic's
158
- // 1.25x. A zero here would understate a session that writes cache.
159
- deepseek: { input: 0.14, output: 0.28, cacheRead: 0.014, cacheWrite: 0.14 },
186
+ // input tokens with no write premium, unlike Anthropic's 1.25x.
187
+ deepseek: {
188
+ input: 0.30, output: 1.20, cacheRead: 0.006, cacheWrite: 0.30,
189
+ offPeak: { input: 0.15, output: 0.60, cacheRead: 0.003, cacheWrite: 0.15 },
190
+ },
191
+ // DeepSeek-V4-Pro-0813 — a different, pricier model. Longest-prefix matching
192
+ // keeps it from being shadowed by the `deepseek` family row above.
193
+ 'deepseek-v4-pro': {
194
+ input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 1.32,
195
+ offPeak: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0.66 },
196
+ },
197
+ // `deepseek-v4.1-pro` is a spelling the plugin's OWN regex accepts
198
+ // (DEEPSEEK_REASONING_MODEL_RE: `v4(\.\d+)?-(flash|pro)`), so a config can
199
+ // carry it and the picker can advertise it. It is listed explicitly because
200
+ // the prefix loop cannot reach the row above — "deepseek-v4.1-pro" does not
201
+ // start with "deepseek-v4-pro" — so it matched the `deepseek` KEY by PREFIX
202
+ // (the prefix branch, not the family scan, though that key is also the row
203
+ // the family scan lands on) and a Pro-tier turn was billed at Flash rates.
204
+ //
205
+ // Figures are the Pro tier's ($1.32/$3.96 per M), the same tier the tail of
206
+ // the id names. This is deliberately the DEARER reading: an id that names
207
+ // "pro" and prices at Flash under-reports spend, which is the direction that
208
+ // cannot be recovered after the fact. Sources disagree on V4 Pro's current
209
+ // rate (one registry still carries an August 12 check at $0.435/$0.87), so
210
+ // treat this row as the one figure here most worth confirming against an
211
+ // invoice.
212
+ 'deepseek-v4.1-pro': {
213
+ input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 1.32,
214
+ offPeak: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0.66 },
215
+ },
160
216
  };
161
217
 
218
+ /**
219
+ * Is `at` inside DeepSeek's peak window? 01:00-04:00 and 06:00-10:00 UTC,
220
+ * Monday-Friday. Everything else, weekends included, is off-peak at half rate.
221
+ *
222
+ * The vendor also excludes Chinese public holidays, which we do NOT model: the
223
+ * published table lists them by date, so honouring them would mean shipping a
224
+ * calendar that goes stale. The consequence is bounded and one-directional —
225
+ * on a holiday we price at peak (the dearer reading) instead of off-peak — and
226
+ * over-reporting a spend is recoverable where under-reporting is not.
227
+ */
228
+ function isPeak(provider, at = new Date()) {
229
+ if (String(provider || '').toLowerCase().indexOf('deepseek') !== 0) return true;
230
+ const day = at.getUTCDay();
231
+ if (day === 0 || day === 6) return false;
232
+ const hour = at.getUTCHours();
233
+ return (hour >= 1 && hour < 4) || (hour >= 6 && hour < 10);
234
+ }
235
+
236
+ /** How a model id was matched to a rate row — see ratesFor. */
237
+ const RATE_BASIS = Object.freeze({
238
+ EXACT: 'exact',
239
+ PREFIX: 'prefix',
240
+ FAMILY: 'family',
241
+ DEFAULT: 'default',
242
+ });
243
+
162
244
  /**
163
245
  * The rate rows a model id may name as a whole word rather than as a prefix.
164
246
  * Anthropic spells its family *inside* the id — "claude-opus-4" matches no
@@ -167,35 +249,122 @@ const RATES = {
167
249
  const RATE_FAMILIES = Object.keys(RATES).filter((k) => k !== 'default');
168
250
 
169
251
  /**
170
- * The rate row for a model id, provider, or alias. Exact id wins, then the
171
- * longest matching prefix, then a family named inside the id, then the
172
- * Sonnet-class default.
252
+ * Ids this module can be handed that deliberately have NO row, with the reason.
253
+ *
254
+ * `test/rate-coverage.test.mjs` fails the build when an id the plugin's own
255
+ * source routes to resolves to RATE_BASIS.DEFAULT without appearing here. That
256
+ * is the mechanism that was missing on the day the picker started advertising
257
+ * DeepSeek: nothing compared "ids we route to" against "ids we have priced", so
258
+ * the gap had no surface on which to show up as a failure.
259
+ *
260
+ * Two honest reasons to be in this list, and no others:
261
+ *
262
+ * - POOLED: aegis1 bills the pool call and reports the settled figure, which
263
+ * `turnAccounting` already prefers over anything computed here (its
264
+ * `costUsd` branch). A local guess would be a second, worse number printed
265
+ * beside the real charge — and for the brain tiers it would also miss the
266
+ * fan-out factor (see ID_NOTES in cli/src/models.js: four billed provider
267
+ * calls per turn at effort=high, sized by the ask).
268
+ * - PROVIDER: a bare provider (`anthropic`, `groq`) is a ROUTING choice — "let
269
+ * the pool pick" — not a model. It names no rate because it names no model.
270
+ *
271
+ * Anything else belongs in RATES. An entry here is a claim that we have no
272
+ * business pricing it, not a parking space for a rate we have not looked up.
173
273
  */
174
- function ratesFor(model) {
274
+ const UNPRICED_BY_DESIGN = Object.freeze({
275
+ // Pooled seats — the ledger carries the charge.
276
+ 'nexus-brain': 'pooled: multi-call fan-out, aegis1 settles the charge',
277
+ 'aegis-brain': 'pooled alias of nexus-brain',
278
+ 'nexus-brain-smart': 'pooled alias of nexus-brain',
279
+ 'nexus-brain-neo': 'pooled alias of nexus-brain',
280
+ 'aegis-brain-smart': 'pooled alias of nexus-brain',
281
+ 'aegis-brain-neo': 'pooled alias of nexus-brain',
282
+ 'openai-gpt4o-mini': 'pooled seat, aegis1 settles the charge',
283
+ // Bare provider names — a routing choice, not a model.
284
+ anthropic: 'provider name, not a model id',
285
+ openai: 'provider name, not a model id',
286
+ groq: 'provider name, not a model id',
287
+ google: 'provider name, not a model id',
288
+ xai: 'provider name, not a model id',
289
+ });
290
+
291
+ /**
292
+ * The rate row for a model id, plus HOW it was matched.
293
+ *
294
+ * `basis` is the whole point of the return shape. This used to be
295
+ * `return family || RATES.default` — a bare row — so an id nobody had priced
296
+ * (DeepSeek, until this change; Haiku too) was silently priced at Sonnet's
297
+ * $3/$15 and rendered as though it were a measurement. A wrong number that
298
+ * announces itself is a bug report; a wrong number that looks like every other
299
+ * number is a fabrication, and it survived because nothing downstream could
300
+ * tell the two apart.
301
+ *
302
+ * So the fallback still exists — a caller needs *a* number to render — but it
303
+ * is now labeled: `basis: 'default'` means "we do not know this model's price
304
+ * and this figure is a Sonnet-class placeholder". Callers that display money
305
+ * are expected to say so, and test/rate-coverage.test.mjs fails the build when
306
+ * a model the plugin can actually route to lands here.
307
+ *
308
+ * @param {string} model a model id, provider name, alias, or "provider:model"
309
+ * @param {{at?: Date}} [opts] the instant to price against, for peak/off-peak
310
+ * @returns {object} the row ({input,output,cacheRead,cacheWrite}) plus `basis`,
311
+ * `peak`, and the `model` it resolved from.
312
+ */
313
+ function ratesFor(model, { at } = {}) {
175
314
  const raw = String(model || '').toLowerCase();
176
- if (!raw) return RATES.default;
315
+ const finish = (row, basis) => {
316
+ const provider = raw.indexOf('deepseek') === 0 || raw.indexOf(':deepseek') > -1
317
+ ? 'deepseek'
318
+ : raw;
319
+ const peak = isPeak(provider, at || new Date());
320
+ // Off-peak rows are half of peak by construction, but read them from the
321
+ // table rather than dividing, so a future discount that is NOT exactly half
322
+ // is expressed where the numbers live instead of in arithmetic here.
323
+ const use = !peak && row.offPeak ? { ...row, ...row.offPeak } : row;
324
+ return { ...use, basis, peak, model: raw };
325
+ };
326
+ if (!raw) return finish(RATES.default, RATE_BASIS.DEFAULT);
327
+
177
328
  // A byok model id carries its provider as a routing label:
178
329
  // "anthropic:claude-opus-4", "deepseek:deepseek-v4-flash". The label is not
179
330
  // a rate, and rating it as written fell through every prefix to
180
331
  // RATES.default — so an Opus BYOK turn was priced at Sonnet's $3/$15 against
181
332
  // the vendor's real $5/$25. 15x, on the one class whose figure can only ever
182
333
  // be an estimate, because there the vendor bills the caller and AEGIS only
183
- // relays. Try the whole id first, then the model behind the label.
334
+ // relays.
335
+ //
336
+ // Precedence is by MATCH QUALITY first and candidate second, not
337
+ // candidate-first: matching candidate-by-candidate let the label `deepseek`
338
+ // prefix-match the family row before the tail was ever considered, so a
339
+ // `deepseek:deepseek-v4-pro` turn was priced at Flash rates — the routing
340
+ // label beating the model it labels. So: try every candidate as an exact id,
341
+ // then every candidate as a prefix.
184
342
  const ids = [raw];
185
- const tail = raw.slice(raw.lastIndexOf(':') + 1);
343
+ // The routing label is separated by ':' in a byok id ("anthropic:claude-opus-4")
344
+ // and by '/' in the ids the PLATFORM advertises ("deepseek/deepseek-v4-flash"
345
+ // — see test/cli-tools.test.mjs, test/mcp-balance.test.mjs). Splitting only on
346
+ // ':' left the slash form resolving its whole string as one id, so
347
+ // "deepseek/deepseek-v4-pro" never reached the tail and prefix-matched the
348
+ // `deepseek` FAMILY row — the pro model priced at Flash rates, the same
349
+ // label-shadowing bug the ':' form had, in the spelling that is actually
350
+ // shipped.
351
+ const sep = Math.max(raw.lastIndexOf(':'), raw.lastIndexOf('/'));
352
+ const tail = raw.slice(sep + 1);
186
353
  if (tail && tail !== raw) ids.push(tail);
187
354
  for (const id of ids) {
188
- if (RATES[id]) return RATES[id];
189
- let best = null;
190
- let bestLen = 0;
355
+ if (RATES[id]) return finish(RATES[id], RATE_BASIS.EXACT);
356
+ }
357
+ let best = null;
358
+ let bestLen = 0;
359
+ for (const id of ids) {
191
360
  for (const [prefix, rates] of Object.entries(RATES)) {
192
- if (id.startsWith(prefix) && prefix.length > bestLen) {
361
+ if (prefix !== 'default' && id.startsWith(prefix) && prefix.length > bestLen) {
193
362
  best = rates;
194
363
  bestLen = prefix.length;
195
364
  }
196
365
  }
197
- if (best) return best;
198
366
  }
367
+ if (best) return finish(best, RATE_BASIS.PREFIX);
199
368
  // Longest family-key hit wins, so an overlapping pair resolves the same way
200
369
  // twice running rather than by object key order.
201
370
  let family = null;
@@ -206,13 +375,37 @@ function ratesFor(model) {
206
375
  familyLen = key.length;
207
376
  }
208
377
  }
209
- return family || RATES.default;
378
+ return finish(family || RATES.default, family ? RATE_BASIS.FAMILY : RATE_BASIS.DEFAULT);
210
379
  }
211
380
 
212
381
  /**
213
- * The four billable buckets from a wire usage object, accepting both provider
214
- * spellings. Cache fields have no Anthropic-compatible short form here because
215
- * the desktop's transport normalises them (desktop/lib/local/providers.js).
382
+ * The four billable buckets from a wire usage object, accepting every
383
+ * provider's spelling of them.
384
+ *
385
+ * ── The one thing the providers genuinely disagree about ───────────────────
386
+ *
387
+ * Cache fields are not merely spelled differently, they are MEASURED
388
+ * differently, and the difference is silent:
389
+ *
390
+ * Anthropic `input_tokens` EXCLUDES `cache_read_input_tokens` and
391
+ * `cache_creation_input_tokens` — the buckets are DISJOINT.
392
+ * OpenAI `prompt_tokens` INCLUDES
393
+ * `prompt_tokens_details.cached_tokens`.
394
+ * DeepSeek `prompt_tokens` INCLUDES `prompt_cache_hit_tokens` — the
395
+ * cached count is a SUBSET of the prompt count.
396
+ *
397
+ * Reading a subset pair as though it were disjoint double-bills every cached
398
+ * token: once at the input rate and again at the cache rate. That is the exact
399
+ * inverse of the saving caching exists to produce, and it is invisible in the
400
+ * output — the figure simply comes out larger, and never looks wrong. So the
401
+ * convention is detected from which field supplied the prompt count, and only
402
+ * the subset spellings subtract.
403
+ *
404
+ * Earlier revisions deferred this to `desktop/lib/local/providers.js`, a file
405
+ * that does not exist — so nothing normalised these fields and every DeepSeek
406
+ * turn reported `cacheRead: 0`, pricing its whole prompt at the miss rate.
407
+ * That is why the convention is resolved here, in the one module both hosts
408
+ * resolve (cli/src/deps.js), rather than in a transport either could drop.
216
409
  *
217
410
  * @param {object|null|undefined} usage
218
411
  * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number}}
@@ -223,32 +416,159 @@ function usageBuckets(usage) {
223
416
  for (const c of candidates) if (typeof c === 'number') return c;
224
417
  return 0;
225
418
  };
226
- const input = num(u.input_tokens, u.prompt_tokens, u.input);
419
+ const opt = (v) => (typeof v === 'number' ? v : undefined);
420
+
421
+ const anthropicIn = opt(u.input_tokens);
422
+ const openaiIn = opt(u.prompt_tokens);
423
+ const details = u.prompt_tokens_details;
424
+ const nested = details && typeof details === 'object' ? opt(details.cached_tokens) : undefined;
425
+ // DeepSeek's `prompt_cache_hit_tokens`, OpenAI's nested `cached_tokens`, and
426
+ // the bare `cached_tokens` some OpenAI-compatible gateways emit. All three
427
+ // are SUBSETS of the prompt count they arrive beside.
428
+ const subsetHit = num(u.prompt_cache_hit_tokens, nested, u.cached_tokens);
429
+
430
+ // Only the OpenAI/DeepSeek spelling names the cache INSIDE the prompt stat.
431
+ // The Anthropic spelling, and this file's own already-bucketed `{input,...}`
432
+ // shape (which a ledger row carries), are disjoint — subtracting there would
433
+ // understate the bill.
434
+ const subset = anthropicIn === undefined && openaiIn !== undefined;
435
+ const promptCount = subset ? openaiIn : num(anthropicIn, openaiIn, u.input);
436
+
437
+ const cacheReadRaw = num(u.cache_read_input_tokens, u.cacheRead, subsetHit);
438
+ // Clamp to the prompt it belongs to: a provider over-reporting its hit count
439
+ // must not be able to produce negative input tokens.
440
+ const cacheRead = subset ? Math.min(Math.max(0, promptCount), cacheReadRaw) : cacheReadRaw;
441
+ const cacheWrite = num(u.cache_creation_input_tokens, u.cacheWrite);
227
442
  const output = num(u.output_tokens, u.completion_tokens, u.output);
443
+ const input = subset ? Math.max(0, promptCount - cacheRead) : promptCount;
444
+
228
445
  // A stated total larger than the split means the provider counted tokens the
229
446
  // split does not name (thinking, cached reads). Attribute the remainder to
230
447
  // input rather than dropping it: dropping it would understate the bill.
231
448
  const total = num(u.total_tokens);
232
- const cacheRead = num(u.cache_read_input_tokens, u.cacheRead);
233
- const cacheWrite = num(u.cache_creation_input_tokens, u.cacheWrite);
234
449
  const accounted = input + output + cacheRead + cacheWrite;
450
+ // ── Did the source report a cache at all? ─────────────────────────────────
451
+ //
452
+ // Every `num(...)` above coerces an absent field to 0, which is right for
453
+ // arithmetic and WRONG for a claim. A provider that reports only
454
+ // `prompt_tokens` and no cache field of any spelling is not reporting a cold
455
+ // cache — it is not reporting a cache — and the two must not render the same.
456
+ // Aider does exactly this (it prints "Tokens: N sent" and no hit count), and
457
+ // reading its silence as a 0 made its prompt total the lowest of five
458
+ // harnesses when it was really a partial number. See `cacheHitRate`.
459
+ const cacheReported =
460
+ typeof u.cache_read_input_tokens === 'number'
461
+ || typeof u.cacheRead === 'number'
462
+ || typeof u.cache_creation_input_tokens === 'number'
463
+ || typeof u.cacheWrite === 'number'
464
+ || typeof u.prompt_cache_hit_tokens === 'number'
465
+ || typeof u.cached_tokens === 'number'
466
+ || typeof nested === 'number';
235
467
  return {
236
468
  input: total > accounted ? input + (total - accounted) : input,
237
469
  output,
238
470
  cacheRead,
239
471
  cacheWrite,
472
+ cacheReported,
240
473
  };
241
474
  }
242
475
 
243
- /** Dollar cost of a usage record at the given model's rates (USD, estimate). */
244
- function usageCost(usage, model = 'sonnet') {
245
- const r = ratesFor(model);
476
+ /**
477
+ * Cache hit rate for a usage record: the share of prompt tokens the provider
478
+ * actually served from its cache rather than billing at miss price.
479
+ *
480
+ * Ported from `aegiscodex-dev/src/tokens.js`. It reads through `usageBuckets`
481
+ * rather than off the raw object, which is the one deliberate difference: the
482
+ * engine's copy is handed an already-normalised record, while this module is
483
+ * also handed WIRE usage (a provider's raw response body) and ledger rows. A
484
+ * raw DeepSeek body spells the hit count `prompt_cache_hit_tokens` inside
485
+ * `prompt_tokens`; reading `usage.cacheRead` off that shape finds nothing and
486
+ * reports `pct: null` — "no cache activity" — for a turn that was almost
487
+ * entirely cached. Going through the normaliser is what makes the number the
488
+ * same on both spellings.
489
+ *
490
+ * The denominator is `input + cacheRead`, and `input` means the MISS half
491
+ * everywhere in this codebase — `usageBuckets` derives it as
492
+ * `prompt_tokens - prompt_cache_hit_tokens`, and the Anthropic spelling
493
+ * `input_tokens` already excludes cached reads by definition. Adding
494
+ * `cacheWrite` to the denominator would be wrong twice over: on Anthropic a
495
+ * written block is read back on the next turn (the same tokens counted again),
496
+ * and on DeepSeek there is no write field at all.
497
+ *
498
+ * `pct` is null — not 0 — when nothing has been billed yet, so a caller can
499
+ * tell "no cache activity recorded" apart from "everything missed". A
500
+ * hardcoded 0 in a parser once made the benchmark's "0 cache reads" column a
501
+ * measurement of our own code rather than of the cache.
502
+ *
503
+ * `reported` closes the other half of that hole, which this module shares with
504
+ * the engine and had to fix in the same commit or the two hosts would disagree.
505
+ * `usageBuckets` coerces every absent field to 0 for arithmetic, so a provider
506
+ * that reports prompt tokens and NO cache spelling of any kind came out
507
+ * `pct: 0` — "everything missed" — when the honest reading is "never said".
508
+ * Aider is that shape: it prints a sent-token count and no hit count, and its
509
+ * silence priced it as the most cache-efficient harness in the benchmark. So
510
+ * `pct` is null unless a cache field was actually present, and a caller that
511
+ * prints the rate renders an unreported one as "—".
512
+ *
513
+ * @returns {{read: number, miss: number, prompt: number, pct: number|null,
514
+ * reported: boolean}} `pct` is 0-100, or null when the source reported no
515
+ * cache field, or when no prompt tokens have been accounted.
516
+ */
517
+ function cacheHitRate(usage) {
246
518
  const u = usageBuckets(usage);
247
- const toD = (n, rate) => (n / 1_000_000) * rate;
248
- return toD(u.input, r.input)
519
+ const read = Math.max(0, u.cacheRead || 0);
520
+ const miss = Math.max(0, u.input || 0);
521
+ const prompt = read + miss;
522
+ return {
523
+ read,
524
+ miss,
525
+ prompt,
526
+ pct: u.cacheReported && prompt > 0 ? (read / prompt) * 100 : null,
527
+ reported: u.cacheReported,
528
+ };
529
+ }
530
+
531
+ /**
532
+ * Dollar cost of a usage record at the given model's rates, with the
533
+ * provenance attached.
534
+ *
535
+ * `basis === 'default'` means the model was not priced and `cost` is a
536
+ * Sonnet-class placeholder — the one state the old code could not express.
537
+ *
538
+ * `model` deliberately has NO `= 'sonnet'` default parameter, which is a
539
+ * behaviour change worth stating: the old signature was `model = 'sonnet'`, so
540
+ * `costBreakdown(u, undefined)` substituted the alias and reported
541
+ * `basis: 'exact'` — "this model's real rate" — while `costBreakdown(u, '')`
542
+ * (and `ratesFor(undefined)`) reported `basis: 'default'` — "we do not know
543
+ * this model". The two spellings produced the SAME money, because
544
+ * RATES.default and RATES.sonnet are numerically identical, but two different
545
+ * labels for the same number is the exact ambiguity this return shape exists to
546
+ * remove. So an unspecified model now flows to the default row and says so.
547
+ * The money is unchanged; only the claim about it is.
548
+ *
549
+ * @param {object} usage a wire usage object or a stored bucket row
550
+ * @param {string} model the model id that answered
551
+ * @param {{at?: Date}} [opts] the instant to price against (peak/off-peak)
552
+ * @returns {{cost: number, basis: string, peak: boolean, model: string, priced: boolean}}
553
+ */
554
+ function costBreakdown(usage, model, opts = {}) {
555
+ const r = ratesFor(model, opts);
556
+ const u = usageBuckets(usage);
557
+ const toD = (n, rate) => (Math.max(0, Number(n) || 0) / 1_000_000) * rate;
558
+ const cost = toD(u.input, r.input)
249
559
  + toD(u.output, r.output)
250
560
  + toD(u.cacheRead, r.cacheRead)
251
561
  + toD(u.cacheWrite, r.cacheWrite);
562
+ return { cost, basis: r.basis, peak: r.peak, model: r.model, priced: r.basis !== RATE_BASIS.DEFAULT };
563
+ }
564
+
565
+ /**
566
+ * Dollar cost of a usage record at the given model's rates (USD, estimate).
567
+ * See `costBreakdown` for why an unnamed model reports `default` rather than
568
+ * silently claiming Sonnet's row as an exact match.
569
+ */
570
+ function usageCost(usage, model, opts = {}) {
571
+ return costBreakdown(usage, model, opts).cost;
252
572
  }
253
573
 
254
574
  /**
@@ -274,13 +594,19 @@ function turnAccounting(usage, model, opts = {}) {
274
594
  ? opts.costUsd
275
595
  : (typeof u.costUsd === 'number' ? u.costUsd : undefined);
276
596
  if (typeof settled === 'number') {
277
- return { tokens, cost: settled, real: true, estimated: false };
597
+ // The ledger's own figure. `basis: 'settled'` rather than a table match,
598
+ // because a settled charge is a fact and a table match is a guess — and the
599
+ // pool's bill carries a margin and a prompt-cache discount this table
600
+ // cannot see, so the two must never be averaged or confused.
601
+ return { tokens, cost: settled, real: true, estimated: false, basis: 'settled', priced: true };
278
602
  }
279
- if (tokens == null) return { tokens, cost: null, real: false, estimated: false };
280
- const priced = usageCost(u, model);
281
- // A model the table cannot place is still priced at the Sonnet-class default
282
- // (ratesFor never returns nothing), so this is always an estimate.
283
- return { tokens, cost: priced, real: false, estimated: true };
603
+ if (tokens == null) return { tokens, cost: null, real: false, estimated: false, basis: null, priced: false };
604
+ const b = costBreakdown(u, model, opts);
605
+ // A model the table cannot place still yields a number (ratesFor never
606
+ // returns nothing), so this is always an estimate — but `priced: false` says
607
+ // the figure is a placeholder rather than this model's rate, so the caller
608
+ // can label it instead of printing it as though it had been measured.
609
+ return { tokens, cost: b.cost, real: false, estimated: true, basis: b.basis, priced: b.priced };
284
610
  }
285
611
 
286
612
  /**
@@ -585,10 +911,15 @@ function fmtCost(cost, real) {
585
911
  if (typeof module !== 'undefined' && module.exports) {
586
912
  module.exports = {
587
913
  RATES,
914
+ RATE_BASIS,
915
+ UNPRICED_BY_DESIGN,
916
+ isPeak,
588
917
  usageTokens,
589
918
  ratesFor,
590
919
  usageBuckets,
920
+ cacheHitRate,
591
921
  usageCost,
922
+ costBreakdown,
592
923
  turnAccounting,
593
924
  estimateTokens,
594
925
  estimatedBuckets,