@contraagent/ui 0.0.0-stage → 0.1.0

package/src/words/panels.ts

@@ -0,0 +1,53 @@
+// Words for a pipeline's own views (`monitor.Panel`): how a value of a panel body is
+// written, by its format, and the words of the charts it draws.
+import type { ValueFormat } from '@contraagent/api';
+import type { ChartStrings } from '@contraagent/elements/charts';
+import { msg, str } from '@lit/localize';
+import { fmtDur, localTime, tokenCount, usd } from './format.js';
+
+/** A fraction as a percent: `97%`, `4.5%` under 10, `<0.1%` above 0. */
+export function fractionPct(v: number): string {
+  const p = v * 100;
+  if (p > 0 && p < 0.05) return '<0.1%';
+  return Math.abs(p) < 10 ? `${Math.round(p * 10) / 10}%` : `${Math.round(p)}%`;
+}
+
+/** A number as it is, up to two decimals. */
+const plain = (v: number): string => String(Math.round(v * 100) / 100);
+
+/** A number of a body in words, by its format (`usd`, `pct` a fraction, `duration` seconds, `tokens`). */
+export function numberText(format: ValueFormat | null | undefined): (v: number) => string {
+  switch (format) {
+    case 'usd':
+      return usd;
+    case 'pct':
+      return fractionPct;
+    case 'duration':
+      return fmtDur;
+    case 'tokens':
+      return tokenCount;
+    default:
+      return plain;
+  }
+}
+
+/** A cell of a table body in words: a number by its format, a `datetime` as an absolute time, '—' when empty. */
+export function cellText(value: unknown, format: ValueFormat | null | undefined): string {
+  if (value === null || value === undefined || value === '') return '—';
+  if (format === 'datetime' && typeof value === 'string') return localTime(value, true) || value;
+  if (typeof value === 'number') return numberText(format)(value);
+  if (typeof value === 'boolean') return String(value);
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+/** The words of a chart, in the UI's language. */
+export const chartStrings = (): Partial<ChartStrings> => ({
+  empty: msg('No values'),
+  showTable: msg('Show table'),
+  showChart: msg('Show chart'),
+  label: msg('Label', { desc: 'Column of a chart\'s table view: the label of each point or bar' }),
+  other: msg('Other', { desc: 'The series of a chart past the sixth, summed into one' }),
+  total: msg('Total'),
+  none: '—',
+  scale: (low: string, high: string) => msg(str`${low} to ${high}`, { desc: 'A heatmap\'s colour scale: its lowest and highest value' }),
+});

package/src/words/passes.ts

@@ -0,0 +1,18 @@
+// A loop's passes and the loop itself, in words.
+import { msg, str } from '@lit/localize';
+
+/** A loop's pass (`flow[].loops[].pass`), as the reader counts it: "Pass 1", "Pass 2" ... (never an attempt). */
+export const passLabel = (pass: number): string => msg(str`Pass ${pass}`);
+
+/** A loop box's pass count: "1 pass", "up to 3 passes" (its loop's last pass). */
+export const passCount = (n: number): string => (n <= 1 ? msg('1 pass') : msg(str`up to ${n} passes`));
+
+/** How many passes a unit ran: "1 pass", "3 passes". */
+export const passesRan = (n: number): string => (n <= 1 ? msg('1 pass') : msg(str`${n} passes`));
+
+/** How many units ran each number of passes of a loop: "1 pass: 4 | 2 passes: 1". */
+export const passSpread = (spread: readonly (readonly [number, number])[]): string =>
+  spread.map(([n, units]) => (n <= 1 ? msg(str`1 pass: ${units}`) : msg(str`${n} passes: ${units}`))).join(' | ');
+
+/** A loop of the flow (a loop box, a breadcrumb level). */
+export const loopLabel = (): string => msg('loop');

package/src/words/preflight.ts

@@ -0,0 +1,53 @@
+// Words for the run's preflight (`Plan.preflight`): one request to each model of the
+// run before its first agent session, and what became of the kinds whose models did not answer.
+import type { PreflightRecord, DroppedRoute, Substitution } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { credentialLabel } from './credential.js';
+import { facts, listText } from './format.js';
+
+/** A route as the history names it: `agent / model`, the agent alone for its default model. */
+export const routeName = (agent: string, model: string): string => (model ? `${agent} / ${model}` : agent);
+
+/** The label of the preflight's facts. */
+export const preflightLabel = (): string => msg('Model availability');
+
+/** What the preflight is, for its tooltip, with its policy. */
+export const preflightTip = (policy: PreflightRecord['policy']): string =>
+  msg(str`One request to each model before the first agent session (preflight, policy ${policy})`);
+
+/** A preflight that dropped no model. */
+export const allAvailable = (): string => msg('all models available');
+
+/** A model that did not answer, or that its coding agent does not list (`dropped`). */
+export const unavailableLabel = (): string => msg('Unavailable', { desc: 'A model that did not answer the request before the run' });
+
+/** A dropped model in one row: `claude / opus | identity work | rate limited | kinds review and summarize`. */
+export const unavailableText = (d: DroppedRoute): string =>
+  facts(
+    routeName(d.agent, d.model),
+    d.credential ? msg(str`identity ${credentialLabel(d.credential)}`) : '',
+    d.reason,
+    d.kinds.length ? msg(str`kinds ${listText(d.kinds)}`) : '',
+  );
+
+/** A kind that runs on the first model that answered, in place of its own (`substituted`). */
+export const replacedLabel = (): string => msg('Model replaced');
+
+/** What a replaced model is, for its tooltip. */
+export const replacedTip = (): string => msg('A kind with no available model, run on the first model that answered (substitute)');
+
+/** A replaced model in one row: `review | claude / opus → claude / sonnet`. */
+export const replacedText = (s: Substitution): string =>
+  facts(s.kind, `${routeName(s.from_agent, s.from_model)} → ${routeName(s.to_agent, s.to_model)}`);
+
+/** A kind none of whose models is available (`kept`, `stopped`). */
+export const noModelLabel = (): string => msg('No available model');
+
+/** What a kept kind is, for its tooltip. */
+export const keptTip = (): string => msg('A kind with no available model, run on its own model (kept)');
+
+/** The title of a run the preflight ended before its first agent session (`stopped`). */
+export const preflightStoppedTitle = (): string => msg('Ended before the first agent session');
+
+/** The cause of that end: `No available model for review and summarize`. */
+export const preflightStoppedCause = (kinds: readonly string[]): string => msg(str`No available model for ${listText(kinds)}`);

package/src/words/priority.ts

@@ -0,0 +1,8 @@
+// Words for a task's priority (`PlanNode.priority`): a tie-breaker in the queue's order.
+import { msg, str } from '@lit/localize';
+
+/** A task's priority as a fact: `Priority 2`; '' for the default, 0. */
+export const priorityText = (p: number | null | undefined): string => (p ? msg(str`Priority ${p}`) : '');
+
+/** What a task's priority is, for its tooltip. */
+export const priorityTip = (): string => msg("Tie-breaker in the queue's order (priority)");

package/src/words/prompt.ts

@@ -0,0 +1,20 @@
+// A prompt and an instructions template as a reader reads them: the template's
+// placeholders picked out, and a prompt's TELEMETRY line apart from its prose.
+import { esc } from '@contraagent/elements';
+
+/** `$unit` and `{{contract}}` picked out of an instructions template (escaped source). */
+export function instructionsHtml(text: string): string {
+  return markInstructions(esc(text));
+}
+
+/** The same, on already-rendered HTML. */
+export const markInstructions = (html: string): string =>
+  html
+    .replace(/\$\{?([A-Za-z_]\w*)\}?/g, '<span class="pv">$&</span>')
+    .replace(/\{\{contract\}\}/g, '<span class="pv pc">{{contract}}</span>');
+
+/** A prompt's leading `TELEMETRY ...` line (which run and task it belongs to), apart from its prose. */
+export function splitTelemetry(text: string): { head: string; body: string } {
+  const m = text.match(/^(TELEMETRY [^\n]*)\n+([\s\S]*)$/);
+  return m ? { head: m[1] ?? '', body: m[2] ?? '' } : { head: '', body: text };
+}

package/src/words/quota.ts

@@ -0,0 +1,108 @@
+// Words for a subscription's utilization readings (see @contraagent/api quota.ts).
+import type { QuotaReading } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { facts, fmtDur, localTime, sentence } from './format.js';
+import { credentialLabel } from './credential.js';
+
+/** A utilization as a whole percent: `14%`; '—' when not reported. */
+export const pct = (v: number | null | undefined): string => (v === null || v === undefined ? '—' : `${Math.round(v)}%`);
+
+/** A reading's `status` in words, with the window it is about when known (`near the limit | weekly`); '' for `allowed` (the usual case) or none. */
+export function quotaStatusLabel(status: string | null | undefined, window?: string | null): string {
+  if (!status || status === 'allowed') return '';
+  const s = status.split(',');
+  const word = s.some((x) => ['rejected', 'exhausted', 'quota', 'blocked'].includes(x))
+    ? msg('limit reached')
+    : s.every((x) => ['allowed_warning', 'warning'].includes(x))
+      ? msg('near the limit')
+      : msg(str`unknown (${status})`);
+  return window ? facts(word, windowName(window)) : word;
+}
+
+/**
+ * A usage window's name: `5-hour`, `weekly`, and a model's own window by its model
+ * (`seven_day_opus`: `weekly (opus)`); an unknown window as it is named.
+ */
+export function windowName(window: string): string {
+  if (window === 'five_hour') return msg('5-hour');
+  if (window === 'seven_day') return msg('weekly');
+  const own = /^(five_hour|seven_day)_(.+)$/.exec(window);
+  if (own) return own[1] === 'five_hour' ? msg(str`5-hour (${own[2]})`) : msg(str`weekly (${own[2]})`);
+  return window;
+}
+
+/** An account's digest, short, as a label: `account 3f9c2a`. */
+export const accountLabel = (account: string): string => msg(str`account ${account.slice(0, 6)}`);
+
+/** When a window resets, relative to now: `resets in 2h 58m`; '' when unknown. */
+export function resetsIn(iso: string | null | undefined, now = Date.now()): string {
+  const t = Date.parse(iso ?? '');
+  if (Number.isNaN(t)) return '';
+  if (t <= now) return msg('reset');
+  const h = (t - now) / 3_600_000;
+  // A weekly window is days away: days and hours read better than 121h.
+  const left = h >= 48 ? msg(str`${Math.floor(h / 24)}d ${Math.floor(h % 24)}h`) : fmtDur((t - now) / 1000);
+  return msg(str`resets in ${left}`);
+}
+
+/** A reading in one line, the weekly window first (the one that runs out first in practice): `weekly 41% | 5-hour 14%`. */
+export const readingShort = (r: QuotaReading): string =>
+  facts(msg(str`weekly ${pct(r.seven_day_pct)}`), msg(str`5-hour ${pct(r.five_hour_pct)}`));
+
+/** A reading in full, for a tooltip: both windows, their resets, when it arrived. */
+export function readingTip(r: QuotaReading): string {
+  const parts = [
+    r.seven_day_resets_at
+      ? msg(str`Weekly usage ${pct(r.seven_day_pct)} (resets ${localTime(r.seven_day_resets_at, true)})`)
+      : msg(str`Weekly usage ${pct(r.seven_day_pct)}`),
+    r.five_hour_resets_at
+      ? msg(str`5-hour usage ${pct(r.five_hour_pct)} (resets ${localTime(r.five_hour_resets_at, true)})`)
+      : msg(str`5-hour usage ${pct(r.five_hour_pct)}`),
+    // The windows beyond the two: a model's own (`weekly (opus)`).
+    ...Object.entries(r.windows ?? {})
+      .filter(([name]) => name !== 'five_hour' && name !== 'seven_day')
+      .map(([name, w]) => msg(str`${sentence(windowName(name))} usage ${pct(w.pct)}`)),
+    msg(str`Reported ${localTime(r.observed_at, true)}`),
+  ];
+  const status = quotaStatusLabel(r.status, r.status_window);
+  if (status) parts.push(msg(str`Status: ${status}`));
+  if (r.threshold_pct != null) parts.push(msg(str`Warning threshold: ${pct(r.threshold_pct)}`));
+  if (r.overage_status) parts.push(msg(str`Extra usage: ${extraUsage(r.overage_status)}`));
+  if (r.account) parts.push(msg(str`Account: ${r.account}`));
+  return parts.join('\n');
+}
+
+/** Whether usage past the limit is allowed (`overage_status`): `allowed`, `not allowed`, else as reported. */
+function extraUsage(status: string): string {
+  if (status === 'allowed' || status === 'allowed_warning') return msg('allowed');
+  if (status === 'rejected') return msg('not allowed');
+  return status;
+}
+
+/** A reading with its account: `weekly 41% | 5-hour 14% | default`. */
+export const accountReading = (r: QuotaReading): string => facts(readingShort(r), credentialLabel(r.credential));
+
+/** One account's latest reading (`credential` + `last`). */
+interface AccountLast {
+  credential: string;
+  last: QuotaReading;
+}
+
+/**
+ * The busiest account's latest reading, for a one-line summary:
+ * `weekly 43% | 5-hour 33%`; with more accounts, the busiest one's name and `1 more account`.
+ * `accounts` comes sorted, the highest weekly use first.
+ */
+export function accountsLine(accounts: readonly AccountLast[]): string {
+  const top = accounts[0];
+  if (!top) return '';
+  const more = accounts.length - 1;
+  // One account: its name is in the tooltip; with more, the line names the busiest.
+  if (!more) return readingShort(top.last);
+  const line = accountReading(top.last);
+  return facts(line, more === 1 ? msg('1 more account') : msg(str`${more} more accounts`));
+}
+
+/** Every account's latest reading, one per line, for a tooltip. */
+export const accountsTip = (accounts: readonly AccountLast[]): string =>
+  accounts.map((a) => (a.credential ? `${credentialLabel(a.credential)}\n${readingTip(a.last)}` : readingTip(a.last))).join('\n\n');

package/src/words/rests.ts

@@ -0,0 +1,96 @@
+// A credential's quota rest (the reader's "paused identity") and why the queue
+// deferred a task, in words. The data says it (`Rest`, `DeferralCause`);
+// the recorded English sentence (`PlanNode.deferred`) is only the fallback for a
+// cause these words do not know.
+import type { CredentialRest, DeferralCause, QuotaCap, Rest, SkippedHop } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { credentialLabel } from './credential.js';
+import { facts, fmtDur, localTime } from './format.js';
+import { pct } from './quota.js';
+
+/** A window's usage in words: `5-hour usage 93%`, `Weekly usage 96%`. */
+function usage(window: string, value: number | null | undefined): string {
+  return window === 'seven_day' ? msg(str`Weekly usage ${pct(value)}`) : msg(str`5-hour usage ${pct(value)}`);
+}
+
+/** A cap as written in the config: `90%`, `0.5%` (a cap is not rounded: 0.5 is not 1). */
+const capPct = (cap: number | null | undefined): string => (cap == null ? '—' : `${Number(cap.toFixed(2))}%`);
+
+/** A cap in words: `limit 90%`. */
+export const capLabel = (cap: number | null | undefined): string => msg(str`limit ${capPct(cap)}`);
+
+/**
+ * Why an identity is paused, its facts after its name:
+ * `5-hour usage 93% | limit 90% | until 10/14 14:30`, or `Usage rule: over the pace`.
+ */
+export function restFacts(r: Rest): string {
+  if (r.rule) return msg(str`Usage rule: ${r.rule}`);
+  return facts(usage(r.window ?? '', r.pct), capLabel(r.cap), r.until ? msg(str`until ${localTime(r.until, true)}`) : '');
+}
+
+/** A paused identity in one line: `Identity personal paused | 5-hour usage 93% | limit 90% | until 10/14 14:30`. */
+export const restLine = (r: Rest): string => facts(msg(str`Identity ${credentialLabel(r.credential)} paused`), restFacts(r));
+
+/** The rests of a cause, one per identity (a pool's members, the hops of one identity). */
+function byIdentity<T extends Rest>(rests: readonly T[]): T[] {
+  const seen = new Set<string>();
+  return rests.filter((r) => !seen.has(r.credential) && seen.add(r.credential));
+}
+
+/**
+ * Why the queue deferred a task, in words: `Past the deadline`, `Past the deadline of topic_work`,
+ * `Identity personal paused | ...`. `recorded`: the run's own sentence, for a cause these words do
+ * not name. `fn`: the function (`module.qualname`) of the flow call whose own deadline it was
+ * (`deferredIn`); '' for the run's. '' for none.
+ */
+export function deferredText(cause: DeferralCause | null | undefined, recorded = '', fn = ''): string {
+  const own = fn ? fn.slice(fn.lastIndexOf('.') + 1) : '';
+  switch (cause?.cause) {
+    case 'deadline':
+      return own ? msg(str`Past the deadline of ${own}`) : msg('Past the deadline');
+    case 'grace_window':
+      return own ? msg(str`Past the deadline of ${own} and its finishing time`) : msg('Past the deadline and its finishing time');
+    case 'cannot_finish':
+      return facts(
+        own ? msg(str`Cannot finish before the deadline of ${own}`) : msg('Cannot finish before the deadline'),
+        cause.need_s != null ? msg(str`needs ${fmtDur(cause.need_s)}`) : '',
+        cause.left_s != null ? msg(str`${fmtDur(cause.left_s)} left`) : '',
+      );
+    case 'dependency_not_queued':
+      return msg('An earlier task was never scheduled');
+    case 'dependency_deferred':
+      return msg('An earlier task was not run');
+    case 'rest': {
+      const rests = byIdentity(cause.rests ?? []);
+      if (!rests.length) return recorded;
+      return rests.length === 1 ? restLine(rests[0]!) : facts(restLine(rests[0]!), msg(str`+${rests.length - 1} paused identities`));
+    }
+    default:
+      return recorded;
+  }
+}
+
+/** The tooltip of a deferral: every paused identity, one per line; '' when there is nothing more to say. */
+export function deferredTip(cause: DeferralCause | null | undefined): string {
+  const rests = cause?.cause === 'rest' ? byIdentity(cause.rests ?? []) : [];
+  return rests.length > 1 ? rests.map(restLine).join('\n') : '';
+}
+
+/** A hop passed over without an agent session, in a model switch: `claude-haiku-5-5 (identity paused)`. */
+export const skippedHopStep = (h: SkippedHop): string => msg(str`${h.model || h.route || '—'} (identity paused)`);
+
+/** One rest of an identity over a run: `Paused 10:31 → 10:45 | 5-hour usage 93% | limit 90%`; still paused: `Paused since 10:31 | ...`. */
+export function restSpan(r: CredentialRest): string {
+  const when = r.ended ? msg(str`Paused ${localTime(r.since)} → ${localTime(r.ended)}`) : msg(str`Paused since ${localTime(r.since)}`);
+  return facts(when, r.rule ? msg(str`Usage rule: ${r.rule}`) : facts(usage(r.window ?? '', r.pct), capLabel(r.cap)));
+}
+
+/** An identity's caps in one line: `Limits: 5-hour 90% | weekly 95%`; '' for none. */
+export function capsLine(c: QuotaCap | undefined): string {
+  if (!c || (c.five_hour_pct == null && c.seven_day_pct == null)) return '';
+  const parts = facts(
+    c.seven_day_pct != null ? msg(str`weekly ${capPct(c.seven_day_pct)}`) : '',
+    c.five_hour_pct != null ? msg(str`5-hour ${capPct(c.five_hour_pct)}`) : '',
+  );
+  return msg(str`Limits: ${parts}`);
+}

package/src/words/rounds.ts

@@ -0,0 +1,56 @@
+import { runRelative } from '@contraagent/api';
+// How a round is named and explained to the reader (render time: msg()).
+import { msg, str } from '@lit/localize';
+import { facts } from './format.js';
+import { attemptLabel } from './attempts.js';
+import { stopLabel } from './stop.js';
+import type { RoundInfo } from '../core/events.js';
+
+/**
+ * "Attempt 1", "Correction 1", "Model switch"; with more than one attempt,
+ * "Attempt 2 | correction 1" and "Attempt 2 | model switch". `name` is the name of
+ * the round's attempt (`attemptNames`: "Attempt 1 | resumed run" in a resumed run).
+ */
+export function roundLabel(r: RoundInfo, tries: number, name = attemptLabel(r.tryNo - 1)): string {
+  if (tries > 1) {
+    if (r.fixupNo) return facts(name, msg(str`correction ${r.fixupNo}`));
+    if (r.hopNo) return facts(name, msg('model switch'));
+    return name;
+  }
+  if (r.fixupNo) return msg(str`Correction ${r.fixupNo}`);
+  if (r.hopNo) return msg('Model switch');
+  return attemptLabel(0);
+}
+
+/** One phrase on what this round was, for its prompt's heading; `resumed`: its attempt is the first of a resumed run. */
+export function roundWhy(r: RoundInfo, resumed = false): string {
+  if (r.fixupNo) return msg('same agent session, after failed checks');
+  if (r.hopNo) return msg('new agent session on the next model');
+  if (r.tryNo > 1 && resumed) return msg('new agent session in the resumed run');
+  if (r.tryNo > 1) return msg(str`new agent session after attempt ${r.tryNo - 1} failed`);
+  return msg('first agent session');
+}
+
+/** A switched round's model, why it stopped, and the next model: `primary-model: rate limited → fallback-model`. */
+export function switchText(r: RoundInfo): string {
+  const from = r.model || msg('model');
+  return r.switchedTo
+    ? msg(str`${from}: ${stopLabel(r.switchedStop)} → ${r.switchedTo}`)
+    : msg(str`${from}: ${stopLabel(r.switchedStop)} → next model`);
+}
+
+/** The ✓ / ✕ mark, its word for screen readers and its tooltip. */
+export function roundMark(r: RoundInfo, run: string): [mark: string, word: string, tip: string] {
+  switch (r.result) {
+    case 'ok':
+      return ['✓', msg('passed'), msg('Output passed checks')];
+    case 'rejected':
+      return ['✕', msg('failed checks'), msg('Output failed checks')];
+    case 'switched':
+      return ['✕', stopLabel(r.switchedStop), switchText(r)];
+    case 'failed':
+      return ['✕', msg('failed'), runRelative(r.row?.reason, run) || stopLabel(r.row?.stop)];
+    default:
+      return ['', '', ''];
+  }
+}

package/src/words/row-extras.ts

@@ -0,0 +1,24 @@
+// Words for a pipeline's own journal columns (`row_extras`): the columns it adds to each
+// attempt's row, named by the pipeline itself.
+import { msg } from '@lit/localize';
+
+/** What such a column is, for a header's tooltip. */
+export const customColumnTip = (): string => msg('Custom column (row_extras)');
+
+/** A custom column's value as text: a string as it is, a number or a boolean as written, anything else as compact JSON; '—' when absent. */
+export function customValue(v: unknown): string {
+  if (v === null || v === undefined || v === '') return '—';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  try {
+    return JSON.stringify(v) ?? '—';
+  } catch {
+    return '—'; // not JSON (a journal row is JSON, so only a hand-built value)
+  }
+}
+
+/** The custom columns `names` of `row` that have a value, as `[name, text]`. */
+export function customValues(row: object, names: readonly string[]): [string, string][] {
+  const r = row as Record<string, unknown>;
+  return names.filter((n) => r[n] !== null && r[n] !== undefined && r[n] !== '').map((n) => [n, customValue(r[n])]);
+}

package/src/words/run-line.ts

@@ -0,0 +1,77 @@
+// The monitor's one-line summaries of a run: the header's run line and the
+// history bar's count.
+import { deriveRun, elapsedS, runAccounts, spendOf, type RunDerived, type RunState, type RunSummary } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { facts, fmtDur, usd } from './format.js';
+import { stateCount } from './outcome.js';
+import { accountsLine } from './quota.js';
+
+/** Each account's latest subscription reading, busiest weekly first: from the live journal once replayed, else the run list's. */
+export const runLineAccounts = (state: RunState, summary: RunSummary) =>
+  state.ready ? runAccounts(state.journal) : (summary.quota ?? []);
+
+/**
+ * The header's run line: tasks that ended well out of all tasks (not attempts),
+ * the tasks that will not run, how long the run took, its cost and usage, running. Before the feed has
+ * replayed, no count: the run list's figures only.
+ */
+export function runLine(state: RunState, summary: RunSummary, derived: RunDerived = deriveRun(state.journal, state.plan)): string {
+  const took = elapsedS(summary);
+  // The live journal is fresher than the run list (polled); before the replay is in, the run list's figure.
+  const spent = state.ready ? spendOf(state.journal)?.cost : summary.cost_usd;
+  const cost = spent !== null && spent !== undefined ? usd(spent) : '';
+  const usage = accountsLine(runLineAccounts(state, summary));
+  const tail = facts(took == null ? '' : msg(str`took ${fmtDur(took)}`), cost, usage, summary.running ? msg('running') : '');
+  if (!state.ready) return tail; // the feed is still replaying: no count yet rather than a wrong one
+  const c = derived.counts;
+  // Tasks deferred, or queued when the run ended: they will not run (the run list counts them).
+  const notRun = summary.tasks.not_run ? stateCount('not_run', summary.tasks.not_run) : '';
+  return facts(msg(str`${c.doneTotal} of ${c.total} tasks done`), notRun, tail);
+}
+
+/** The history bar's count, as the overview counts: "23 attempts | 4 not started". */
+export function triesLine({ tries, notStarted }: RunDerived['tries']): string {
+  return facts(tries === 1 ? msg('1 attempt') : msg(str`${tries} attempts`), notStarted ? stateCount('not_started', notStarted) : '');
+}
+
+/** A stub run's mark (`RunSummary.stub`): its tasks were played by the stub agent. */
+export const stubLabel = (): string => msg('stub agent', { desc: 'A run whose tasks a coding agent with scripted replies played' });
+
+/** What a stub run's mark means, for its tooltip. */
+export const stubTip = (): string => msg('Tasks played by the stub agent with scripted replies (stub)');
+
+/** A replay's mark (`RunSummary.replay`): its agent tasks played their recordings. */
+export const replayLabel = (): string => msg('replay', { desc: 'A run whose agent sessions were played from the recordings of an earlier run' });
+
+/** What a replay's mark means, for its tooltip: where its recordings are. */
+export const replayTip = (dir: string): string => msg(str`Agent sessions played from the recordings in ${dir} (replay)`);
+
+/**
+ * A replay that also launched (`RunSummary.replay` with `stub` false, `record_missing`):
+ * some attempts played their recordings, the others ran and were recorded. Only
+ * then is each played attempt (`JournalRow.replayed`) marked: in a replay that
+ * launched nothing, the run's mark says it of every attempt.
+ */
+export const mixedReplay = (r: Pick<RunSummary, 'stub' | 'replay'> | undefined): boolean => !!r?.replay && !r.stub;
+
+/** A replay that also launched: its mark. */
+export const mixedReplayLabel = (): string =>
+  msg('replay and new sessions', { desc: 'A run that played some attempts from recordings and ran the others as new agent sessions' });
+
+/** What that mark means, for its tooltip: where its recordings are. */
+export const mixedReplayTip = (dir: string): string =>
+  msg(str`Agent sessions played from the recordings in ${dir}, and new agent sessions recorded there (replay, record_missing)`);
+
+/** An attempt played from its recording (`JournalRow.replayed`), in a replay that also launched. */
+export const replayedLabel = (): string => msg('replayed', { desc: 'An attempt played from its recording, not run again' });
+
+/** What that mark means, for its tooltip. */
+export const replayedTip = (): string => msg('Played from a recording (replayed)');
+
+/** The mark beside a run's name: a replay (one that also launched, or not), else a stub run; null for a run of coding agents. */
+export function runMark(r: Pick<RunSummary, 'stub' | 'replay'> | undefined): { text: string; title: string } | null {
+  if (r?.replay && mixedReplay(r)) return { text: mixedReplayLabel(), title: mixedReplayTip(r.replay) };
+  if (r?.replay) return { text: replayLabel(), title: replayTip(r.replay) };
+  if (r?.stub) return { text: stubLabel(), title: stubTip() };
+  return null;
+}

package/src/words/stop.ts

@@ -0,0 +1,65 @@
+// How an attempt ended (a journal row's `stop`), in words.
+import { inputProblems, type Stop } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { isStop } from '../lib/tone.js';
+
+/**
+ * How one attempt ended (a journal row's `stop`), in words. A value contraagent does not write is shown as it is.
+ * With the row's `reason`, a refused input names its problem (missing, or failed checks).
+ */
+export function stopLabel(stop: string | null | undefined, reason?: string | null): string {
+  if (!stop) return '—';
+  return isStop(stop) ? knownStopLabel(stop, reason) : msg(str`unknown (${stop})`);
+}
+
+/** A stop contraagent writes, in words: every `Stop` has a case, or this fails type-checking. */
+function knownStopLabel(stop: Stop, reason?: string | null): string {
+  switch (stop) {
+    case 'completed':
+      return msg('done', { id: 'stop-completed', desc: 'How an attempt ended: completed' });
+    case 'skipped':
+      return msg('skipped');
+    case 'partial':
+      return msg('partly done', { id: 'stop-partial', desc: 'How an attempt ended: partial, its output a placeholder' });
+    case 'invalid_input': {
+      const kinds = new Set(inputProblems(reason).map((p) => p.problem));
+      if (kinds.size === 1 && kinds.has('missing')) return msg('not started (input missing)');
+      if (kinds.size === 1 && kinds.has('checks')) return msg('not started (input failed checks)');
+      if (kinds.size === 1 && kinds.has('failed')) return msg('not started (earlier task failed)');
+      if (kinds.size === 2 && kinds.has('missing') && kinds.has('checks')) return msg('not started (input missing and input failed checks)');
+      return msg('not started', { id: 'stop-invalid-input', desc: 'How an attempt ended: invalid_input, with no input named' });
+    }
+    case 'invalid_output':
+      return msg('failed checks');
+    case 'timeout':
+      return msg('timed out');
+    case 'max_turns':
+      return msg('turn limit reached');
+    case 'budget':
+      return msg('cost limit reached');
+    case 'context_budget':
+      return msg('context limit reached');
+    case 'stalled':
+      return msg('stalled (no events)');
+    case 'auth_failed':
+      return msg('authentication failed');
+    case 'api_error':
+      return msg('API error');
+    case 'rate_limited':
+      return msg('rate limited');
+    case 'refused':
+      return msg('refused by the model');
+    case 'aborted':
+      return msg('aborted');
+    case 'denied':
+      return msg('permission denied');
+    case 'error':
+      return msg('error');
+    case 'no_output':
+      return msg('ended without a result');
+    case 'launch_failed':
+      return msg('agent session did not start');
+    case 'credential_mismatch':
+      return msg('wrong identity used');
+  }
+}

package/src/words/table.ts

@@ -0,0 +1,10 @@
+// The words of a `<cae-data-table>`.
+import type { DataTableStrings } from '@contraagent/elements/data-table';
+import { msg } from '@lit/localize';
+
+/** A table's words; `empty` is what it shows with no rows. */
+export const tableStrings = (empty: string): Required<DataTableStrings> => ({
+  empty,
+  sortAscending: msg('Sort ascending'),
+  sortDescending: msg('Sort descending'),
+});

package/src/words/task-definition.ts

@@ -0,0 +1,37 @@
+// Words for the facts of a task definition that need more than a label: a Python
+// task's retries, the parts of an output file it keeps, another kind's output it writes,
+// the kind it is one implementation of.
+import { msg, str } from '@lit/localize';
+
+/** The label of a Python task's retries. */
+export const retriesLabel = (): string => msg('Retries');
+
+/** A number of retries: `up to 2`. */
+export const retriesText = (n: number): string => msg(str`up to ${n}`, { desc: 'A number of retries' });
+
+/** The label of the exceptions that give a Python task another attempt. */
+export const retriedExceptionsLabel = (): string => msg('Retried exceptions');
+
+/** What they are, for their tooltip. */
+export const retriedExceptionsTip = (): string => msg('Exceptions that give another attempt (retry_on)');
+
+/** The label of the parts of an output file a task must keep as they were (`preserve`). */
+export const preserveLabel = (): string => msg('Must stay unchanged');
+
+/** What they are, for their tooltip. */
+export const preserveTip = (): string => msg('Parts of the output file kept as before the task (preserve)');
+
+/** The output of another kind that a task writes in place of its own (`output_of`): `output of draft`. */
+export const outputOfText = (kind: string): string => msg(str`output of ${kind}`, { desc: "Another kind's output file that this task writes" });
+
+/** What that is, for its tooltip. */
+export const outputOfTip = (): string => msg('The kind whose output file this task writes (output_of)');
+
+/** The label of the kind an implementation kind is one implementation of (`base_kind`). */
+export const implementationOfLabel = (): string => msg('Implementation of', { desc: 'A task definition: the kind that this kind is one implementation of' });
+
+/** An implementation kind, in a list of kinds: `Implementation of review`. */
+export const implementationOfText = (kind: string): string => msg(str`Implementation of ${kind}`);
+
+/** What a base kind is, for its tooltip. */
+export const implementationOfTip = (): string => msg('A kind that other kinds implement (base_kind)');