@toddzheng024/dscode-bundle 0.7.22 → 0.7.24

package/plugins/session-metrics/turns.mjs

@@ -0,0 +1,134 @@
+// Per-turn cost attribution and the session budget gate. The footer reports the
+// whole session's spend and /usage reports tokens per turn; these functions
+// answer what neither does with that ledger: which turn spent the money, so the
+// footer can show the last completed turn and /usage can price each one.
+
+/**
+ * Turn windows from the session's own events. `turn/start` opens a window and
+ * `turn/end` closes it; an unterminated turn stays open to `Infinity` so the
+ * turn in flight still attributes its settled calls. Windows come back in
+ * ascending start order, which the attribution lookup below depends on.
+ */
+export function turnWindows(events = []) {
+  const open = new Map();
+  const windows = [];
+  for (const event of events) {
+    const turn = event.data?.turn;
+    // A boundary without a time cannot place a window or a call inside one. It
+    // is skipped rather than stored: a NaN edge would make the ascending-search
+    // contract false and silently orphan every call of that turn.
+    if (!Number.isFinite(turn) || !Number.isFinite(event.time)) continue;
+    if (event.type === 'turn/start') {
+      const existing = open.get(turn);
+      // A resumed turn can re-emit its start; keep the earliest boundary.
+      open.set(turn, existing === undefined ? event.time : Math.min(existing, event.time));
+    } else if (event.type === 'turn/end') {
+      const start = open.get(turn);
+      if (start === undefined) continue;
+      open.delete(turn);
+      windows.push({ turn, start, end: event.time });
+    }
+  }
+  for (const [turn, start] of open) windows.push({ turn, start, end: Infinity });
+  return windows.sort((left, right) => left.start - right.start || left.turn - right.turn);
+}
+
+/**
+ * The clauses a call is priced against: each turn's window, with an open turn
+ * (no `turn/end`) bounded by the next turn's start. An interrupted turn must not
+ * swallow every later turn, while the turn genuinely in flight keeps running to
+ * `Infinity`. Satisfies {@link attributeCostByTurn}'s ascending-start contract.
+ */
+export function turnBounds(events = []) {
+  return turnWindows(events).map((window, index, windows) => ({
+    turn: window.turn,
+    start: window.start,
+    // Math.max keeps the window non-inverted even for a log whose timestamps
+    // are out of order; an inverted bound would break the ascending search.
+    end: window.end === Infinity && index + 1 < windows.length ? Math.max(window.start, windows[index + 1].start) : window.end,
+  }));
+}
+
+/**
+ * The window containing `time`, by binary search over the ascending bounds. The
+ * index is the FIRST window starting after `time`, so the one before it is the
+ * only candidate that can contain it; `-1` means no turn was running.
+ * @param bounds - ascending {@link turnBounds} rows.
+ * @param time - the call's start time (`time` prices the call, so it is also when the turn ran).
+ * @returns the bounds index, or -1 when `time` falls in no window.
+ */
+export function turnAt(bounds, time) {
+  let low = 0, high = bounds.length;
+  while (low < high) {
+    const mid = (low + high) >> 1;
+    if (bounds[mid].start <= time) low = mid + 1;
+    else high = mid;
+  }
+  const candidate = bounds[low - 1];
+  return candidate !== undefined && time <= candidate.end ? low - 1 : -1;
+}
+
+/**
+ * Cost and call count per turn. Roughly O(calls × log turns), so the footer can
+ * ask for the last turn once a second. A call is attributed by its start time,
+ * and a call outside every window (before the first `turn/start`, in a gap
+ * between two turns, or a backfilled row without one) is reported under
+ * `unattributed` rather than dropped.
+ * @param rows - ledger rows (`{ kind, time, cost, purpose }`).
+ * @param events - the session's events, for the turn windows.
+ * @returns One bucket per turn, plus `lastTurn` (the newest turn that is no
+ *   longer running, undefined while none has stopped), the `unattributed` total
+ *   and whether any of it was unpriceable. A turn that never emitted `turn/end`
+ *   still counts as stopped once the next turn opens its window.
+ */
+export function attributeCostByTurn(rows = [], events = []) {
+  const bounds = turnBounds(events);
+  const turns = bounds.map(bound => ({ turn: bound.turn, cost: 0, calls: 0, unknown: false }));
+  let unattributed = 0;
+  let unattributedUnknown = false;
+  for (const row of rows ?? []) {
+    if (row?.kind !== 'end') continue;
+    const at = turnAt(bounds, row.time);
+    if (at === -1) {
+      // Outside every window the spend still exists: an unpriceable row must be
+      // visible as such rather than counted as nothing.
+      if (Number.isFinite(row.cost)) unattributed += row.cost;
+      else unattributedUnknown = true;
+      continue;
+    }
+    turns[at].calls += 1;
+    if (Number.isFinite(row.cost)) turns[at].cost += row.cost;
+    else turns[at].unknown = true;
+  }
+  let lastTurn;
+  for (let index = bounds.length - 1; index >= 0; index -= 1) {
+    if (bounds[index].end !== Infinity) { lastTurn = turns[index]; break; }
+  }
+  return { turns, lastTurn, unattributed, unattributedUnknown };
+}
+
+/**
+ * The budget gate's verdict. A missing or non-positive limit means no budget is
+ * set, so the gate never fires and the footer shows no budget slot. `warn` is
+ * the alerting share; `over` means the next prompt would spend past the limit.
+ */
+export function evaluateBudget(spent, limit, options = {}) {
+  const warnPercent = Number.isFinite(options.warnPercent) ? options.warnPercent : 80
+  if (!Number.isFinite(limit) || limit <= 0) return { state: 'unset', limit: null, spent, ratio: null, percent: null, warnPercent }
+  const safeSpent = Number.isFinite(spent) ? spent : 0
+  const ratio = safeSpent / limit
+  return {
+    state: ratio >= 1 ? 'over' : ratio * 100 >= warnPercent ? 'warn' : 'ok',
+    limit, spent: safeSpent, ratio,
+    percent: Math.round(ratio * 100),
+    warnPercent,
+  }
+}
+
+/** Parse the `DSCODE_SESSION_BUDGET_USD`-style value; anything else is no budget. */
+export function parseBudget(value) {
+  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? value : null
+  if (typeof value !== 'string') return null
+  const parsed = Number.parseFloat(value.trim())
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}

package/plugins/session-metrics/view.mjs

@@ -4,7 +4,7 @@ import { estimateCost, peakEmoji } from './pricing.mjs';
 import { balanceNow, trustedNow } from './balance.mjs';
 import { grokSubscriptionNow } from '../grok/billing.mjs';
 import { sessionAverageTps } from './rate.mjs';
-import { providerOfHeader } from '../providers/catalog.mjs';
+import { attributeCostByTurn, evaluateBudget, parseBudget } from './turns.mjs';
 let source;
 export function setMetricSource(next) { source = next; return () => { if (source === next) source = undefined; }; }
 export function summarize(rows, events = [], corrupt = false) {
@@ -43,7 +43,29 @@ export function summarize(rows, events = [], corrupt = false) {
     // OpenRouter reports cache reads only when there are some: a missing count is zero, not unknown.
     input += total; hit += u.cacheReadTokens ?? 0;
   }
-  return { cost, unknown, calls, pending, cache: input > 0 && !cacheUnknown ? Math.min(100, hit / input * 100) : null };
+  // Per-turn attribution needs the ledger's own rows (the backfilled history has
+  // no turn boundary), so it reads them directly instead of the merged map.
+  const attribution = attributeCostByTurn(rows, events);
+  return {
+    cost, unknown, calls, pending,
+    cache: input > 0 && !cacheUnknown ? Math.min(100, hit / input * 100) : null,
+    turns: attribution.turns,
+    lastTurn: attribution.lastTurn,
+    unattributed: attribution.unattributed,
+  };
+}
+
+/**
+ * Per-turn cost for one live session, straight from its ledger, keyed by the
+ * durable turn number. The /usage panel prices its turns with this: the token
+ * meter says what each turn billed, this says what it cost.
+ * @param id - the session id.
+ * @param events - the session's durable events, for the turn windows.
+ * @returns `{ turn, cost, calls, unknown }` per completed or running turn.
+ */
+export function turnCostsFor(id, events = []) {
+  const entries = id && process.env.DSH_HOME ? readMetrics(process.env.DSH_HOME, id).rows : [];
+  return attributeCostByTurn(entries, events).turns;
 }
 /**
  * Terminal columns of a string: East Asian wide characters (such as the cache label's
@@ -113,50 +135,77 @@ function figure(text, width) {
   return padding > 0 ? ' '.repeat(padding) + text : text;
 }
 
-export function formatFooter(metrics, context, columns = 80, rates, locale = 'en', header = '', provider = providerOfHeader(header) ?? 'deepseek-official') {
+export function formatFooter(metrics, context, columns = 80, rates, locale = 'en', provider = 'deepseek-official') {
   const label = key => t(locale, key);
   const ctx = figure(Number.isFinite(context) ? `${Math.round(context)}%` : '--', FIGURE.percent);
   const cache = figure(metrics.cache === null ? '--' : `${metrics.cache.toFixed(1)}%`, FIGURE.share);
-  // The balance belongs to the provider the header names; only DeepSeek's official route bills by a peak window.
+  // The balance belongs to the provider serving the route; only DeepSeek's official one bills by a peak window.
   const balance = balanceNow(provider);
   const spend = metrics.unknown && metrics.cost === 0 ? '--' : `$${metrics.cost.toFixed(2)}${metrics.unknown ? '+' : ''}${metrics.pending ? '…' : ''}`;
-  // The money pair is the one live figure left unpadded: its digits cross a
-  // column a handful of times per session, and reserving those columns would
-  // evict a per-second figure at the widths the footer actually runs at.
+  // The money is the one live figure whose digits are not reserved: they cross a
+  // column a handful of times per session, and reserving them would evict a
+  // per-second figure at the widths the footer actually runs at. A balance the
+  // provider cannot report is left out instead of parked as `$--`.
   const dollars = provider === 'grok' ? grokFooterFact(grokSubscriptionNow(), locale)
-    : `${spend} / ${balance === null ? '$--' : '$' + balance.toFixed(2)}${provider === 'deepseek-official' ? ' ' + peakEmoji(trustedNow()) : ''}`;
+    : spend + (balance === null ? '' : ' / $' + balance.toFixed(2)) + (provider === 'deepseek-official' ? ' ' + peakEmoji(trustedNow()) : '');
+  // The budget slot rides the money figure: it answers "how much of the session's
+  // limit is spent", which is a fact about the cost, not a second cost. A session
+  // with no limit renders exactly as before, so the footer only grows by choice.
+  const budget = metrics.budget;
+  const budgeted = budget === undefined || budget.limit === null ? ''
+    : `/${budget.limit.toFixed(2)}${budget.state === 'over' ? '⚠!' : budget.state === 'warn' ? '⚠' : ''}`;
+  const money = dollars + budgeted;
+  // The last completed turn is the one figure the whole-session total cannot
+  // give: `$1.23 / $9.86 · #12 $0.04` reads "the session so far, of which the
+  // last turn cost this". `+` marks a turn whose settled calls were not all
+  // priceable, the same mark the total uses.
+  const turn = metrics.lastTurn === undefined || !Number.isFinite(metrics.lastTurn.cost) ? ''
+    : `#${metrics.lastTurn.turn} $${metrics.lastTurn.cost.toFixed(2)}${metrics.lastTurn.unknown ? '+' : ''}`;
+  // Every figure reads value first and carries its own short qualifier, so the
+  // cluster stays scannable without a `label:` prefix in front of each number.
   const base = rates ? [
-    `${label('footer.current')}: ${figure(Number.isFinite(rates.current) ? '~' + rates.current.toFixed(1) : '--', FIGURE.rate)} tps`,
-    `${label('footer.average')}: ${figure(Number.isFinite(rates.average) ? rates.average.toFixed(1) : '--', FIGURE.rate)} tps`,
-    `${label('footer.context')}: ${ctx}`, dollars, `${label('footer.cache')}: ${cache}`,
-  ] : [`${label('footer.context')}: ${ctx}`, dollars, `${label('footer.cache')}: ${cache}`];
-  // Narrow terminals shed the quietest figures first: average, current, context. The
-  // model header then falls back to its bare `model @ effort` form, then context goes,
-  // and only then the header itself — the running cost is the last thing standing.
-  const drops = rates ? [1, 0, 2, 4] : [0, 2];
-  const offset = header === '' ? 0 : 1;
-  const parts = header === '' ? base : [header, ...base];
-  const short = header.replace(/^[^:]+: /, '');
-  const heads = header === '' ? [''] : short === header ? [header] : [header, short];
-  const render = ({ omit, head }) => parts
-    .map((part, index) => (index === 0 && header !== '' ? head : part))
-    .filter((part, index) => part !== '' && !omit.has(index))
-    .join(' | ');
+    `${figure(Number.isFinite(rates.current) ? '~' + rates.current.toFixed(1) : '--', FIGURE.rate)} tps`,
+    `${figure(Number.isFinite(rates.average) ? rates.average.toFixed(1) : '--', FIGURE.rate)} tps ${label('footer.average')}`,
+    `${ctx} ${label('footer.context')}`, money, `${cache} ${label('footer.cache')}`,
+  ] : [`${ctx} ${label('footer.context')}`, money, `${cache} ${label('footer.cache')}`];
+  // The slot is reserved even when no turn has cost anything yet: the drop
+  // ladder's indices are fixed against this array, and an unfilled slot renders
+  // as '' (skipped by `render`) exactly like the absent figure would.
+  base.splice(rates ? 3 : 1, 0, turn);
+  // Narrow terminals shed the quietest figures first: the last turn, then
+  // average, current and context, and only then the cache. The running cost is
+  // the last thing standing, and its slot is index 4 (or 2 without rates) now
+  // that the turn slot holds index 3 (or 1) open.
+  const drops = rates ? [3, 1, 0, 2, 5, 4] : [1, 0, 3, 2];
+  const render = omit => base.filter((part, index) => part !== '' && !omit.has(index)).join(' · ');
   for (let dropped = 0; dropped <= drops.length; dropped++) {
-    const omit = new Set(drops.slice(0, dropped).map(index => index + offset));
-    for (const head of heads) {
-      const value = render({ omit, head });
-      if (displayWidth(value) <= columns) return value;
-    }
+    const value = render(new Set(drops.slice(0, dropped)));
+    if (displayWidth(value) <= columns) return value;
   }
-  const floor = render({ omit: new Set(drops.map(index => index + offset)), head: '' });
+  const floor = render(new Set(drops));
   let clipped = '';
   for (const char of floor) { if (displayWidth(clipped + char) > columns) break; clipped += char; }
   return clipped;
 }
+/**
+ * The session's recorded spend and whether any of it is unpriceable, for a host
+ * that must decide something (the budget gate) rather than only render it. Same
+ * ledger and same rules as {@link footerFor}, so the figure the gate compares
+ * and the figure the footer shows can never disagree.
+ */
+export function sessionSpend(id) {
+  try {
+    const ledger = id && process.env.DSH_HOME ? readMetrics(process.env.DSH_HOME, id) : { rows: [], corrupt: false };
+    const data = id ? source?.(id) : undefined;
+    const summary = summarize(ledger.rows, data?.events ?? [], ledger.corrupt);
+    return { cost: summary.cost, unknown: summary.unknown, pending: summary.pending };
+  } catch { return { cost: 0, unknown: true, pending: 0 }; }
+}
+
 /** Per-events memo: the status line renders up to once a second, and summarize/average are O(events). */
 const footerCache = new WeakMap();
-export function footerFor(id, stats, columns, header = '', locale = 'en') {
+export function footerFor(id, stats, columns, provider = 'deepseek-official', locale = 'en') {
+  const limit = parseBudget(process.env.DSCODE_SESSION_BUDGET_USD);
   try {
     const data = id ? source?.(id) : undefined;
     const ledger = id && process.env.DSH_HOME ? readMetrics(process.env.DSH_HOME, id) : { rows: [], corrupt: false };
@@ -170,6 +219,9 @@ export function footerFor(id, stats, columns, header = '', locale = 'en') {
     const capacity = data?.capacity ?? stats.contextWindow;
     const average = fresh ? hit.average : sessionAverageTps(events);
     if (events.length > 0 && !fresh) footerCache.set(events, { key: ledger.rows, length: events.length, tail, summary, average });
-    return formatFooter(summary, Number.isFinite(used) && capacity > 0 ? used / capacity * 100 : undefined, columns, { current: data?.currentTps, average }, locale, header);
-  } catch { return formatFooter({ cost: 0, unknown: true, cache: null }, undefined, columns, { current: null, average: null }, locale, header); }
+    // The budget comes from the environment for this process only: it is a
+    // per-machine spending guard, not a session property worth persisting.
+    const budget = limit === null ? undefined : evaluateBudget(summary.cost, limit);
+    return formatFooter({ ...summary, ...(budget === undefined ? {} : { budget }) }, Number.isFinite(used) && capacity > 0 ? used / capacity * 100 : undefined, columns, { current: data?.currentTps, average }, locale, provider);
+  } catch { return formatFooter({ cost: 0, unknown: true, cache: null }, undefined, columns, { current: null, average: null }, locale, provider); }
 }