@contraagent/ui 0.0.0-stage → 0.2.0

package/src/words/api-error.ts

@@ -0,0 +1,17 @@
+// A request to the monitor's API that got no JSON answer, in words: the URL and
+// the cause (render time: msg()).
+import type { ApiError } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+
+/** "No monitor API at http://host/api/runs: the response is HTML, not JSON". */
+export function apiErrorLine({ url, failure, status, type }: ApiError): string {
+  const why =
+    failure === 'network'
+      ? msg('network error, no response')
+      : failure === 'status'
+        ? msg(str`the response status is ${status}`)
+        : type.includes('html')
+          ? msg('the response is HTML, not JSON')
+          : msg('the response is not JSON');
+  return msg(str`No monitor API at ${url}: ${why}`);
+}

package/src/words/attempts.ts

@@ -0,0 +1,28 @@
+// Attempts and corrections, as the reader counts them.
+import { runStarts } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { facts, localTime } from './format.js';
+
+/** What a retry is, for tooltips and the transcript's legend. */
+export const retryTip = (): string => msg('An attempt after a failed attempt (retries)');
+
+/** The attempt as the reader counts it: "Attempt 1", "Attempt 2" ... (`JournalRow.attempt` is 0-based). */
+export const attemptLabel = (attempt: number | null | undefined): string => msg(str`Attempt ${(attempt ?? 0) + 1}`);
+
+/**
+ * The names of one task's attempts that ran (its journal rows in order): "Attempt 1",
+ * and "Attempt 1 | resumed run" for an attempt of a later start of the run (`runStarts`).
+ * Where two names are still the same (a run resumed more than once), each also gets
+ * the time its attempt ended.
+ */
+export function attemptNames(rows: readonly { attempt?: number | null | undefined; ts: string }[]): string[] {
+  const starts = runStarts(rows);
+  const names = rows.map((r, i) => (starts[i] ? facts(attemptLabel(r.attempt), msg('resumed run')) : attemptLabel(r.attempt)));
+  return names.map((n, i) => (names.indexOf(n) === names.lastIndexOf(n) ? n : facts(n, localTime(rows[i]?.ts))));
+}
+
+/** `1 correction`, `3 corrections`; '' for none. */
+export function correctionsText(n: number): string {
+  if (n <= 0) return '';
+  return n === 1 ? msg('1 correction') : msg(str`${n} corrections`);
+}

package/src/words/causes.ts

@@ -0,0 +1,67 @@
+// Why a task waits or did not start, as a phrase that names the cause the data
+// has: the earlier task, the input and what happened to the task that writes it.
+import { inputProblems, isFinished, runRelative, type InputProblem, type Outcome, type TaskOutcome } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { kindUnit } from './format.js';
+
+/**
+ * Why a waiting task has not run, as a phrase that starts in lower case: the
+ * earlier task it waits for (`waits for output of review · zeta`), or how many
+ * (`waits for output of 3 earlier tasks`); '' for none.
+ */
+export function waitCause(waits: readonly { kind?: string | null; unit?: string | null }[]): string {
+  const first = waits[0];
+  if (!first) return '';
+  return waits.length === 1 ? msg(str`waits for output of ${kindUnit(first)}`) : msg(str`waits for output of ${waits.length} earlier tasks`);
+}
+
+/** The task that writes an input, as far as the run knows it. */
+export interface InputSource {
+  /** `kind · unit`. */
+  name: string;
+  /** What happened to it, when known. */
+  outcome?: Outcome | undefined;
+}
+
+/**
+ * Why an input stopped a task, in one phrase that starts in lower case:
+ * `input out/review/zeta.json is missing because review · zeta failed`,
+ * `input out/a.json failed checks`, `input out/review/zeta.json is the output of
+ * failed task review · zeta`. `path` is already shown run-relative.
+ */
+export function inputCause(path: string, problem: InputProblem['problem'], from?: InputSource): string {
+  if (problem === 'failed')
+    return from ? msg(str`input ${path} is the output of failed task ${from.name}`) : msg(str`input ${path} is the output of a failed task`);
+  if (problem === 'checks') return from ? msg(str`input ${path} from ${from.name} failed checks`) : msg(str`input ${path} failed checks`);
+  if (!from) return msg(str`input ${path} is missing`);
+  if (from.outcome === 'failed') return msg(str`input ${path} is missing because ${from.name} failed`);
+  if (from.outcome === 'not_started') return msg(str`input ${path} is missing because ${from.name} did not start`);
+  if (from.outcome && isFinished(from.outcome))
+    return msg(str`input ${path} from ${from.name} is missing`);
+  return msg(str`input ${path} is missing because ${from.name} did not finish`);
+}
+
+/**
+ * Why a task did not start, as a phrase after "Not started: ": the input its
+ * refusal names and why that input is not ready (`input out/review/zeta.json is
+ * missing because review · zeta failed`), or the earlier task that failed and
+ * stopped it (`earlier task review · zeta failed`); '' when the run does not tell.
+ * `writerOf` names the task that writes a path, for a reason that names none.
+ */
+export function notStartedCause(
+  t: Pick<TaskOutcome, 'attempts' | 'cause'>,
+  outcomes: ReadonlyMap<string, TaskOutcome>,
+  run: string,
+  writerOf?: (path: string) => string | undefined,
+): string {
+  const last = t.attempts[t.attempts.length - 1];
+  if (last?.stop === 'invalid_input') {
+    const p = inputProblems(last.reason)[0];
+    if (!p) return runRelative(last.reason, run);
+    const key = p.producer || writerOf?.(p.path) || '';
+    const w = key ? outcomes.get(key) : undefined;
+    return inputCause(runRelative(p.path, run), p.problem, w ? { name: kindUnit(w), outcome: w.outcome } : undefined);
+  }
+  const c = t.cause ? outcomes.get(t.cause) : undefined;
+  return c ? msg(str`earlier task ${kindUnit(c)} failed`) : '';
+}

package/src/words/changes.ts

@@ -0,0 +1,29 @@
+// Words for a task's changes: the files an attempt created, modified or deleted under
+// the patterns its task declares (`changes` in a journal row).
+import { msg, str } from '@lit/localize';
+
+/** What happened to one file in one attempt. `removed`: it created the file, and the file was removed because the attempt failed; `kept`: it created the file, and the file stayed though the attempt failed (`keep_failed_changes`). */
+export type ChangeKind = 'created' | 'modified' | 'deleted' | 'removed' | 'kept';
+
+/** `1 changed file`, `3 changed files`. */
+export const changedFiles = (n: number): string => (n === 1 ? msg('1 changed file') : msg(str`${n} changed files`));
+
+/** What a task's changed files are, for a tooltip. */
+export const changedFilesTip = (): string =>
+  msg("Files under the task's declared patterns that its attempts created, modified or deleted (changes)");
+
+/** What happened to a file, in words. */
+export function changeLabel(kind: ChangeKind): string {
+  switch (kind) {
+    case 'created':
+      return msg('created');
+    case 'modified':
+      return msg('modified');
+    case 'deleted':
+      return msg('deleted');
+    case 'removed':
+      return msg('created, removed after the failed attempt');
+    case 'kept':
+      return msg('created, kept after the failed attempt');
+  }
+}

package/src/words/claims.ts

@@ -0,0 +1,16 @@
+// Words for a task's claims: the names it holds while it runs (`claims`), shown as its locks.
+import { msg, str } from '@lit/localize';
+import { facts, listText } from './format.js';
+
+/** The label before a task's claims. */
+export const locksLabel = (): string => msg('Locks');
+
+/** What a task's claims are, for a tooltip. */
+export const locksTip = (): string => msg('Names this task holds while it runs (claims)');
+
+/** A task's claims in a row of the tasks list: by name, or how many when more than two. */
+export const locksShort = (names: readonly string[]): string =>
+  names.length > 2 ? msg(str`Locks ${names.length} names`) : msg(str`Locks ${listText(names)}`);
+
+/** The tooltip of `locksShort`: what they are, and every name. */
+export const locksNames = (names: readonly string[]): string => facts(locksTip(), listText(names));

package/src/words/context.ts

@@ -0,0 +1,47 @@
+// Words for the peak context: the whole input of the largest API call of an attempt
+// (`usage.peak_context`), against its kind's context limit (`context_budget`).
+import type { JournalRow } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { facts, tokenCount } from './format.js';
+
+/** The label before a peak context. */
+export const peakContextLabel = (): string => msg('Peak context');
+
+/** What a peak context is, for its tooltip. */
+export const peakContextTip = (): string => msg('Largest input of one API call, cache read and cache write included (peak_context)');
+
+/** A peak context, then its share of the context limit when one is set: `142k | 71% of the context limit 200k`. */
+export function peakContextText(peak: number, budget?: number | null): string {
+  const share = budget ? Math.round((100 * peak) / budget) : null;
+  return facts(tokenCount(peak), share === null ? '' : msg(str`${share}% of the context limit ${tokenCount(budget)}`));
+}
+
+/** An attempt's peak context with its label (`Peak context: 142k | 71% of ...`); '' when it reported none. */
+export function peakContextLine(r: Pick<JournalRow, 'usage' | 'context_budget'>): string {
+  const peak = r.usage?.peak_context;
+  return peak == null ? '' : msg(str`Peak context: ${peakContextText(peak, r.context_budget)}`);
+}
+
+/** The state of an attempt whose peak context passed the warning share of its context limit (`context_warned`). */
+export const contextWarnedLabel = (): string => msg('near the context limit');
+
+/** That state with the share of the limit when known: `near the context limit (91%)`. */
+export function contextWarnedText(r: Pick<JournalRow, 'usage' | 'context_budget'>): string {
+  const peak = r.usage?.peak_context;
+  const budget = r.context_budget;
+  if (peak == null || !budget) return contextWarnedLabel();
+  return msg(str`near the context limit (${Math.round((100 * peak) / budget)}%)`);
+}
+
+/** What that state means, for its tooltip. */
+export const contextWarnedTip = (): string => msg('Peak context above the warning threshold (context_warned)');
+
+/** Of `tries`, the one with the largest peak context; null when none reported one. */
+export function peakTry<T extends Pick<JournalRow, 'usage'>>(tries: readonly T[]): T | null {
+  let best: T | null = null;
+  for (const r of tries) {
+    const p = r.usage?.peak_context;
+    if (p != null && (best === null || p > (best.usage?.peak_context ?? 0))) best = r;
+  }
+  return best;
+}

package/src/words/contract.ts

@@ -0,0 +1,63 @@
+// A contract file's status and its causes, in words (the UI says "checked
+// file"; packages/ui/WORDS.md).
+import { inputProblems, runRelative, type ContractSpec, type ContractStatus, type Outcome } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { inputCause } from './causes.js';
+import { sentence } from './format.js';
+
+/** A contract status in words, in the current locale. */
+export function contractStatusLabel(s: ContractStatus): string {
+  switch (s) {
+    case 'valid':
+      return msg('passed');
+    case 'invalid':
+      return msg('failed checks');
+    case 'refused':
+      return msg('not written (task not started)');
+    case 'failed':
+      return msg('not written (task failed)');
+    case 'running':
+      return msg('not written yet (task running)');
+    case 'pending':
+      return msg('not written yet (task waiting)');
+  }
+}
+
+/** A fact a contract's status word does not say, for its tooltip; '' when the word says it all. */
+export function contractStatusWhy(s: ContractStatus): string {
+  return s === 'failed' ? msg('The task failed before it wrote a file that passes its checks') : '';
+}
+
+/** What a correction is, for tooltips. */
+export const correctionTip = (): string => msg('Another round in the same agent session after failed checks (rounds)');
+
+/** How many corrections a file took (`rounds` counts the first round too), in words; '' for none. */
+export function correctionsLabel(rounds: number | null | undefined, passed: boolean): string {
+  const n = (rounds ?? 1) - 1;
+  if (n < 1) return '';
+  if (passed) return n === 1 ? msg('after 1 correction') : msg(str`after ${n} corrections`);
+  return n === 1 ? msg('1 correction') : msg(str`${n} corrections`);
+}
+
+/** Who writes a file, for naming the task an input should have come from. */
+export interface Producer {
+  /** "kind · unit" of the task that writes it. */
+  name: string;
+  /** The file exists now. */
+  written: boolean;
+  /** What happened to that task, when known. */
+  outcome?: Outcome | undefined;
+}
+
+/**
+ * Why a task never ran, in one line beside its status: the input it was refused
+ * for (from its check errors) and, when known, the task that should have written it;
+ * '' when the run records no input error.
+ */
+export function notRunText(o: ContractSpec, run: string, producerOf?: (path: string) => Producer | undefined): string {
+  const errors = o.errors ?? [];
+  const p = inputProblems(`invalid input: ${errors.map((e) => e.replace(/^invalid input:\s*/, '')).join('; ')}`)[0];
+  if (!p) return errors[0] ? sentence(runRelative(errors[0], run)) : '';
+  const from = producerOf?.(p.path);
+  return sentence(inputCause(runRelative(p.path, run), p.problem, from));
+}

package/src/words/credential.ts

@@ -0,0 +1,8 @@
+// A credential as the reader knows it (shown as "identity").
+import { msg } from '@lit/localize';
+
+/** A credential as the reader knows it: the built-in `ambient` shows as "default". */
+export const credentialLabel = (c: string | null | undefined): string => (!c ? '' : c === 'ambient' ? msg('default') : c);
+
+/** What a credential's label leaves out, for its tooltip: the built-in `ambient` is the local credentials. */
+export const credentialTip = (c: string | null | undefined): string => (c === 'ambient' ? msg('local credentials (ambient)') : '');

package/src/words/executor.ts

@@ -0,0 +1,22 @@
+// What ran a task, as a small icon before its name: ✦ an agent task, ⚙ a Python task.
+import { icon } from '@contraagent/elements/primitives';
+import { css, type TemplateResult } from 'lit';
+
+/** The glyph of who runs a task. */
+export const executorGlyph = (python: boolean): string => (python ? '⚙' : '✦');
+
+/**
+ * Who ran a task, as an icon (`.k-ic`, `.k-ic.llm` for an agent task, unless `cls`
+ * names other classes). With a label, the label is its tooltip and what a screen
+ * reader reads; without one, it is hidden from screen readers.
+ */
+export function executorIcon(python: boolean, label?: string | null, cls?: string): TemplateResult {
+  return icon(executorGlyph(python), label, { cls: cls ?? `k-ic ${python ? '' : 'llm'}` });
+}
+
+/** Who ran it (identity, a small cue): `.k-ic` for a Python task, `.k-ic.llm` for an agent task. */
+export const executorIconStyles = css`
+  .k-ic { display: inline-grid; place-items: center; width: 20px; height: 20px; border-radius: 6px; margin-right: 7px;
+    font-size: var(--font-size-sm); background: var(--raise); color: var(--text-muted); flex: none; }
+  .k-ic.llm { background: var(--agent-bg); color: var(--agent); }
+`;

package/src/words/export.ts

@@ -0,0 +1,22 @@
+// Words for an export (`contraagent monitor export`, `Info.export`): the monitor
+// read from files, with no server.
+import type { ExportInfo } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { listText, localTime } from './format.js';
+
+/** The header's mark of an export: when it was written. */
+export const exportedLabel = (e: ExportInfo): string =>
+  msg(str`Exported ${localTime(e.exported_at, true)}`, { desc: 'The monitor shows files written at this time, not a live server' });
+
+/** A view an export does not hold, in words. */
+function leftOutLabel(view: string): string {
+  if (view === 'transcripts') return msg('transcripts');
+  if (view === 'processes') return msg('processes');
+  return view;
+}
+
+/** What the export does not hold, for the mark's tooltip: "Not in this export: transcripts, processes". */
+export const exportTip = (e: ExportInfo): string => msg(str`Not in this export: ${listText(e.left_out.map(leftOutLabel))}`);
+
+/** Beside an empty view: what it would show is not in the export. */
+export const notInExport = (): string => msg('not in this export');

package/src/words/format.ts

@@ -0,0 +1,107 @@
+// Durations, times and small text helpers shared by the views.
+import { msg, str } from '@lit/localize';
+import { getLocale } from '../core/i18n.js';
+
+// The formats that read the same in every language are the generic package's.
+export { esc, fmtDur } from '@contraagent/elements';
+
+const formats = new Map<string, Intl.DateTimeFormat>();
+function formatter(locale: string, withDate: boolean): Intl.DateTimeFormat {
+  const id = `${locale}|${withDate}`;
+  let f = formats.get(id);
+  if (!f) {
+    f = new Intl.DateTimeFormat(locale, {
+      ...(withDate ? { month: 'short', day: 'numeric' } : {}),
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+    });
+    formats.set(id, f);
+  }
+  return f;
+}
+
+/**
+ * An ISO time in the reader's time zone, as the UI locale writes it: `10:38:40`,
+ * or with the date `Oct 12, 10:38:40` (the month as a word, so no reader takes
+ * the day for the month). '' when there is no time.
+ */
+export function localTime(ts: string | null | undefined, withDate = false, locale: string = getLocale()): string {
+  if (!ts) return '';
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return ts;
+  return formatter(locale, withDate).format(d);
+}
+
+/** An ISO time as `just now`, `5m ago`, `3h ago`, `2d ago` (the run picker only; rows and chips show `localTime`). */
+export function relAgo(iso: string | null | undefined, now = Date.now()): string {
+  const t = Date.parse(iso || '');
+  if (Number.isNaN(t)) return '';
+  const s = Math.max(0, (now - t) / 1000);
+  if (s < 60) return msg('just now');
+  if (s < 3600) return msg(str`${Math.floor(s / 60)}m ago`);
+  if (s < 86400) return msg(str`${Math.floor(s / 3600)}h ago`);
+  return msg(str`${Math.floor(s / 86400)}d ago`);
+}
+
+/** `s` as a sentence on its own: its first letter upper-cased (a phrase that also follows a colon starts lower case). */
+export const sentence = (s: string): string => s.charAt(0).toLocaleUpperCase(getLocale()) + s.slice(1);
+
+/** The facts of one row, chip or line, in order, without the empty ones (for `factLine`). */
+export const factList = (...xs: (string | null | undefined | false)[]): string[] => xs.filter((x): x is string => !!x);
+
+/** Facts of one row, chip or line, in order: `attempt 1 | done | 0.2s`. Empty facts are left out. */
+export const facts = (...xs: (string | null | undefined | false)[]): string => factList(...xs).join(' | ');
+
+const lists = new Map<string, Intl.ListFormat>();
+
+/**
+ * Words a reader reads as a list, as the UI locale writes one: `Pass 1, Pass 2, and Pass 3`
+ * in English, `1 周目、2 周目、3 周目` in Japanese. Codes and identifiers are joined with `, ` instead.
+ */
+export function listText(items: readonly string[], locale: string = getLocale()): string {
+  let f = lists.get(locale);
+  if (!f) {
+    f = new Intl.ListFormat(locale, { type: 'conjunction' });
+    lists.set(locale, f);
+  }
+  return f.format(items);
+}
+
+/** `kind · unit`, or the bare kind for a run-scope task. */
+export const kindUnit = (x: { kind?: string | null | undefined; unit?: string | null | undefined }, sep = ' · '): string =>
+  `${x.kind ?? ''}${x.unit ? sep + x.unit : ''}`;
+
+/** The first line of a text, cut at 100 characters. */
+export function firstLine(s: string | null | undefined): string {
+  const t = (s || '').trim();
+  if (!t) return '';
+  const l = (t.split('\n')[0] || '').trim();
+  return l.length > 100 ? `${l.slice(0, 100)}…` : l;
+}
+
+/** A token count, compact: `950`, `1.2k`, `34k`, `1.3M`. */
+export function tokenCount(n: number | null | undefined): string {
+  const v = n ?? 0;
+  if (v < 1000) return String(Math.round(v));
+  if (v < 10_000) return `${(v / 1000).toFixed(1).replace(/\.0$/, '')}k`;
+  if (v < 1_000_000) return `${Math.round(v / 1000)}k`;
+  return `${(v / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+}
+
+/** A cost in USD: `$0.041`, `$1.23`, `<$0.001`; '—' when none was reported. */
+export function usd(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '—';
+  if (v === 0) return '$0';
+  if (v < 0.001) return '<$0.001';
+  if (v < 1) return `$${v.toFixed(3)}`; // fixed decimals, so columns of costs line up
+  return `$${v.toFixed(2)}`;
+}
+
+/** A row's unread event types with their counts (`session_settled ×2, x ×1`); '' when none. */
+export function unreadEvents(rows: readonly { unread_events?: Record<string, number> | null }[]): string {
+  const total = new Map<string, number>();
+  for (const r of rows) for (const [k, n] of Object.entries(r.unread_events ?? {})) total.set(k, (total.get(k) ?? 0) + n);
+  return [...total].map(([k, n]) => `${k} ×${n}`).join(', ');
+}

package/src/words/hops.ts

@@ -0,0 +1,30 @@
+// A model switch (the hops of one attempt), in words.
+import type { Hop, SkippedHop } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { fmtDur } from './format.js';
+import { skippedHopStep } from './rests.js';
+import { stopLabel } from './stop.js';
+
+/** What a model switch is, for tooltips and the transcript's legend. */
+export const modelSwitchTip = (): string => msg('A new agent session on the next model after a failed one (Router hops)');
+
+/** One hop's model, or its route when the journal names no model. */
+const hopModel = (h: Pick<Hop, 'model' | 'route'>): string => h.model || h.route || '—';
+
+/**
+ * A model switch in words, the one form every view uses:
+ * `primary-model (rate limited) → fallback-model`; '' for a single hop.
+ * The hops passed over without an agent session (`skipped`: their identity was
+ * paused) come first: `primary-model (identity paused) → fallback-model`.
+ * With `time`, the attempt's time follows: `... → fallback-model | 0.2s`.
+ */
+export function modelSwitch(hops: readonly Hop[] | null | undefined, time?: number | null, skipped?: readonly SkippedHop[] | null): string {
+  const passed = [...new Map((skipped ?? []).map((h) => [h.route || h.model, h])).values()];
+  if (!hops || hops.length + passed.length < 2 || !hops.length) return '';
+  const steps = [
+    ...passed.map(skippedHopStep),
+    ...hops.map((h, i) => (i < hops.length - 1 ? msg(str`${hopModel(h)} (${stopLabel(h.stop)})`) : hopModel(h))),
+  ];
+  const chain = steps.join(' → ');
+  return time === undefined || time === null ? chain : `${chain} | ${fmtDur(time)}`;
+}

package/src/words/hosts.ts

@@ -0,0 +1,37 @@
+// Words for the hosts behind a hub's runs (`Info.hosts`): a host's state, its
+// last report, its runs, and a run whose host stopped reporting. The code's
+// terms (`up`, `last_seen`, `unresponsive`) stay in the data and in tooltips.
+import type { HostSummary } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { facts, localTime } from './format.js';
+
+/** A run whose host stopped reporting (`RunSummary.unresponsive`), as a status value. */
+export const noReportLabel = (): string => msg('no report from host');
+
+/** A host's state: `up`, or `no report` (its reports stopped, or it never reported). */
+export const hostStateLabel = (h: Pick<HostSummary, 'up'>): string =>
+  h.up ? msg('up', { desc: 'A host whose reports keep arriving' }) : msg('no report');
+
+/** A host's state with the time of its last report where one is known: `no report since Oct 13, 10:41:03`. */
+export const hostStateSince = (h: Pick<HostSummary, 'up' | 'last_seen'>): string =>
+  !h.up && h.last_seen ? msg(str`no report since ${localTime(h.last_seen, true)}`) : hostStateLabel(h);
+
+/** When a host last reported: `Last report Oct 13, 10:41:03`; '' when it never did. */
+export const lastReport = (h: Pick<HostSummary, 'last_seen'> | undefined): string =>
+  h?.last_seen ? msg(str`Last report ${localTime(h.last_seen, true)}`) : '';
+
+/** A host's id as a fact: `Host h1`; for a run whose run.json names none, `No host id`. */
+export const hostFact = (id: string): string => (id ? msg(str`Host ${id}`) : msg('No host id'));
+
+/** How many runs: `1 run`, `4 runs`. */
+export const runCount = (n: number): string => (n === 1 ? msg('1 run') : msg(str`${n} runs`));
+
+/** How many runs have no report from their host: `1 with no report from host`. */
+export const noReportCount = (n: number): string => msg(str`${n} with no report from host`);
+
+/** The hosts in one line: `2 hosts | 1 with no report`. */
+export function hostsLine(hosts: readonly Pick<HostSummary, 'up'>[]): string {
+  const quiet = hosts.filter((h) => !h.up).length;
+  return facts(hosts.length === 1 ? msg('1 host') : msg(str`${hosts.length} hosts`), quiet ? msg(str`${quiet} with no report`) : '');
+}
+

package/src/words/index.ts

@@ -0,0 +1,31 @@
+// The words the UI shows for run data, in the reader's terms. The code's own
+// terms (stop values, plan states, round, hop, attempt ...) stay in the data and
+// in tooltips; what the reader sees comes from here, so every screen says the
+// same thing for the same state. The mapping is listed in packages/ui/WORDS.md.
+export * from './format.js';
+export * from './outcome.js';
+export * from './stop.js';
+export * from './causes.js';
+export * from './attempts.js';
+export * from './passes.js';
+export * from './credential.js';
+export * from './hops.js';
+export * from './quota.js';
+export * from './contract.js';
+export * from './run-line.js';
+export * from './hosts.js';
+export * from './table.js';
+export * from './changes.js';
+export * from './claims.js';
+export * from './rests.js';
+export * from './services.js';
+export * from './time-box.js';
+export * from './row-extras.js';
+export * from './models.js';
+export * from './panels.js';
+export * from './export.js';
+export * from './trends.js';
+export * from './priority.js';
+export * from './context.js';
+export * from './preflight.js';
+export * from './task-definition.js';

package/src/words/models.ts

@@ -0,0 +1,50 @@
+// Words for what each model was used for in a run (`Plan.models`).
+import type { ModelMeasure, ModelUsage } from '@contraagent/api';
+import { modelTokens } from '@contraagent/api';
+import { msg } from '@lit/localize';
+import { fmtDur, tokenCount, usd } from './format.js';
+
+/** A measure's name: the name of the column it is in, too. */
+export function measureLabel(m: ModelMeasure): string {
+  switch (m) {
+    case 'cost':
+      return msg('Cost');
+    case 'tokens':
+      return msg('Tokens');
+    case 'time':
+      return msg('Time');
+    case 'sessions':
+      return msg('Agent sessions');
+  }
+}
+
+/** What a measure counts, for its tooltip. */
+export function measureTip(m: ModelMeasure): string {
+  switch (m) {
+    case 'cost':
+      return msg('Reported by the coding agent');
+    case 'tokens':
+      return msg('Input, output, cache read and cache write');
+    case 'time':
+      return msg('Time of the agent sessions, summed');
+    case 'sessions':
+      return msg('Agent sessions started on the model');
+  }
+}
+
+/** A model's amount of `measure` in words: `$0.12`, `12.3k`, `2m 05s`, `4`; '—' for no cost reported. */
+export function measureText(u: ModelUsage, m: ModelMeasure): string {
+  switch (m) {
+    case 'cost':
+      return u.cost_usd === null || u.cost_usd === undefined ? '—' : usd(u.cost_usd);
+    case 'tokens':
+      return tokenCount(modelTokens(u));
+    case 'time':
+      return fmtDur(u.wall_s ?? 0);
+    case 'sessions':
+      return String(u.sessions);
+  }
+}
+
+/** The name the parts of a share past the colours fold into. */
+export const otherModels = (): string => msg('Other models');

package/src/words/outcome.ts

@@ -0,0 +1,61 @@
+// A task's outcome in words: its status, a count of tasks in a state, a plan
+// state. The code's terms (`recovered`, `blocked`) stay in the data and in
+// tooltips; the words are the reader's (packages/ui/WORDS.md).
+import { planOutcome, type Outcome, type PlanNode } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+
+/** What happened to a task. */
+export function outcomeLabel(o: Outcome): string {
+  switch (o) {
+    case 'done':
+      return msg('done', { id: 'outcome-done', desc: 'The status of a task: done' });
+    case 'recovered':
+      return msg('done after retrying');
+    case 'partial':
+      return msg('partly done', { id: 'outcome-partial', desc: 'The status of a task whose output is a placeholder: a service it needed was unavailable (partial)' });
+    case 'failed':
+      return msg('failed');
+    case 'not_started':
+      return msg('not started');
+    case 'running':
+      return msg('running');
+    case 'waiting':
+      return msg('waiting');
+    case 'skipped':
+      return msg('skipped');
+  }
+}
+
+/** What happened to a task, in a run that is `live` or over: a task still waiting when the run ended is "not run". */
+export const taskStatusLabel = (o: Outcome, live: boolean): string => (o === 'waiting' && !live ? msg('not run') : outcomeLabel(o));
+
+/** A plan node's state (the task matrix, progress by kind). */
+export const planStateLabel = (s: PlanNode['state']): string => outcomeLabel(planOutcome(s));
+
+/**
+ * How many tasks are in a state, number first: "3 failed", "2 not started".
+ * A count only: a cause ("review · zeta failed") has its own message.
+ * `not_run`: waiting when the run ended.
+ */
+export function stateCount(s: Outcome | 'not_run', n: number): string {
+  switch (s) {
+    case 'done':
+      return msg(str`${n} done`);
+    case 'recovered':
+      return msg(str`${n} done after retrying`);
+    case 'partial':
+      return msg(str`${n} partly done`);
+    case 'failed':
+      return msg(str`${n} failed`);
+    case 'not_started':
+      return msg(str`${n} not started`);
+    case 'running':
+      return msg(str`${n} running`);
+    case 'waiting':
+      return msg(str`${n} waiting`);
+    case 'skipped':
+      return msg(str`${n} skipped`);
+    case 'not_run':
+      return msg(str`${n} not run`);
+  }
+}