@contraagent/ui 0.0.0-stage → 0.2.0

package/src/adapters/transcript/rounds.ts

@@ -0,0 +1,86 @@
+// Rounds as the reader counts them, from each round's launch and the task's
+// journal rows.
+//
+// Each round is one turn of the coding agent. A *try* starts a new session
+// (the first one, or a retry after a failure); a *fix-up* continues the same
+// session after the output failed its checks, with the errors in its prompt; a
+// *model switch* starts a session on the next model of the failover chain
+// within the same try (the journal row's `hops`), after a rate limit.
+import type { LaunchEvent } from '@contraagent/api';
+import type { RoundInfo, TryResult } from '../../core/events.js';
+
+/** The start of the prompt the runner sends when an output failed its checks (contracts.py). */
+const FIXUP_PROMPT = 'The output file(s) you wrote do not pass their checks.';
+
+/** The check errors a fix-up's prompt lists (the lines under `Errors:`). */
+export function fixupErrors(prompt: string | null | undefined): string[] {
+  const out: string[] = [];
+  let inErrors = false;
+  for (const line of (prompt || '').split('\n')) {
+    if (/^Errors:\s*$/.test(line)) inErrors = true;
+    else if (inErrors && line.startsWith('- ')) out.push(line.slice(2));
+    else if (inErrors && line.trim() && !line.startsWith('- ')) inErrors = false;
+  }
+  return out;
+}
+
+export const isFixup = (launch: Pick<LaunchEvent, 'prompt'> | null | undefined): boolean =>
+  !!launch && (launch.prompt || '').startsWith(FIXUP_PROMPT);
+
+
+/**
+ * Classify each round (by its launch) as a try or a fix-up, and attach what is known of
+ * its result. `rows` are the task's journal rows in order; the n-th that ran is the n-th try's.
+ */
+export function classifyRounds(launches: readonly (Pick<LaunchEvent, 'prompt'> | null)[], rows: readonly TryResult[]): RoundInfo[] {
+  // The tries that ran, in order: a resumed run numbers a task's attempts from 0 again,
+  // so a try's row is found by its place, not by its attempt number.
+  const byTry = new Map(rows.filter((r) => r.stop !== 'invalid_input' && r.stop !== 'skipped').map((r, i) => [i + 1, r]));
+  const out: RoundInfo[] = [];
+  let tryNo = 0;
+  let fixupNo = 0;
+  let hopNo = 0;
+  launches.forEach((l, i) => {
+    const hops = byTry.get(tryNo)?.hops?.length ?? 1;
+    if (i > 0 && isFixup(l)) fixupNo++;
+    else if (i > 0 && hopNo + 1 < hops) {
+      hopNo++; // a fresh session within the same try: the next model of its chain
+      fixupNo = 0;
+    } else {
+      tryNo++;
+      hopNo = 0;
+      fixupNo = 0;
+    }
+    const hop = byTry.get(tryNo)?.hops?.[hopNo];
+    const model = hop?.model || hop?.route || '';
+    const kind = fixupNo ? 'fixup' : hopNo ? 'switch' : 'try';
+    out.push({ kind, tryNo, fixupNo, hopNo, model, result: null, rejectedWith: [], switchedStop: '', switchedTo: '', row: null });
+  });
+  out.forEach((r, i) => {
+    const next = out[i + 1];
+    if (next && next.tryNo === r.tryNo && next.hopNo !== r.hopNo) {
+      r.result = 'switched';
+      r.switchedStop = byTry.get(r.tryNo)?.hops?.[r.hopNo]?.stop ?? '';
+      r.switchedTo = next.model;
+      return;
+    }
+    if (next && next.tryNo === r.tryNo) {
+      r.result = 'rejected';
+      r.rejectedWith = fixupErrors(launches[i + 1]?.prompt);
+      return;
+    }
+    const row = byTry.get(r.tryNo) ?? null;
+    r.row = row;
+    r.result = row ? (row.ok ? 'ok' : 'failed') : null;
+  });
+  return out;
+}
+
+/** The check name in an error line (`.../delta.json: [three_points] points: ...` -> `three_points`). */
+export const checkName = (error: string): string => /\[([\w.-]+)\]/.exec(error)?.[1] ?? '';
+
+/** A check error as the reader reads it: `[three_points] points: ...` after a path -> `three_points: points: ...`. */
+export function checkMessage(error: string): string {
+  const m = /\[([\w.-]+)\]\s*(.*)$/.exec(error);
+  return m ? `${m[1]}: ${m[2]}` : error;
+}

package/src/adapters/transcript/sections.ts

@@ -0,0 +1,82 @@
+// A task's transcript as `<cae-transcript>` shows it: a section per round,
+// named as the reader counts rounds (attempt, correction, model switch), with
+// how it ended, who ran it, its command line and prompt, and its items.
+import { isLaunched, runRelative, type JournalRow, type LaunchEvent } from '@contraagent/api';
+import type { TranscriptDetail, TranscriptItem, TranscriptSection } from '@contraagent/elements/transcript';
+import { msg, str } from '@lit/localize';
+import type { RoundInfo } from '../../core/events.js';
+import { attemptNames } from '../../words/attempts.js';
+import { roundLabel, roundMark, switchText } from '../../words/rounds.js';
+import { stopLabel } from '../../words/stop.js';
+import type { Transcript } from './model.js';
+import { whoTags } from './who.js';
+
+export interface SectionsContext {
+  /** The run id: paths in a reason are shown relative to it. */
+  run: string;
+  /** The task's journal rows: the attempts' names. */
+  rows: readonly JournalRow[];
+  /** The latest round is still being written (the task runs and its transcript is tailed). */
+  active: boolean;
+}
+
+/** The command line, and the prompt with what was not saved of it. */
+function launchDetails(launch: LaunchEvent): TranscriptDetail[] {
+  const prompt = launch.prompt || '';
+  const trunc = launch.prompt_truncated || 0;
+  return [
+    { id: 'cmd', code: true, summary: msg('Command line'), text: launch.argv.join(' ') },
+    {
+      id: 'prompt',
+      summary: trunc
+        ? msg(str`Prompt (${prompt.length} characters; ${trunc} characters not saved)`)
+        : msg(str`Prompt (${prompt.length} characters)`),
+      text: prompt + (trunc ? `\n\n${msg(str`(${trunc} characters not saved)`)}` : ''),
+    },
+  ];
+}
+
+/** How the round ended, after its transcript: its output was sent back, its model switched, or its try failed. */
+function footer(info: RoundInfo, run: string): TranscriptSection['footer'] {
+  if (info.result === 'rejected') {
+    return {
+      tone: 'attention',
+      title: msg('Output failed checks'),
+      list: info.rejectedWith.map((e) => runRelative(e, run)),
+      note: msg('Sent in the correction prompt'),
+    };
+  }
+  if (info.result === 'switched') return { tone: 'failed', title: switchText(info) };
+  if (info.result === 'failed' && info.row) {
+    const why = runRelative(info.row.reason, run) || stopLabel(info.row.stop);
+    return { tone: 'failed', title: msg(str`Attempt ${info.tryNo} failed: ${why}`) };
+  }
+  return undefined;
+}
+
+/**
+ * The sections of a transcript, one per round; `rounds` are the rounds as
+ * `classifyRounds` counts them. In the reader's language: call at render time.
+ */
+export function transcriptSections(t: Transcript, rounds: readonly RoundInfo[], ctx: SectionsContext): TranscriptSection[] {
+  const tries = rounds[rounds.length - 1]?.tryNo ?? 1;
+  const names = attemptNames(ctx.rows.filter(isLaunched));
+  const last = t.rounds.length - 1;
+  return t.rounds.map((r, i) => {
+    const info = rounds[i];
+    const [mark, word, tip] = info ? roundMark(info, ctx.run) : ['', '', ''];
+    const model = r.who?.model;
+    return {
+      id: r.id,
+      title: info ? roundLabel(info, tries, names[info.tryNo - 1]) : String(i + 1),
+      facts: model ? [model.replace(/^claude-/, '')] : [],
+      verdict: mark ? { tone: mark === '✓' ? 'done' : 'failed', text: word, tip } : undefined,
+      active: i === last && ctx.active,
+      tags: r.launch ? whoTags(r.who) : [],
+      details: r.launch ? launchDetails(r.launch) : [],
+      // the model leaves an event's title to the reader's words: the only event is an API request sent again
+      items: r.items.map((it): TranscriptItem => (it.type === 'event' ? { ...it, title: msg('API request sent again') } : it)),
+      footer: info && footer(info, ctx.run),
+    };
+  });
+}

package/src/adapters/transcript/web.ts

@@ -0,0 +1,40 @@
+// The pages a web search returned, read from its output.
+
+/** One page a web search returned. */
+export interface WebResult {
+  title: string;
+  url: string;
+}
+
+const RESULTS_MAX = 20;
+const JSON_LINK = /\{\s*"title"\s*:\s*"((?:[^"\\]|\\.)*)"\s*,\s*"url"\s*:\s*"(https?:\/\/[^"\s]+)"/g;
+const NUMBERED = /^\s*\[\d+\]\s+(.+)\n\s*(https?:\/\/\S+)/gm;
+const BARE_URL = /https?:\/\/[^\s"'<>)\]]+/g;
+
+/**
+ * The pages a web search's output lists, in order, at most 20: Claude Code's
+ * `{"title", "url"}` links, omp's `[n] title` lines followed by a URL, else every
+ * http(s) URL in the text (titled by itself).
+ */
+export function webResults(out: string | null | undefined): WebResult[] {
+  const text = out ?? '';
+  const found: WebResult[] = [];
+  const seen = new Set<string>();
+  const add = (title: string, url: string): void => {
+    if (seen.has(url) || found.length >= RESULTS_MAX) return;
+    seen.add(url);
+    found.push({ title: title.trim() || url, url });
+  };
+  for (const m of text.matchAll(JSON_LINK)) {
+    let title = m[1] ?? '';
+    try {
+      title = JSON.parse(`"${title}"`) as string;
+    } catch {
+      // an escape JSON does not take: the raw text is still a title
+    }
+    add(title, m[2] ?? '');
+  }
+  if (!found.length) for (const m of text.matchAll(NUMBERED)) add(m[1] ?? '', m[2] ?? '');
+  if (!found.length) for (const m of text.matchAll(BARE_URL)) add('', m[0].replace(/[.,;:!?]+$/, '')); // a sentence's own punctuation
+  return found;
+}

package/src/adapters/transcript/who.ts

@@ -0,0 +1,53 @@
+// Who ran a session: the coding agent (the CLI), the model and the role, read
+// from its launch, and as the chips of a transcript section's head.
+import type { LaunchEvent } from '@contraagent/api';
+import type { TranscriptTag } from '@contraagent/elements/transcript';
+import { msg } from '@lit/localize';
+
+/** Who ran a round: the coding agent (the CLI), the model and the role. */
+export interface Who {
+  agent: string;
+  model: string;
+  role: string;
+}
+
+const AGENT_NAMES: Record<string, string> = {
+  claude: 'Claude Code',
+  omp: 'omp',
+  codex: 'Codex',
+  opencode: 'opencode',
+  gemini: 'Gemini CLI',
+};
+
+/** The display name of a coding agent's executable (`/usr/bin/claude` -> `Claude Code`). */
+export function agentLabel(exe: string | null | undefined): string {
+  const b = String(exe || '').split('/').pop() ?? '';
+  return AGENT_NAMES[b] ?? b;
+}
+
+const argvFlag = (argv: readonly string[], name: string): string => {
+  const i = argv.indexOf(name);
+  return i >= 0 ? (argv[i + 1] ?? '') : '';
+};
+
+/** Who ran a launch: its argv names the agent and model, its prompt's TELEMETRY line the role. */
+export function launchWho(launch: Pick<LaunchEvent, 'argv' | 'prompt'>): Who {
+  const argv = launch.argv;
+  const tele = /TELEMETRY [^\n]*role=([\w:-]+)/.exec(launch.prompt || '');
+  const role = tele?.[1];
+  return {
+    agent: agentLabel(argv[0]),
+    model: argvFlag(argv, '--model') || argvFlag(argv, '-m'),
+    role: role && role !== '-' ? role : '',
+  };
+}
+
+/** The chips for who ran a session (`tagChips`), in the reader's language (call at render time). */
+export function whoTags(w: Who | null | undefined): TranscriptTag[] {
+  if (!w) return [];
+  const tags: TranscriptTag[] = [];
+  if (w.agent) tags.push({ label: msg('coding agent'), value: w.agent, tip: msg('The CLI that ran the task (claude, omp)') });
+  if (w.model) tags.push({ label: msg('model'), value: w.model, tip: msg('The model the agent session ran on'), look: 'mono' });
+  if (w.role) tags.push({ label: msg('role'), value: w.role, tip: msg('The agent definition the coding agent ran as (agents/<role>.md)'), look: 'quiet' });
+  return tags;
+}

package/src/adapters/trends.ts

@@ -0,0 +1,337 @@
+// The trends (`/api/trends`) as the typed bodies `ca-panel-body` draws, in the UI's words:
+// built from the raw numbers, never from the English `Trends.bodies`.
+import type { Trends, TypedPanelBody } from '@contraagent/api';
+import { credentialLabel } from '../words/credential.js';
+import { fmtDur, tokenCount, usd } from '../words/format.js';
+import { accountLabel, windowName } from '../words/quota.js';
+import { deferredText } from '../words/rests.js';
+import { peakContextLabel, peakContextTip } from '../words/context.js';
+import { stopLabel } from '../words/stop.js';
+import { stateCount } from '../words/outcome.js';
+import { dayLabel, modelName, doneShare, pausedCause, perDay, restEvent, titled, trendWords, usageLine, weekdayLabels } from '../words/trends.js';
+
+/** The sections of the trends, one body each, in the order a reader checks them: their key and their body. */
+export interface TrendSection {
+  id: string;
+  body: TypedPanelBody;
+  /** The section spans the page's width (a chart over the days, a wide table). */
+  wide?: boolean;
+}
+
+const tokensOf = (t: { input?: number; output?: number; cache_read?: number; cache_creation?: number }): number =>
+  (t.input ?? 0) + (t.output ?? 0) + (t.cache_read ?? 0) + (t.cache_creation ?? 0);
+
+/**
+ * How an identity is named in the trends: its credential, and its account (`account 3f9c2a`)
+ * when that credential was of two accounts in the period (a token replaced), so their lines
+ * and rests do not read as one.
+ */
+function identityNamer(t: Trends): (credential?: string | null, account?: string | null) => string {
+  const accounts = new Map<string, Set<string>>();
+  for (const x of [...t.quota, ...t.rests]) {
+    const credential = x.credential ?? '';
+    if (!x.account) continue;
+    const seen = accounts.get(credential) ?? new Set<string>();
+    seen.add(x.account);
+    accounts.set(credential, seen);
+  }
+  return (credential, account) => {
+    const c = credential ?? '';
+    const name = credentialLabel(c) || c || '—';
+    return account && (accounts.get(c)?.size ?? 0) > 1 ? `${name} | ${accountLabel(account)}` : name;
+  };
+}
+
+/** The trends as sections; empty when no run worked in the period. */
+export function trendSections(t: Trends, locale?: string): TrendSection[] {
+  if (!t.totals.runs) return [];
+  const w = trendWords();
+  const days = t.period.days.map((d) => dayLabel(d, locale));
+  const out: TrendSection[] = [];
+  const identity = identityNamer(t);
+
+  const tot = t.totals;
+  const spent = t.daily.filter((d) => Object.keys(d.cost_usd).length).length;
+  out.push({
+    id: 'totals',
+    wide: true,
+    body: {
+      type: 'tiles',
+      collapsed: false,
+      tiles: [
+        { id: 'runs', label: w.runs, value: String(tot.runs), sub: [] },
+        {
+          id: 'attempts',
+          label: w.attempts,
+          value: String(tot.attempts),
+          sub: [[doneShare(tot.attempts ? `${Math.round((tot.ok / tot.attempts) * 100)}%` : '—'), ...(tot.partial ? [stateCount('partial', tot.partial)] : [])]],
+        },
+        { id: 'cost', label: w.cost, value: tot.cost_usd == null ? '—' : usd(tot.cost_usd), sub: spent && tot.cost_usd != null ? [[perDay(usd(tot.cost_usd / spent))]] : [] },
+        { id: 'tokens', label: w.tokens, value: tokenCount(tokensOf(tot.tokens)), sub: [[`${w.input} ${tokenCount(tot.tokens.input)} | ${w.output} ${tokenCount(tot.tokens.output)}`]] },
+        { id: 'time', label: w.time, value: fmtDur(tot.wall_s), sub: [] },
+      ],
+    },
+  });
+
+  // Cost by day, stacked by kind (or group): a magnitude over time, parts of each day's whole.
+  const series = [...new Set(t.daily.flatMap((d) => Object.keys(d.cost_usd)))];
+  const byCost = series
+    .map((s) => ({ s, total: t.daily.reduce((a, d) => a + (d.cost_usd[s] ?? 0), 0) }))
+    .sort((a, b) => b.total - a.total)
+    .map((x) => x.s);
+  out.push({
+    id: 'cost-by-day',
+    wide: true,
+    body: {
+      type: 'columns',
+      collapsed: false,
+      title: w.costByDay,
+      x: days,
+      unit: 'usd',
+      stacked: true,
+      series: byCost.map((s) => ({ name: s, values: t.daily.map((d) => d.cost_usd[s] ?? null) })),
+    },
+  });
+
+  // Agent tasks first, with their tokens and cost; Python tasks (no model, no cost) in a fold of their own.
+  const kindsTable = (id: string, title: string, kinds: Trends['kinds'], collapsed: boolean): TrendSection => ({
+    id,
+    wide: true,
+    body: {
+      type: 'table',
+      collapsed,
+      title,
+      columns: [
+        { id: 'kind', label: w.kind },
+        ...(t.kinds.some((k) => k.group && k.group !== k.kind) ? [{ id: 'group', label: w.group }] : []),
+        { id: 'tasks', label: w.tasks, align: 'end' as const, format: 'number' as const },
+        { id: 'passed', label: w.tasksDone, align: 'end' as const, format: 'pct' as const },
+        ...(kinds.some((k) => k.tasks_partial) ? [{ id: 'partial', label: w.partial, align: 'end' as const, format: 'number' as const }] : []),
+        { id: 'attempts', label: w.attempts, align: 'end' as const, format: 'number' as const },
+        { id: 'median', label: w.medianTime, align: 'end' as const, format: 'duration' as const },
+        { id: 'wall', label: w.totalTime, align: 'end' as const, format: 'duration' as const },
+        { id: 'tokens', label: w.tokens, align: 'end' as const, format: 'tokens' as const },
+        { id: 'cost', label: w.cost, align: 'end' as const, format: 'usd' as const, bar: true },
+      ],
+      rows: [...kinds]
+        .sort((a, b) => (b.cost_usd ?? 0) - (a.cost_usd ?? 0) || b.attempts - a.attempts)
+        .map((k) => ({
+          kind: k.kind,
+          group: k.group,
+          tasks: k.tasks,
+          passed: k.tasks ? k.tasks_ok / k.tasks : null,
+          partial: k.tasks_partial ?? 0,
+          attempts: k.attempts,
+          median: k.wall_s_median,
+          wall: k.wall_s,
+          tokens: tokensOf(k.tokens),
+          cost: k.cost_usd,
+          ...(k.tasks_ok < k.tasks ? { _tone: 'attention' as const } : {}),
+        })),
+    },
+  });
+  const agentKinds = t.kinds.filter((k) => k.executor !== 'python');
+  const pythonKinds = t.kinds.filter((k) => k.executor === 'python');
+  if (agentKinds.length) out.push(kindsTable('kinds', w.kinds, agentKinds, false));
+  if (pythonKinds.length) out.push(kindsTable('python-kinds', titled(w.pythonKinds, pythonKinds.length), pythonKinds, agentKinds.length > 0));
+
+  if (t.models.length) {
+    out.push({
+      id: 'models',
+      wide: true,
+      body: {
+        type: 'table',
+        collapsed: false,
+        title: w.models,
+        columns: [
+          { id: 'model', label: w.model },
+          { id: 'sessions', label: w.sessions, align: 'end', format: 'number' },
+          { id: 'calls', label: w.calls, align: 'end', format: 'number' },
+          { id: 'input', label: w.input, align: 'end', format: 'tokens' },
+          { id: 'output', label: w.output, align: 'end', format: 'tokens' },
+          { id: 'cache_read', label: w.cacheRead, align: 'end', format: 'tokens' },
+          { id: 'cache_write', label: w.cacheWrite, align: 'end', format: 'tokens' },
+          { id: 'cost', label: w.cost, align: 'end', format: 'usd', bar: true },
+          { id: 'wall', label: w.time, align: 'end', format: 'duration' },
+          ...(t.models.some((m) => m.peak_context != null)
+            ? [{ id: 'peak', label: peakContextLabel(), align: 'end' as const, format: 'tokens' as const, tip: peakContextTip() }]
+            : []),
+        ],
+        rows: t.models.map((m) => ({
+          model: modelName(m.agent, m.model),
+          sessions: m.sessions,
+          calls: m.calls,
+          input: m.input,
+          output: m.output,
+          cache_read: m.cache_read,
+          cache_write: m.cache_creation,
+          cost: m.cost_usd,
+          wall: m.wall_s,
+          peak: m.peak_context ?? null,
+        })),
+      },
+    });
+  }
+
+  // The utilization of each identity and window: a level over time, one line each.
+  if (t.quota.length) {
+    out.push({
+      id: 'usage',
+      wide: true,
+      body: {
+        type: 'lines',
+        collapsed: false,
+        title: w.usage,
+        x: days,
+        unit: 'pct',
+        series: t.quota.map((q) => ({
+          name: usageLine(identity(q.credential, q.account), windowName(q.window)),
+          values: q.daily_peak.map((p) => (p == null ? null : p / 100)),
+        })),
+      },
+    });
+  }
+
+  const bad = t.stops.filter((s) => s.stop !== 'completed' && s.stop !== 'skipped');
+  if (bad.length) {
+    out.push({
+      id: 'outcomes',
+      body: {
+        type: 'table',
+        collapsed: false,
+        title: w.outcomes,
+        columns: [
+          { id: 'outcome', label: w.outcome },
+          { id: 'attempts', label: w.attempts, align: 'end', format: 'number', bar: true },
+          { id: 'kinds', label: w.kinds },
+        ],
+        rows: bad.map((s) => ({
+          outcome: stopLabel(s.stop),
+          attempts: s.attempts,
+          kinds: Object.entries(s.kinds)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k, n]) => `${k} ${n}`)
+            .join(' | '),
+          _tone: 'failed' as const,
+        })),
+      },
+    });
+  }
+
+  if (t.denials.length) {
+    out.push({
+      id: 'denials',
+      body: {
+        type: 'table',
+        collapsed: false,
+        title: w.denials,
+        columns: [
+          { id: 'tool', label: w.tool },
+          { id: 'count', label: w.toolCalls, align: 'end', format: 'number', bar: true },
+          { id: 'kinds', label: w.kinds },
+        ],
+        rows: t.denials.map((d) => ({
+          tool: d.tool,
+          count: d.count,
+          kinds: Object.entries(d.kinds)
+            .map(([k, n]) => `${k} ${n}`)
+            .join(' | '),
+        })),
+      },
+    });
+  }
+
+  if (t.deferred.length) {
+    out.push({
+      id: 'deferred',
+      body: {
+        type: 'table',
+        // A long list folds: its count is in its title.
+        collapsed: t.deferred.length > 20,
+        title: titled(w.deferred, t.deferred.length),
+        columns: [
+          { id: 'when', label: w.when, format: 'datetime' },
+          { id: 'task', label: w.task },
+          { id: 'cause', label: w.cause },
+          { id: 'run', label: w.run },
+        ],
+        rows: [...t.deferred]
+          .sort((a, b) => b.ts.localeCompare(a.ts))
+          .map((d) => ({
+            when: d.ts,
+            task: d.key,
+            cause: d.cause === 'rest' ? pausedCause(d.reason) : deferredText({ cause: d.cause }, d.reason),
+            run: d.run,
+            _tone: 'attention' as const,
+          })),
+      },
+    });
+  }
+
+  if (t.rests.length) {
+    out.push({
+      id: 'rests',
+      body: {
+        type: 'table',
+        collapsed: false,
+        title: w.rests,
+        columns: [
+          { id: 'when', label: w.when, format: 'datetime' },
+          { id: 'identity', label: w.identity },
+          { id: 'event', label: w.event },
+          { id: 'run', label: w.run },
+        ],
+        rows: [...t.rests]
+          .sort((a, b) => (b.ts ?? '').localeCompare(a.ts ?? ''))
+          .map((r) => ({ when: r.ts, identity: identity(r.credential, r.account), event: restEvent(r.event), run: r.run })),
+      },
+    });
+  }
+
+  // When runs start: counts on a weekday × hour grid, one hue light to dark.
+  if (t.starts.counts.some((row) => row.some((n) => n > 0))) {
+    out.push({
+      id: 'starts',
+      wide: true,
+      body: {
+        type: 'heatmap',
+        collapsed: false,
+        title: w.starts,
+        x: t.starts.hours.map((h) => String(h).padStart(2, '0')),
+        y: weekdayLabels(locale),
+        values: t.starts.counts.map((row) => row.map((n) => n || null)),
+        unit: 'number',
+      },
+    });
+  }
+
+  out.push({
+    id: 'runs',
+    wide: true,
+    body: {
+      type: 'table',
+      collapsed: false,
+      title: w.runs,
+      columns: [
+        { id: 'run', label: w.run },
+        { id: 'started', label: w.started, format: 'datetime' },
+        { id: 'attempts', label: w.attempts, align: 'end', format: 'number' },
+        { id: 'passed', label: w.done, align: 'end', format: 'pct' },
+        ...(t.runs.some((r) => r.partial) ? [{ id: 'partial', label: w.partial, align: 'end' as const, format: 'number' as const }] : []),
+        { id: 'cost', label: w.cost, align: 'end', format: 'usd', bar: true },
+        { id: 'wall', label: w.time, align: 'end', format: 'duration' },
+      ],
+      rows: t.runs.map((r) => ({
+        run: r.run,
+        started: r.started_at || null,
+        attempts: r.attempts,
+        passed: r.attempts ? r.ok / r.attempts : null,
+        partial: r.partial ?? 0,
+        cost: r.cost_usd,
+        wall: r.wall_s,
+        ...(r.ok < r.attempts ? { _tone: 'attention' as const } : {}),
+      })),
+    },
+  });
+  return out;
+}

package/src/controllers/locale.ts

@@ -0,0 +1,47 @@
+// The language an element shows: its `locale` property, else the reader's
+// earlier choice or the browser's language; and the `lang` its text is in.
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { getLocale, isLocale, preferredLocale, setLocale, type Locale } from '../core/i18n.js';
+
+export interface LocaleOptions {
+  /** The element's `locale` property; '' for the reader's earlier choice, else the browser's language. */
+  locale: () => Locale | '';
+  /** The element is the page: `<html lang>` follows the language too. */
+  pageWide: () => boolean;
+}
+
+/**
+ * Sets the language when the host connects and when its `locale` changes, and
+ * sets `lang` on the host (and on `<html>` when the host is the page) after
+ * every update.
+ */
+export class LocaleController implements ReactiveController {
+  /** The `locale` the last update saw; undefined before the first. */
+  private seen: Locale | '' | undefined;
+  /** Settles when the language chosen at connect is loaded (a locale's module loads when first chosen). */
+  ready: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly host: ReactiveControllerHost & HTMLElement,
+    private readonly opts: LocaleOptions,
+  ) {
+    host.addController(this);
+  }
+
+  hostConnected(): void {
+    const l = this.opts.locale();
+    this.ready = setLocale(isLocale(l) ? l : preferredLocale()).catch(() => {});
+  }
+
+  hostUpdated(): void {
+    const l = this.opts.locale();
+    if (l !== this.seen) {
+      this.seen = l;
+      if (isLocale(l) && l !== getLocale()) void setLocale(l);
+    }
+    // A page that is the monitor speaks its language; an embedded monitor leaves the host's <html lang> alone.
+    if (this.opts.pageWide()) document.documentElement.lang = getLocale();
+    // Its own text is in its language either way (line breaking between Japanese phrases reads it).
+    this.host.lang = getLocale();
+  }
+}