tinywebui 0.1.0

package/public/panels/usage.js

@@ -0,0 +1,474 @@
+/**
+ * Token usage panel: LLM name, tokens in/out/cached, and a drill-down bar
+ * chart -- years, click a year for its months, click a month for its days.
+ * The server hands back one row per calendar day (store.usageRollup());
+ * everything coarser than a day is folded client-side from that, since a
+ * year of daily rows is cheap to carry but expensive to re-derive per click.
+ */
+import { $, el } from '../core/dom.js';
+import { api } from '../core/api.js';
+
+let days = []; // raw daily rows from /api/usage
+let path = []; // drill-down breadcrumb, e.g. ['2026'] or ['2026', '2026-03']
+let statistics = null;
+// The top-level filter: '' is everything, else JSON of { model, provider? }.
+let selected = '';
+let targets = [];
+let usageRequest = 0;
+
+const fmt = (n) => n.toLocaleString();
+
+// Assigned the first time each model name is seen and kept for the rest of
+// the session, so a model's color stays the same whether you're looking at
+// "all time" or drilled into a single day -- switching levels would
+// otherwise reshuffle which color means which model.
+const MODEL_PALETTE = ['--accent', '--tool', '--err', '--muted', '--faint'];
+const modelColors = new Map();
+function colorForModel(model) {
+  if (!modelColors.has(model)) modelColors.set(model, MODEL_PALETTE[modelColors.size % MODEL_PALETTE.length]);
+  return `var(${modelColors.get(model)})`;
+}
+
+function sumModels(rows) {
+  const totals = new Map();
+  for (const row of rows) {
+    for (const m of row.models) {
+      if (!totals.has(m.model)) totals.set(m.model, { model: m.model, in: 0, out: 0, cached: 0 });
+      const t = totals.get(m.model);
+      t.in += m.in; t.out += m.out; t.cached += m.cached;
+    }
+  }
+  return [...totals.values()].sort((a, b) => b.in + b.out - (a.in + a.out));
+}
+
+/** Groups daily rows by year, or by month within a chosen year. */
+function bucket(rows, level) {
+  const groups = new Map();
+  for (const row of rows) {
+    const key = level === 'year' ? row.day.slice(0, 4) : row.day.slice(0, 7);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(row);
+  }
+  return [...groups.entries()]
+    .map(([key, rows]) => {
+      const models = sumModels(rows);
+      const total = models.reduce((n, m) => n + m.in + m.out, 0);
+      return { key, rows, models, total };
+    })
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+function render() {
+  renderCostStatistics(statistics);
+  renderModelFilter();
+  if (!days.length) renderDistribution([]);
+  if (!days.length) {
+    $('usageStats').innerHTML = '<div class="empty">no usage recorded yet</div>';
+    $('usageModels').innerHTML = '';
+    $('usageBars').innerHTML = '';
+    $('usageRange').textContent = '';
+    return;
+  }
+
+  const level = path.length === 0 ? 'year' : path.length === 1 ? 'month' : 'day';
+  const scoped = (path.length === 0 ? days : days.filter((d) => d.day.startsWith(path[path.length - 1])))
+    .map((d) => {
+      const models = d.models;
+      return { ...d, models, in: models.reduce((n,m) => n + m.in, 0), out: models.reduce((n,m) => n + m.out, 0) };
+    });
+  renderDistribution(scoped);
+
+  const models = sumModels(scoped);
+  renderTiles(models);
+  renderModelSplit(models);
+  renderBreadcrumb();
+  renderBars(scoped, level, models);
+}
+
+/** Stat tiles: totals for whatever is currently in view. */
+function renderTiles(models) {
+  const totalIn = models.reduce((n, m) => n + m.in, 0);
+  const totalOut = models.reduce((n, m) => n + m.out, 0);
+  const totalCached = models.reduce((n, m) => n + m.cached, 0);
+
+  const stats = $('usageStats');
+  stats.innerHTML = '';
+  const tile = (label, value) => {
+    const box = el('div');
+    const l = el('label');
+    l.textContent = label;
+    const v = el('div', 'usage-stat-value');
+    v.textContent = value;
+    box.append(l, v);
+    return box;
+  };
+  stats.append(
+    tile('tokens in', fmt(totalIn)),
+    tile('tokens out', fmt(totalOut)),
+    tile('cached', fmt(totalCached))
+  );
+}
+
+/**
+ * Per-model breakdown, as its own list rather than crammed into a stat
+ * tile: a model name plus three counts doesn't fit next to "584,746" at
+ * the same width, and comma-joining every model into one string just wraps
+ * wherever it wraps, with no way to see a single model's in/out split.
+ */
+function renderModelSplit(models) {
+  const modelsBox = $('usageModels');
+  modelsBox.innerHTML = '';
+  if (models.length) {
+    // `cached` is a subset of `in` (a cache hit still counts as an input
+    // token), not a third bucket alongside it -- the API reports it that way
+    // too. So each bar is fresh-in + cached-in + out, in that stacking order.
+    // The bar itself is always full width: how one model's total compares to
+    // another's is already in the numbers (and in the totals below), and
+    // scaling bar length to that on top just makes small models unreadably
+    // thin. What the bar is for here is one model's own in/cached/out split.
+    for (const m of models) {
+      const row = el('div', 'usage-model-row');
+      const name = el('span', 'usage-model-name');
+      name.textContent = m.model;
+      name.title = m.model;
+      const total = m.in + m.out;
+      const cachedIn = Math.min(m.cached, m.in);
+      const freshIn = m.in - cachedIn;
+      const track = el('span', 'usage-model-track');
+      const bar = el('span', 'usage-model-bar');
+      for (const [cls, count] of [['fresh', freshIn], ['cached', cachedIn], ['out', m.out]]) {
+        if (!count) continue;
+        const seg = el('span', `usage-model-seg ${cls}`);
+        seg.style.width = `${(count / total) * 100}%`;
+        bar.appendChild(seg);
+      }
+      track.appendChild(bar);
+      const counts = el('span', 'usage-model-counts');
+      counts.textContent = `${fmt(m.in)} in · ${fmt(m.out)} out${m.cached ? ` · ${fmt(m.cached)} cached` : ''}`;
+      row.append(name, track, counts);
+      modelsBox.appendChild(row);
+    }
+    const legend = el('div', 'usage-model-legend');
+    for (const [cls, label] of [['fresh', 'in'], ['cached', 'cached'], ['out', 'out']]) {
+      const item = el('span', 'usage-model-legend-item');
+      item.append(el('span', `usage-model-swatch ${cls}`), document.createTextNode(label));
+      legend.appendChild(item);
+    }
+    modelsBox.appendChild(legend);
+  }
+}
+
+function renderBreadcrumb() {
+  const crumbs = ['all time', ...path];
+  $('usageRange').innerHTML = '';
+  crumbs.forEach((label, i) => {
+    if (i > 0) $('usageRange').appendChild(document.createTextNode(' / '));
+    const a = el('a');
+    a.href = '#';
+    a.textContent = label;
+    a.onclick = (e) => { e.preventDefault(); path = path.slice(0, i); render(); };
+    $('usageRange').appendChild(a);
+  });
+}
+
+/**
+ * Bars: years, or months in a year, or individual days. This is the one
+ * place bar *length* means "more tokens than that other bar" -- so this is
+ * also where the per-model split belongs, as colored segments inside each
+ * bar, rather than on the fixed-width rows above.
+ */
+function renderBars(scoped, level, models) {
+  const box = $('usageBars');
+  box.innerHTML = '';
+  const buckets = level === 'day'
+    ? scoped.map((d) => ({ key: d.day, rows: [d], models: sumModels([d]), total: d.in + d.out })).sort((a, b) => a.key.localeCompare(b.key))
+    : bucket(scoped, level);
+  if (!buckets.length) {
+    box.innerHTML = '<div class="empty">nothing here</div>';
+    return;
+  }
+  const max = Math.max(...buckets.map((b) => b.total), 1);
+  for (const b of buckets) {
+    const drillable = path.length < 3;
+    const row = el(drillable ? 'button' : 'div', 'usage-bar-row');
+    if (drillable) row.type = 'button';
+    const label = el('span', 'usage-bar-label');
+    label.textContent = level === 'day' ? b.key.slice(8) : (level === 'year' ? b.key : b.key.slice(5));
+    const track = el('span', 'usage-bar-track');
+    const fill = el('span', 'usage-bar-fill');
+    fill.style.width = `${Math.max((b.total / max) * 100, 2)}%`;
+    for (const m of b.models) {
+      if (!m.in && !m.out) continue;
+      const seg = el('span', 'usage-bar-seg');
+      seg.style.width = `${((m.in + m.out) / b.total) * 100}%`;
+      seg.style.background = colorForModel(m.model);
+      fill.appendChild(seg);
+    }
+    track.appendChild(fill);
+    const count = el('span', 'usage-bar-count');
+    count.textContent = fmt(b.total);
+    row.append(label, track, count);
+    if (drillable) {
+      row.classList.add('clickable');
+      row.setAttribute('aria-label', `Show ${b.key} usage details`);
+      row.onclick = () => { path = [...path, b.key]; render(); };
+    }
+    box.appendChild(row);
+  }
+  if (models.length > 1) {
+    const legend = el('div', 'usage-model-legend');
+    for (const m of models) {
+      const item = el('span', 'usage-model-legend-item');
+      const swatch = el('span', 'usage-model-swatch');
+      swatch.style.background = colorForModel(m.model);
+      item.append(swatch, document.createTextNode(m.model));
+      legend.appendChild(item);
+    }
+    box.appendChild(legend);
+  }
+}
+
+const costFmt = (value) => value == null ? 'not reported' : `$${Number(value).toFixed(6)}`;
+
+// Ordered like the server's MISS: the first is the one that's ours to fix.
+const MISS_LABELS = [
+  ['prefix', 'prefix changed', 'we altered something already sent; worth investigating'],
+  ['switch', 'provider switched', 'a different upstream served it, with its own cache'],
+  ['expired', 'expired', 'more than 5 minutes idle since the previous request'],
+  ['stub', 'result stubbed', 'a large tool result switched to its stub after its turn, as planned'],
+  ['provider', 'provider-side', 'same prefix, same upstream, in time, and it still missed']
+];
+const missTotal = (cache) => Object.values(cache.misses || {}).reduce((n, v) => n + v, 0);
+
+/** The cache misses section: how many, and one bar per cause. */
+function renderMisses(cache) {
+  const box = $('statisticsMisses');
+  const head = $('statisticsMissesSummary');
+  if (!box || !head) return;
+  box.replaceChildren();
+  if (!cache?.judged) {
+    head.textContent = '';
+    box.appendChild(el('div', 'empty')).textContent = 'No requests to compare yet: a chat needs two rounds from a provider that reports cache figures.';
+    return;
+  }
+  head.textContent = `${fmt(missTotal(cache))} of ${fmt(cache.judged)} comparable requests missed`;
+  const max = Math.max(...MISS_LABELS.map(([k]) => cache.misses[k] || 0), 1);
+  for (const [key, label, hint] of MISS_LABELS) {
+    const n = cache.misses[key] || 0;
+    const row = el('div', 'statistics-tool-row');
+    const name = el('span', 'statistics-tool-name'); name.textContent = label;
+    const track = el('span', 'statistics-tool-track');
+    const bar = el('span', 'statistics-tool-bar');
+    bar.style.width = `${(n / max) * 100}%`;
+    track.appendChild(bar);
+    const count = el('span', 'statistics-tool-count'); count.textContent = fmt(n);
+    row.append(name, track, count);
+    const why = el('div', 'statistics-miss-hint'); why.textContent = hint;
+    box.append(row, why);
+  }
+}
+
+function renderCostStatistics(stats) {
+  const summary = $('statisticsSummary');
+  const coverage = $('statisticsCoverage');
+  const modelsBox = $('statisticsCosts');
+  const toolsBox = $('statisticsTools');
+  if (!summary || !coverage || !modelsBox) return;
+  summary.replaceChildren(); modelsBox.replaceChildren();
+  if (toolsBox) toolsBox.replaceChildren();
+  renderMisses(stats?.rounds ? stats.cache : null);
+  if (!stats || !stats.rounds) {
+    summary.appendChild(el('div', 'empty')).textContent = 'No model usage recorded yet.';
+    coverage.textContent = '';
+    if (toolsBox) toolsBox.appendChild(el('div', 'empty')).textContent = 'No tool calls recorded yet.';
+    return;
+  }
+  // `sub` is a short second line under the value; `hint` is the hover detail,
+  // so the explanations stay available without a paragraph under the tiles.
+  const tile = (label, value, sub = '', hint = '') => {
+    const box = el('div');
+    const name = el('label'); name.textContent = label;
+    const amount = el('div', 'usage-stat-value'); amount.textContent = value;
+    box.append(name, amount);
+    if (sub) box.appendChild(el('div', 'usage-stat-sub')).textContent = sub;
+    if (hint) box.title = hint;
+    return box;
+  };
+  const cache = stats.cache || {};
+  const pct = (share) => `${(share * 100).toFixed(1)}%`;
+  const rates = (cache.rates || []).map((r) => `${r.model}${r.provider ? ` @ ${r.provider}` : ''}: `
+    + `$${(r.full * 1e6).toFixed(3)}/M full, $${(r.cache * 1e6).toFixed(3)}/M cached`).join('\n');
+  summary.append(
+    tile('cache saved', costFmt(cache.saved),
+      cache.savedShare == null ? '' : `${pct(cache.savedShare)} off the bill`,
+      'Share of what these requests would have cost with no cache. Where the provider does not report it, '
+        + 'it is worked out from the input cost it charged at different cache ratios.' + (rates ? `\n\n${rates}` : '')),
+    tile('cache hit share', cache.hitShare == null ? '—' : pct(cache.hitShare),
+      cache.reportedRounds ? `${fmt(cache.cached)} of ${fmt(cache.input)} input` : '',
+      'Input tokens read from cache, over requests whose provider reports cache figures.'),
+    tile('reported cost', costFmt(stats.reportedCost)),
+    tile('average model request', costFmt(stats.averageRoundCost)),
+    tile('average complete answer', costFmt(stats.averageAnswerCost), '', 'All model requests of the answer, tool-work rounds included.'),
+    tile('average answer tokens (all rounds)', stats.averageAnswerTokens == null ? '—' : Math.round(stats.averageAnswerTokens).toLocaleString()),
+    tile('average rounds per answer', stats.averageRoundsPerAnswer == null ? '—' : stats.averageRoundsPerAnswer.toFixed(1))
+  );
+  // Only what's off: full coverage needs no sentence.
+  const notes = [];
+  if (stats.pricedRounds < stats.rounds) notes.push(`${fmt(stats.pricedRounds)} of ${fmt(stats.rounds)} requests reported cost`);
+  if (stats.pricedAnswers < stats.completedAnswers) notes.push(`${fmt(stats.pricedAnswers)} of ${fmt(stats.completedAnswers)} answers fully priced`);
+  if (!cache.reportedRounds) notes.push('no provider has reported cache figures yet');
+  if (stats.auxiliary?.requests) notes.push(`conversation summaries: ${fmt(stats.auxiliary.requests)} requests, ${costFmt(stats.auxiliary.cost)}, not included above`);
+  coverage.textContent = notes.join(' · ');
+  for (const model of stats.models || []) {
+    const row = el('div', 'statistics-cost-row');
+    const name = el('span'); name.className = 'usage-model-name'; name.textContent = model.model; name.title = model.model;
+    const amount = el('span'); amount.textContent = `${costFmt(model.cost)} · ${model.pricedRounds}/${model.rounds} priced requests`;
+    row.append(name, amount); modelsBox.appendChild(row);
+  }
+  if (toolsBox) {
+    if (!stats.tools || !stats.tools.length) {
+      toolsBox.appendChild(el('div', 'empty')).textContent = 'No tool calls recorded yet.';
+    } else {
+      const maxCalls = Math.max(...stats.tools.map((t) => t.calls));
+      for (const tool of stats.tools) {
+        const row = el('div', 'statistics-tool-row');
+        const name = el('span', 'statistics-tool-name'); name.textContent = tool.name; name.title = tool.name;
+        const track = el('span', 'statistics-tool-track');
+        const bar = el('span', 'statistics-tool-bar');
+        bar.style.width = `${(tool.calls / maxCalls) * 100}%`;
+        track.appendChild(bar);
+        const count = el('span', 'statistics-tool-count'); count.textContent = `${tool.calls.toLocaleString()} call${tool.calls === 1 ? '' : 's'}`;
+        row.append(name, track, count); toolsBox.appendChild(row);
+      }
+    }
+  }
+}
+
+export async function loadUsage() {
+  const request = ++usageRequest;
+  let data;
+  try {
+    const f = selected ? JSON.parse(selected) : {};
+    const q = new URLSearchParams();
+    if (f.model) q.set('model', f.model);
+    if (f.provider != null) q.set('provider', f.provider);
+    data = await api.get(`/api/usage${q.size ? `?${q}` : ''}`);
+  } catch (err) {
+    if (request !== usageRequest) return;
+    const msg = Object.assign(el('div', 'empty'), { textContent: `Couldn't load usage (${err.message}).` });
+    $('usageStats').replaceChildren(msg);
+    $('usageModels').replaceChildren();
+    $('usageBars').replaceChildren();
+    return;
+  }
+  if (request !== usageRequest) return;
+  days = data.days || [];
+  statistics = data.statistics || null;
+  path = [];
+  targets = data.statistics?.targets || [];
+  render();
+}
+
+
+const CATEGORY_LABELS = {
+  operator: 'Operator / system prompt', harness: 'TinyWebUI harness', mcp_instructions: 'MCP guidance', checkpoint: 'Conversation summary',
+  tool_schemas: 'Tool schemas', user_messages: 'User messages (including document notes)',
+  assistant_history: 'Assistant history', tool_history: 'Tool-call history', tool_results: 'Tool results',
+  reasoning_history: 'Reasoning resent on wire', image_allowance: 'Image allowance', attachments_other: 'Other attachments',
+  system_other: 'Other system content', reasoning: 'Reasoning / thinking', tool_generation: 'Tool-call generation',
+  intermediate_text: 'Intermediate assistant text', final_text: 'Final visible answer', provider_delta: 'Other / provider delta'
+};
+/**
+ * One filter for the whole panel. A model served by several upstreams also
+ * gets one entry per upstream: each has its own prices and its own cache, so
+ * mixed together neither the saving nor the misses say much.
+ */
+function renderModelFilter() {
+  const box = $('statisticsFilter');
+  if (!box) return;
+  box.replaceChildren();
+  const select = el('select'); select.setAttribute('aria-label', 'Statistics for model');
+  const add = (value, text) => { const o = el('option'); o.value = value; o.textContent = text; select.append(o); };
+  add('', 'All models');
+  for (const t of targets) {
+    add(JSON.stringify({ model: t.model }), t.providers.length > 1 ? `${t.model} (all providers)` : t.model);
+    if (t.providers.length > 1) for (const p of t.providers) add(JSON.stringify({ model: t.model, provider: p }), `${t.model} @ ${p}`);
+  }
+  // A choice that no longer exists (data changed underneath) would show blank.
+  if (![...select.options].some((o) => o.value === selected)) selected = '';
+  select.value = selected;
+  select.onchange = () => { selected = select.value; loadUsage(); };
+  box.append(select);
+}
+function renderDistribution(rows) {
+  const box = $('usageDistribution');
+  if (!box) return;
+  box.replaceChildren();
+  const models = rows.flatMap((d) => d.models);
+  const snapshots = models.map((m) => m.attribution).filter(Boolean);
+  const requests = snapshots.reduce((n, s) => n + s.requests, 0);
+  const note = el('p', 'usage-attribution-note');
+  note.textContent = requests
+    ? `${fmt(requests)} of ${fmt(models.reduce((n,m) => n + (m.requests || 0), 0))} requests have saved attribution. Provider totals are authoritative; ~ component counts are character-based estimates. Cache reads are a subset of input and cannot be assigned to individual components.`
+    : 'No saved token attribution in this range. New requests will record it; historical prompts are not reconstructed.';
+  box.append(note);
+  if (!requests) return;
+  for (const side of ['input', 'output']) {
+    const panel = el('section', 'usage-composition');
+    const heading = el('h3'); heading.textContent = side === 'input' ? 'Input composition' : 'Output composition'; panel.append(heading);
+    const buckets = new Map();
+    let total = 0, reported = 0;
+    for (const snapshot of snapshots) {
+      total += snapshot[side].total; reported += snapshot[side].reported;
+      for (const b of snapshot[side].buckets) {
+        const key = JSON.stringify([b.category, b.source]);
+        const item = buckets.get(key) || { category: b.category, source: b.source, tokens: 0 };
+        item.tokens += b.tokens; buckets.set(key, item);
+      }
+    }
+    const complete = reported === requests;
+    const summary = el('p', 'usage-attribution-note');
+    summary.textContent = `${fmt(total)} provider-reported tokens across ${fmt(reported)}/${fmt(requests)} requests.`;
+    if (side === 'input') summary.textContent += ` ${fmt(snapshots.reduce((n,s) => n + s.cached, 0))} cached input tokens reported.`;
+    panel.append(summary);
+    const table = el('table', 'usage-composition-table');
+    for (const b of buckets.values()) {
+      const row = el('tr');
+      const label = el('td'); label.textContent = CATEGORY_LABELS[b.category] || b.category;
+      const value = el('td'); value.textContent = `${b.source === 'provider' ? '' : '~'}${fmt(b.tokens)} (${b.source === 'provider' ? 'provider' : 'estimated'})`;
+      const share = el('td'); share.textContent = complete && total > 0 ? `${(b.tokens / total * 100).toFixed(1)}%` : '—';
+      row.append(label, value, share); table.append(row);
+    }
+    // A signed provider delta is intentionally not hidden or scaled away. A
+    // negative delta means the estimates exceed the provider's token total.
+    const hasNegative = [...buckets.values()].some((b) => b.tokens < 0);
+    if (complete && total > 0 && !hasNegative) {
+      const track = el('div', 'usage-composition-track');
+      let i = 0;
+      for (const b of buckets.values()) {
+        if (!b.tokens) continue;
+        const seg = el('span'); seg.style.width = `${b.tokens / total * 100}%`;
+        seg.style.background = `var(${MODEL_PALETTE[i++ % MODEL_PALETTE.length]})`;
+        seg.title = `${CATEGORY_LABELS[b.category] || b.category}: ${fmt(b.tokens)}`;
+        track.append(seg);
+      }
+      panel.append(track);
+    }
+    panel.append(table);
+    if (hasNegative) {
+      const warning = el('p', 'usage-attribution-note'); warning.textContent = 'Estimates exceed provider totals in some categories. The signed delta shows the difference; components have not been rescaled.'; panel.append(warning);
+    }
+    box.append(panel);
+  }
+  const detail = el('details'); const title = el('summary'); title.textContent = 'Tool / MCP overhead by server'; detail.append(title);
+  const grouped = new Map();
+  for (const snapshot of snapshots) for (const b of snapshot.input.buckets) {
+    if (!b.capability) continue;
+    const key = `${b.capability} · ${CATEGORY_LABELS[b.category] || b.category}`;
+    grouped.set(key, (grouped.get(key) || 0) + b.tokens);
+  }
+  for (const [label, count] of grouped) {
+    const row = el('p', 'usage-attribution-note'); row.textContent = `${label}: ~${fmt(count)} estimated tokens`; detail.append(row);
+  }
+  box.append(detail);
+}

package/public/shared/attachment_note.js

@@ -0,0 +1,23 @@
+/**
+ * The inline note that tells the model a document's id ("read_document" needs
+ * it). It lives in the stored message text, so the page strips it back out to
+ * draw a chip instead. One module for both directions: the server writes the
+ * note, the transcript reads it, and they cannot drift apart.
+ */
+
+export function attachmentNote(doc) {
+  return `\n\n[Attached document: "${doc.filename}" (id: ${doc.id}, ${doc.char_len.toLocaleString('en-US')} chars). Use read_document to search or read it.]`;
+}
+
+// Only notes at the very end count: the server appends them after the user's
+// text, so one the user typed mid-message is left alone.
+const NOTES_AT_END = /(?:\n\n\[Attached document: ".*?" \(id: ([\w.-]+), [\d,]+ chars\)\. Use read_document to search or read it\.\])+$/;
+const ONE_NOTE = /\[Attached document: ".*?" \(id: ([\w.-]+), /g;
+
+/** A stored message's text without its notes, and the document ids they named. */
+export function splitAttachmentNotes(content) {
+  const text = String(content ?? '');
+  const tail = NOTES_AT_END.exec(text);
+  if (!tail) return { text, ids: [] };
+  return { text: text.slice(0, tail.index), ids: [...tail[0].matchAll(ONE_NOTE)].map((m) => m[1]) };
+}

package/public/shared/events.js

@@ -0,0 +1,27 @@
+/**
+ * The events a running turn streams to the browser, as `data: {"type": ...}`
+ * lines. Shared by both sides: the server imports this file to emit them
+ * (src/chat/runs.js, llm.js, tool_executor.js, agent.js) and the page imports
+ * it to handle them (stream.js). It lives in public/shared/ because that is the one
+^ * place both can load. A test checks that stream.js handles every one.
+ */
+export const EVENT = Object.freeze({
+  CHAT: 'chat',                     // the run's chat id and title, first on every stream
+  USER: 'user',                     // a user message the run added (queued follow-up, steering)
+  QUEUE: 'queue',                   // what is waiting to be sent into this chat
+  NEXT_RUN: 'next_run',             // a queued follow-up is starting as a new run
+  REASONING: 'reasoning',           // a chunk of the model's thinking
+  TEXT: 'text',                     // a chunk of the model's answer
+  TOOL_CALL: 'tool_call',           // the model called a tool
+  TOOL_RESULT: 'tool_result',       // that call's result
+  APPROVAL: 'approval',             // a call waits for the user's allow / deny
+  APPROVAL_DONE: 'approval_done',   // the user decided
+  QUESTION: 'question',             // ask_user put a question to the user
+  QUESTION_DONE: 'question_done',   // it was answered, skipped, timed out or cancelled
+  TASKS: 'tasks',                   // the chat's checklist changed
+  COMPACTED: 'compacted',           // older context was compacted this turn
+  USAGE: 'usage',                   // token usage for one model round
+  NOTICE: 'notice',                 // something worth telling the user, not an error
+  ERROR: 'error',                   // the run failed or was stopped
+  DONE: 'done'                      // the turn finished
+});

package/public/shared/features.js

@@ -0,0 +1,21 @@
+/**
+ * Every feature a role can be granted (access.roles.*.features). Shared by
+ * both sides: the server checks them on each API route (src/routes/*,
+ * src/access/policy.js) and the page hides what the viewer cannot use
+ * (core/access.js, chat/composer.js, app.js).
+ */
+export const FEATURE = Object.freeze({
+  CHAT: 'chat',
+  ATTACHMENTS: 'attachments',
+  IMAGES: 'images',
+  SEARCH: 'search',
+  FOLDERS: 'folders',
+  AUTOMATIONS: 'automations',
+  STATISTICS: 'statistics',
+  MODEL_PICKER: 'model-picker',
+  TOOLS: 'tools',
+  SETTINGS: 'settings',
+  MCP: 'mcp',
+  ADMIN: 'admin',
+  OVERSIGHT: 'oversight'
+});

package/public/shared/origins.js

@@ -0,0 +1,8 @@
+/**
+ * Where a stored message came from, when it was not typed by the user. The
+ * server stamps it (src/automations/scheduler.js) and the page draws such a
+ * message as what it is (chat/transcript.js), not as a user bubble.
+ */
+export const ORIGIN = Object.freeze({
+  AUTOMATION: 'automation'          // a scheduled or manually triggered automation run
+});

package/public/shared/usage.js

@@ -0,0 +1,59 @@
+/**
+ * Reading a provider's usage object. Shared by both sides so the transcript's
+ * per-turn line and the Statistics panel count the same tokens.
+ *
+ * Nothing here is standardised; each provider spells it differently, and some
+ * report no cache figures at all -- then a hit is invisible, not absent. So
+ * every reader returns null for "not reported" and the caller picks a default.
+ *   OpenAI / Gemini / OpenRouter : prompt_tokens_details.cached_tokens
+ *   OpenAI Responses             : input_tokens_details.cached_tokens
+ *   Anthropic                    : cache_read_input_tokens (+ creation, billed extra)
+ *   DeepSeek                     : prompt_cache_hit_tokens / prompt_cache_miss_tokens
+ */
+
+const num = (v) => {
+  if (v == null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+};
+
+export const inputTokens = (u) => num(u?.prompt_tokens ?? u?.input_tokens);
+export const outputTokens = (u) => num(u?.completion_tokens ?? u?.output_tokens);
+
+export const cacheReads = (u) => num(
+  u?.prompt_tokens_details?.cached_tokens
+  ?? u?.input_tokens_details?.cached_tokens
+  ?? u?.cache_read_input_tokens
+  ?? u?.prompt_cache_hit_tokens
+  ?? u?.cached_tokens
+);
+
+export const cacheWrites = (u) => num(
+  u?.cache_creation_input_tokens
+  ?? u?.cache_write_tokens
+  ?? u?.prompt_tokens_details?.cache_write_tokens
+  ?? u?.prompt_tokens_details?.cache_creation_tokens
+  ?? u?.input_tokens_details?.cache_write_tokens
+);
+
+/** Folds one or more raw usage objects into the numbers a turn displays. */
+export function tally(raws) {
+  const t = { in: 0, out: 0, cached: 0, written: 0, discount: 0, reported: false, raw: raws, provider: null, providers: [] };
+  for (const u of raws) {
+    if (u.provider) {
+      t.provider = u.provider;
+      // Distinct upstreams, in the order they served. A turn split across two
+      // of them cannot cache between rounds, and summing would otherwise hide
+      // that behind whichever one happened to serve last.
+      if (!t.providers.includes(u.provider)) t.providers.push(u.provider);
+    }
+    t.in += inputTokens(u) ?? 0;
+    t.out += outputTokens(u) ?? 0;
+    t.cached += cacheReads(u) ?? 0;
+    t.written += cacheWrites(u) ?? 0;
+    t.discount += Number(u.cache_discount || 0);
+    // "The provider said zero" is not "the provider said nothing".
+    if (u.prompt_tokens_details || u.input_tokens_details || cacheReads(u) !== null || cacheWrites(u) !== null) t.reported = true;
+  }
+  return t;
+}