aegiscode 6.8.3 → 6.8.5

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 (53) hide show
  1. package/README.md +2 -2
  2. package/bin/aegiscode.js +35 -5
  3. package/package.json +1 -6
  4. package/scripts/predist.mjs +99 -0
  5. package/src/agents.js +1 -1
  6. package/src/app.js +41 -9
  7. package/src/caps.js +1 -1
  8. package/src/chatflow.js +182 -34
  9. package/src/checkpoint.js +1 -1
  10. package/src/clipboard.js +1 -1
  11. package/src/commands.js +158 -21
  12. package/src/config.js +2 -2
  13. package/src/deps.js +2 -1
  14. package/src/devrun.js +1 -1
  15. package/src/diff.js +1 -1
  16. package/src/events.js +38 -15
  17. package/src/export.js +1 -1
  18. package/src/fuzzy.js +1 -1
  19. package/src/history.js +3 -3
  20. package/src/init.js +1 -1
  21. package/src/input.js +1 -1
  22. package/src/keys.js +1 -1
  23. package/src/markdown.js +2 -2
  24. package/src/mcp.js +683 -0
  25. package/src/overlays.js +2 -2
  26. package/src/panels.js +52 -19
  27. package/src/permissions.js +2 -2
  28. package/src/render.js +2 -2
  29. package/src/screen.js +133 -8
  30. package/src/screens.js +1 -1
  31. package/src/summarize.js +1 -1
  32. package/src/system.js +2 -2
  33. package/src/theme.js +6 -6
  34. package/src/title.js +217 -0
  35. package/src/tokens.js +75 -96
  36. package/src/update.js +75 -1
  37. package/vendor/desktop/lib/local/agents.js +1 -1
  38. package/vendor/desktop/lib/local/autonomous.js +1 -1
  39. package/vendor/desktop/lib/local/engine.js +32 -8
  40. package/vendor/desktop/lib/local/git-scope.js +1 -1
  41. package/vendor/desktop/lib/local/prompt.js +3 -3
  42. package/vendor/desktop/lib/local/queue.js +2 -2
  43. package/vendor/desktop/lib/local/shell.js +1 -1
  44. package/vendor/desktop/lib/local/tools.js +2 -2
  45. package/vendor/desktop/lib/local/turn-guard.js +1 -1
  46. package/vendor/desktop/lib/local/worktree-lock.js +1 -1
  47. package/vendor/desktop/lib/settings.js +67 -0
  48. package/vendor/desktop/renderer/usage.js +377 -46
  49. package/vendor/hosts/install.js +638 -0
  50. package/vendor/hosts/openai-shim.js +419 -0
  51. package/vendor/hosts/spec.js +164 -0
  52. package/vendor/hosts/targets.js +346 -0
  53. package/vendor/mcp/server.js +186 -0
@@ -68,11 +68,11 @@ function usageTokens(usage) {
68
68
 
69
69
  /**
70
70
  * Rough token count for text the wire never measured — a direct port of the
71
- * CLI's own estimator (`aegiscodex-dev/src/tokens.js estimateTokens`), and the
71
+ * CLI's own estimator (the upstream engine's estimateTokens), and the
72
72
  * reason its session total is MONOTONIC.
73
73
  *
74
74
  * This is the whole difference being fixed. The CLI's `appendHistory`
75
- * (aegiscodex-dev/src/history.js) writes a `tokens` object for EVERY finished
75
+ * (the upstream engine's history module) writes a `tokens` object for EVERY finished
76
76
  * exchange: `{input, output, cacheRead, cacheWrite, real: true}` when the wire
77
77
  * reported usage, and `{input: estimateTokens(prompt), output:
78
78
  * estimateTokens(reply), real: false}` when it did not. `real` is a FLAG, not a
@@ -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 the upstream engine reference. 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
  /**
@@ -268,19 +588,25 @@ function turnAccounting(usage, model, opts = {}) {
268
588
  const tokens = usageTokens(usage);
269
589
  const u = usage && typeof usage === 'object' ? usage : {};
270
590
  // The settled charge can arrive either on the response or folded into the
271
- // usage object — aegiscodex-dev/src/main.js does the latter
591
+ // usage object — the upstream engine does the latter
272
592
  // (`{ ...result.usage, costUsd: result.costUsd }`), so both are accepted.
273
593
  const settled = typeof opts.costUsd === 'number'
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
  /**
@@ -377,7 +703,7 @@ function rollTurn(roll, usage, opts = {}) {
377
703
  if (turn.tokens == null) {
378
704
  // No reported usage. The CLI does not let such a turn vanish from the
379
705
  // total: `appendHistory` estimates it from the text and marks it
380
- // `real: false` (aegiscodex-dev/src/history.js), and
706
+ // `real: false` (the upstream engine's history module), and
381
707
  // `aggregateSessionUsage` then adds it like any other row. Folding the same
382
708
  // estimate here is what makes the live roll and the rebuilt roll the same
383
709
  // number, and what stops the total standing still on exactly the turns the
@@ -446,7 +772,7 @@ function rollMessages(messages) {
446
772
  * The ledger row one finished dispatch must carry into the shared session
447
773
  * store, so the rolling total can be REBUILT when the thread is reopened —
448
774
  * the desktop's counterpart of the CLI's `appendHistory`
449
- * (aegiscodex-dev/src/history.js:36).
775
+ * (the upstream engine's history module).
450
776
  *
451
777
  * One authority for the row, on purpose. The CLI writes a `tokens` object for
452
778
  * EVERY exchange and skips none:
@@ -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,