@contraagent/ui 0.0.0-stage → 0.1.0

package/src/adapters/lanes.ts

@@ -0,0 +1,98 @@
+// The timeline (`ca-timeline`) as the lanes of `<cae-lanes>`: every attempt as
+// a bar as long as it took, on its kind's lane, the running ones growing until
+// now. Pure.
+import { isLaunched, isPython, runRelative, type JournalRow, type TaskOutcome } from '@contraagent/api';
+import type { Lane, LaneBar, LaneStyle } from '@contraagent/elements/lanes';
+import { msg, str } from '@lit/localize';
+import { getLocale } from '../core/i18n.js';
+import { facts, fmtDur, kindUnit } from '../words/format.js';
+import { modelSwitch, notStartedCause, stopLabel } from '../words/index.js';
+
+/** Finished tasks older than this before the newest are left out. */
+export const TIMELINE_WINDOW_MS = 6 * 3600e3;
+
+/** Something running now, as the timeline draws it. */
+export interface LiveBar {
+  kind: string;
+  cls: 'llm' | 'py';
+  /** Epoch ms it started. */
+  t0: number;
+}
+
+/** A bar's look: `py`, `llm`, `bad` (ran and failed), `idle` (a task that never started), `run` (running). */
+export type LaneStyleKey = 'py' | 'llm' | 'bad' | 'idle' | 'run';
+
+export interface TimelineLanes {
+  lanes: Lane[];
+  /** Finished tasks left out of the window. */
+  omitted: number;
+}
+
+const hhmmss = (t: number) => new Date(t).toLocaleTimeString(getLocale(), { hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' });
+
+/**
+ * The bars' looks and the legend: who ran it is an identity cue (Python
+ * neutral, an agent violet), on the first row; failed and running are
+ * statuses, each with a pattern besides the colour, on the second.
+ */
+export function laneStyles(): Record<LaneStyleKey, LaneStyle> {
+  return {
+    py: { label: msg('Python task'), color: 'var(--meter)' },
+    llm: { label: msg('Agent task'), color: 'var(--agent)' },
+    run: { label: msg('running'), color: 'var(--status-running)', pattern: 'striped', group: 1 },
+    bad: { label: msg('failed'), color: 'var(--status-failed)', pattern: 'hatched', group: 1 },
+    idle: { label: msg('not started'), color: 'var(--line2)', pattern: 'outline', group: 1 },
+  };
+}
+
+/** A finished row's tooltip, one item per line: its name, how it ended, its time, its model, why it failed. */
+function rowLabel(e: JournalRow, end: number, outcomes: ReadonlyMap<string, TaskOutcome>, run: string): string {
+  // A task that never ran: its name and why, and no time, end or model.
+  if (!isLaunched(e)) {
+    const t = outcomes.get(e.key);
+    const cause = e.stop === 'invalid_input' && t ? notStartedCause(t, outcomes, run) : '';
+    return [kindUnit(e), cause ? msg(str`Not started: ${cause}`) : stopLabel(e.stop, e.reason), e.key].join('\n');
+  }
+  const sw = modelSwitch(e.hops, null, e.skipped_hops);
+  const reason = e.reason && !e.ok ? runRelative(e.reason, run) : '';
+  // One item per line: a task's name holds a `·` of its own.
+  return [
+    kindUnit(e),
+    facts(stopLabel(e.stop), fmtDur(e.wall_s), msg(str`ended ${hhmmss(end)}`)),
+    sw ? msg(str`Model switch: ${sw}`) : e.model ? msg(str`Model ${e.model}`) : '',
+    reason,
+    e.key,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Every finished task as a bar on its kind's lane, in order of first start,
+ * and the running ones (`end` null); finished tasks that ended more than six
+ * hours before the newest are left out. Null when there is nothing to draw.
+ */
+export function lanesFromJournal(
+  journal: readonly JournalRow[],
+  live: readonly LiveBar[],
+  outcomes: ReadonlyMap<string, TaskOutcome>,
+  run: string,
+): TimelineLanes | null {
+  /** Each finished row's bar, on its lane. */
+  const bars: { lane: string; bar: LaneBar & { end: number } }[] = [];
+  journal.forEach((e, i) => {
+    if (!e.ts) return;
+    const end = Date.parse(e.ts);
+    if (Number.isNaN(end)) return;
+    const style: LaneStyleKey = !isLaunched(e) ? 'idle' : !e.ok ? 'bad' : isPython(e) ? 'py' : 'llm';
+    bars.push({ lane: e.kind || '?', bar: { id: `j${i}`, style, start: end - (e.wall_s || 0) * 1000, end, label: rowLabel(e, end, outcomes, run) } });
+  });
+  if (!bars.length && !live.length) return null;
+  const newest = Math.max(...bars.map((x) => x.bar.end), ...live.map((a) => a.t0));
+  const vis: { lane: string; bar: LaneBar }[] = bars.filter((x) => x.bar.end >= newest - TIMELINE_WINDOW_MS);
+  const omitted = bars.length - vis.length;
+  live.forEach((a, i) => vis.push({ lane: a.kind, bar: { id: `live${i}`, style: 'run', start: a.t0, end: null, label: `${a.kind}\n${msg('running')}` } }));
+  const lanes = new Map<string, LaneBar[]>();
+  for (const { lane, bar } of [...vis].sort((a, b) => a.bar.start - b.bar.start)) (lanes.get(lane) ?? lanes.set(lane, []).get(lane)!).push(bar);
+  return { lanes: [...lanes].map(([name, bs]) => ({ id: name, label: name, bars: bs })), omitted };
+}

package/src/adapters/model-shares.ts

@@ -0,0 +1,62 @@
+// A run's models (`Plan.models`) → the share bar's parts and the rows of the table
+// beside it, for one measure (cost, tokens, time, agent sessions).
+import { modelValue, type ModelMeasure, type ModelUsage } from '@contraagent/api';
+import { wholePercents, sharePercent, type SharePart } from '@contraagent/elements/primitives';
+import { measureText, otherModels } from '../words/models.js';
+
+/** The series colours (`--series-1` ...), in their order. */
+export const SERIES_COLOURS = 6;
+
+/** The colour the models past the series colours share. */
+export const OTHER_COLOUR = 'var(--meter)';
+
+/** A model's identity: its coding agent and its name. */
+export const modelId = (m: Pick<ModelUsage, 'agent' | 'model'>): string => `${m.agent}/${m.model}`;
+
+/**
+ * Each model's colour, by the order of first use (the order of `models`): the first
+ * six take the series colours; with more than six, the sixth and later share the
+ * colour of "other models". A model keeps its colour whatever the measure, and
+ * whatever its rank.
+ */
+export function modelColours(models: readonly ModelUsage[]): Map<string, string> {
+  const own = models.length > SERIES_COLOURS ? SERIES_COLOURS - 1 : SERIES_COLOURS;
+  return new Map(models.map((m, i) => [modelId(m), i < own ? `var(--series-${i + 1})` : OTHER_COLOUR]));
+}
+
+/** The share bar's parts for `measure`: one per model with a colour of its own, the rest folded into one. */
+export function shareParts(models: readonly ModelUsage[], measure: ModelMeasure): SharePart[] {
+  const colours = modelColours(models);
+  const parts: SharePart[] = [];
+  let other = 0;
+  for (const m of models) {
+    const value = modelValue(m, measure) ?? 0;
+    const colour = colours.get(modelId(m))!;
+    if (colour === OTHER_COLOUR) other += value;
+    else parts.push({ id: modelId(m), label: m.model, value, color: colour, text: measureText(m, measure) });
+  }
+  if (models.length > SERIES_COLOURS) parts.push({ id: 'other', label: otherModels(), value: other, color: OTHER_COLOUR });
+  return parts;
+}
+
+export interface ModelRow {
+  id: string;
+  usage: ModelUsage;
+  colour: string;
+  /** The model's share of `measure` in words (`42%`, `<1%`); '—' when nothing was measured. */
+  share: string;
+}
+
+/** One row per model, in the order of first use, with its share of `measure`. */
+export function modelRows(models: readonly ModelUsage[], measure: ModelMeasure): ModelRow[] {
+  const colours = modelColours(models);
+  const values = models.map((m) => modelValue(m, measure) ?? 0);
+  const pcts = wholePercents(values);
+  const measured = values.some((v) => v > 0);
+  return models.map((m, i) => ({
+    id: modelId(m),
+    usage: m,
+    colour: colours.get(modelId(m))!,
+    share: measured ? sharePercent(pcts[i]!, values[i]!) : '—',
+  }));
+}

package/src/adapters/panel-body.ts

@@ -0,0 +1,74 @@
+// A pipeline's own view (`monitor.Panel`) → what the generic elements take: a table
+// body's columns and rows for `<cae-data-table>`, its tiles for `<cae-stat-tiles>`.
+import type { PanelTile, TableBody, TableColumn } from '@contraagent/api';
+import type { DataColumn } from '@contraagent/elements/data-table';
+import type { StatTile } from '@contraagent/elements/tiles';
+import type { Tone } from '@contraagent/elements';
+import { html } from 'lit';
+import { cellText } from '../words/panels.js';
+
+/** A row of a table body: a value per column id, and its status (`_tone`). */
+export type BodyRow = Readonly<Record<string, unknown>> & { _tone?: Tone | null };
+
+const TONES: readonly string[] = ['failed', 'attention', 'done', 'running', 'muted', 'neutral'];
+
+/** A row's status, when it names one the monitor knows. */
+export const rowTone = (r: BodyRow): Tone | undefined => (typeof r._tone === 'string' && TONES.includes(r._tone) ? r._tone : undefined);
+
+/** The formats of numbers: their columns are right-aligned. */
+const NUMERIC = new Set(['usd', 'pct', 'duration', 'tokens', 'number']);
+
+/** A cell as the text it is ordered by. */
+const cellKey = (v: unknown): string => (typeof v === 'string' ? v : JSON.stringify(v));
+
+/** The order of two cells: numbers by value, then text; empty cells last. */
+function compareCells(a: unknown, b: unknown): number {
+  const empty = (v: unknown) => v === null || v === undefined || v === '';
+  if (empty(a) || empty(b)) return empty(a) === empty(b) ? 0 : empty(a) ? 1 : -1;
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return cellKey(a).localeCompare(cellKey(b));
+}
+
+/** `v` as a URL a cell may lead to: http or https only; null for anything else. */
+export function cellUrl(v: unknown): string | null {
+  if (typeof v !== 'string' || !/^https?:\/\//i.test(v.trim())) return null;
+  try {
+    const u = new URL(v.trim());
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The columns of a table body: each cell written by its column's format, a number
+ * right-aligned, a `bar` column with a bar, a `link` column a link to its row's URL.
+ */
+export function bodyColumns(body: TableBody): DataColumn<BodyRow>[] {
+  return body.columns.map((c: TableColumn, i): DataColumn<BodyRow> => {
+    const numeric = c.format ? NUMERIC.has(c.format) : body.rows.some((r) => typeof (r as BodyRow)[c.id] === 'number');
+    const top = c.bar ? Math.max(0, ...body.rows.map((r) => Number((r as BodyRow)[c.id]) || 0)) : 0;
+    return {
+      id: c.id,
+      header: c.label,
+      tip: c.tip ?? undefined,
+      align: c.align ?? (numeric ? 'end' : 'start'),
+      rowHeader: i === 0,
+      compare: (a, b) => compareCells(a[c.id], b[c.id]),
+      text: (r) => cellText(r[c.id], c.format),
+      cell: (r) => {
+        const v = r[c.id];
+        const text = cellText(v, c.format);
+        const url = c.link ? cellUrl(r[c.link]) : null;
+        if (url) return html`<a href=${url} target="_blank" rel="noopener noreferrer">${text}</a>`;
+        if (!c.bar || typeof v !== 'number') return text;
+        // A measure, not a verdict: the bar stays neutral; the row's tone marks its status.
+        return html`${text}<span class="jdur" aria-hidden="true"><i style="width: ${top > 0 ? (100 * Math.max(0, v)) / top : 0}%"></i></span>`;
+      },
+    };
+  });
+}
+
+/** A body's tiles as `<cae-stat-tiles>` takes them. */
+export const bodyTiles = (tiles: readonly PanelTile[]): StatTile[] =>
+  tiles.map((t) => ({ id: t.id, label: t.label, value: t.value, tone: t.tone ?? undefined, tip: t.tip ?? undefined, sub: t.sub ?? [] }));

package/src/adapters/preflight.ts

@@ -0,0 +1,27 @@
+// The run's preflight (`Plan.preflight`) → the rows the run's card lists: the kinds
+// with no available model first (the run's cause when it ended before its first
+// agent session), then the replaced models, then each unavailable model.
+import type { PreflightRecord } from '@contraagent/api';
+import type { Tone } from '../lib/tone.js';
+import { facts } from '../words/format.js';
+import { allAvailable, keptTip, noModelLabel, replacedLabel, replacedText, replacedTip, routeName, unavailableLabel, unavailableText } from '../words/preflight.js';
+
+export interface PreflightRow {
+  label: string;
+  text: string;
+  tone: Tone;
+  /** What the label means; '' for none. */
+  tip: string;
+}
+
+/** The rows of a preflight; none for no preflight or one with policy `off` (no model was sent a request). */
+export function preflightRows(p: PreflightRecord | null | undefined): PreflightRow[] {
+  if (!p || p.policy === 'off') return [];
+  const rows: PreflightRow[] = [
+    ...(p.stopped ?? []).map((kind): PreflightRow => ({ label: noModelLabel(), text: kind, tone: 'failed', tip: '' })),
+    ...(p.kept ?? []).map((k): PreflightRow => ({ label: noModelLabel(), text: facts(k.kind, routeName(k.agent, k.model), k.reason), tone: 'attention', tip: keptTip() })),
+    ...(p.substituted ?? []).map((s): PreflightRow => ({ label: replacedLabel(), text: replacedText(s), tone: 'attention', tip: replacedTip() })),
+    ...(p.dropped ?? []).map((d): PreflightRow => ({ label: unavailableLabel(), text: unavailableText(d), tone: 'muted', tip: '' })),
+  ];
+  return rows.length ? rows : [{ label: '', text: allAvailable(), tone: 'neutral', tip: '' }];
+}

package/src/adapters/task-columns.ts

@@ -0,0 +1,120 @@
+// The tasks list's columns (`ca-task-table`): a row per task of the run
+// (`TaskRow`), its attempts, time, tokens, cost and status.
+import { addRow, emptySpend, isPython, runRelative, type JournalRow, type Spend, type TaskOutcome, type TaskRow } from '@contraagent/api';
+import type { DataColumn } from '@contraagent/elements/data-table';
+import { pill } from '@contraagent/elements/primitives';
+import { msg, str } from '@lit/localize';
+import { html, nothing } from 'lit';
+import { outcomeMark, outcomeTone } from '../lib/tone.js';
+import { executorIcon } from '../words/executor.js';
+import { facts, fmtDur, localTime, tokenCount, usd } from '../words/format.js';
+import { deferredText, deferredTip, notStartedCause, locksNames, locksShort, passLabel, priorityText, priorityTip, taskStatusLabel, waitCause } from '../words/index.js';
+
+export interface TaskColumnsContext {
+  /** The run id: paths in a cause are shown relative to it. */
+  run: string;
+  /** The run is running: a task that has not started is waiting; in a run that is over, it did not run. */
+  live: boolean;
+  /** What happened to each task of the run (`deriveRun(...).outcomes`). */
+  outcomes: ReadonlyMap<string, TaskOutcome>;
+  /** Every task of the run, filtered or not: a kind and unit with more than one task names each one's pass. */
+  all: readonly TaskRow[];
+  /** The rows shown: the time bars are relative to their longest. */
+  rows: readonly TaskRow[];
+  /** The run's journal: tokens and cost per task, over all its attempts. */
+  journal: readonly JournalRow[];
+}
+
+const none = () => msg('none', { id: 'none', desc: 'An empty value' });
+
+/** Why a task that never ran did not run (what stopped it, or the earlier tasks it waits for), or why a task was partly done; '' when unknown. */
+function cause(t: TaskRow, ctx: TaskColumnsContext): string {
+  if (t.outcome === 'not_started') return notStartedCause(t, ctx.outcomes, ctx.run);
+  if (t.outcome === 'partial') return runRelative(t.attempts[t.attempts.length - 1]?.reason ?? '', ctx.run);
+  if (t.outcome === 'waiting' && t.deferred) return deferredText(t.deferredCause, t.deferred, t.deferredIn);
+  if (t.outcome === 'waiting') return waitCause(t.waits_for.map((k) => ctx.outcomes.get(k) ?? { kind: k }));
+  return '';
+}
+
+/** The columns of the tasks list. */
+export function taskColumns(ctx: TaskColumnsContext): DataColumn<TaskRow>[] {
+  // A kind and unit with more than one task (a loop's passes): each row names its pass.
+  const per = new Map<string, number>();
+  for (const t of ctx.all) per.set(`${t.kind}|${t.unit}`, (per.get(`${t.kind}|${t.unit}`) ?? 0) + 1);
+  const maxWall = Math.max(1, ...ctx.rows.map((t) => t.wall_s));
+  const spend = new Map<string, Spend>();
+  for (const r of ctx.journal) addRow(spend.get(r.key) ?? spend.set(r.key, emptySpend()).get(r.key)!, r);
+  // A task that has not run (refused, skipped, waiting) has no attempts and no time.
+  const ran = (t: TaskRow) => t.tries.length > 0;
+  // Tokens and cost: 'none' for a task that never ran, '—' for one that reported none (a Python task).
+  const spent = (t: TaskRow, show: (s: Spend) => unknown) => {
+    if (!ran(t)) return html`<span class="jdim">${none()}</span>`;
+    const s = spend.get(t.key);
+    return s?.reported ? show(s) : html`<span class="jdim">—</span>`;
+  };
+  return [
+    {
+      id: 'task',
+      header: msg('Task'),
+      tip: msg('Kind · unit'),
+      width: 'minmax(220px, 0.6fr)',
+      rowHeader: true,
+      text: (t) => t.key,
+      cell: (t) => {
+        const py = isPython(t);
+        const pass = t.pass !== null && (per.get(`${t.kind}|${t.unit}`) ?? 0) > 1 ? t.pass : null;
+        return html`<span class="grow jmono" title=${t.key}>
+          ${executorIcon(py, py ? msg('Python task') : msg('Agent task'))}${t.kind}
+          ${t.unit ? html`<span class="jdim">· ${t.unit}</span>` : nothing}${pass !== null ? html`<span class="pass">${passLabel(pass)}</span>` : nothing}
+          ${t.claims?.length ? html`<span class="jdim also" title=${locksNames(t.claims)}>${locksShort(t.claims)}</span>` : nothing}
+          ${t.priority ? html`<span class="jdim also" title=${priorityTip()}>${priorityText(t.priority)}</span>` : nothing}
+        </span>`;
+      },
+    },
+    { id: 'attempts', header: msg('Attempts'), tip: msg('Attempts that ran'), align: 'end', width: '64px', cell: (t) => t.tries.length },
+    {
+      id: 'time',
+      header: msg('Time'),
+      tip: msg('Summed over all attempts'),
+      align: 'end',
+      width: '132px',
+      cell: (t) =>
+        html`<span class="wall">${ran(t)
+          ? html`${fmtDur(t.wall_s)}<span class="jdur"><i class=${isPython(t) ? '' : 'llm'}
+              style="width:${Math.max(4, Math.round((100 * t.wall_s) / maxWall))}%"></i></span>`
+          : html`<span class="jdim">${none()}</span><span class="jdur" style="visibility:hidden"></span>`}</span>`,
+    },
+    {
+      id: 'tokens',
+      header: msg('Tokens'),
+      tip: msg('Input and output, summed over all attempts'),
+      align: 'end',
+      width: '72px',
+      cell: (t) =>
+        spent(t, (s) => {
+          const cache = facts(msg(str`Cache read ${tokenCount(s.cache_read)}`), msg(str`Cache write ${tokenCount(s.cache_creation)}`));
+          return html`<span title=${cache}>${tokenCount(s.input + s.output)}</span>`;
+        }),
+    },
+    { id: 'cost', header: msg('Cost'), tip: msg('Reported by the coding agent'), align: 'end', width: '72px', cell: (t) => spent(t, (s) => usd(s.cost)) },
+    {
+      id: 'ended',
+      header: msg('Last attempt ended'),
+      align: 'end',
+      width: '128px',
+      cell: (t) => html`<span class="meta">${ran(t) ? localTime(t.tries[t.tries.length - 1]?.ts, true) : none()}</span>`,
+    },
+    {
+      id: 'status',
+      header: msg('Status', { id: 'status', desc: 'The status of a task: done, failed, not started' }),
+      width: 'minmax(240px, 1fr)',
+      cell: (t) => {
+        const why = cause(t, ctx);
+        const tip = t.outcome === 'waiting' && t.deferred ? deferredTip(t.deferredCause) || t.deferred : '';
+        return html`${pill({ text: taskStatusLabel(t.outcome, ctx.live && !t.deferred), tone: outcomeTone(t.outcome), mark: outcomeMark(t.outcome), title: t.last_stop })}${why
+          ? html`<span class="cause" title=${tip || nothing}>${why}</span>`
+          : nothing}`;
+      },
+    },
+  ];
+}

package/src/adapters/transcript/index.ts

@@ -0,0 +1,14 @@
+// A task's transcript: its events folded into rounds (`applyTranscriptEvents`),
+// the rounds as the reader counts them, and the sections `<cae-transcript>` shows.
+export { agentLabel, launchWho, whoTags, type Who } from './who.js';
+export {
+  applyEvents as applyTranscriptEvents,
+  emptyTranscript,
+  type Item as TranscriptItem,
+  type Round as TranscriptRound,
+  type ToolItem as TranscriptToolItem,
+  type Transcript,
+} from './model.js';
+export { checkMessage, checkName, classifyRounds, fixupErrors, isFixup } from './rounds.js';
+export { webResults, type WebResult } from './web.js';
+export { transcriptSections, type SectionsContext } from './sections.js';

package/src/adapters/transcript/model.ts

@@ -0,0 +1,156 @@
+// A transcript as the reader sees it: one round per launch, each a list of
+// items (chat bubbles, tool cards, notices). Pure: no DOM. The model is
+// mutated in place as pages of events arrive (`StreamController`);
+// `transcriptSections` turns it into what `<cae-transcript>` shows.
+import { knownEvent, type LaunchEvent, type TranscriptEvent } from '@contraagent/api';
+import type { ToolCard, TranscriptItem } from '@contraagent/elements/transcript';
+import { firstLine } from '../../words/format.js';
+import { webResults } from './web.js';
+import { launchWho, type Who } from './who.js';
+
+/** One tool call: the card that opens on its start and receives its result. */
+export interface ToolItem extends ToolCard {
+  /** The call id pairing start and end; '' when the agent sent none. */
+  call: string;
+  /** The tool's short name (`bash`, `read`, ...). */
+  icon: string;
+  intent: string;
+  /** The command shown in the card's body. */
+  body: string;
+}
+
+/**
+ * What a round shows, as `<cae-transcript>` takes it: the prompt the launch
+ * assembled as the agent echoed it, assistant prose accumulated from its deltas
+ * (`message`), a turn's closing thinking (`reasoning`), an API request the
+ * coding agent sent again (`auto_retry_start`, an `event` whose `text` is the
+ * error it got; its title is the reader's word, `transcriptSections`), a
+ * notice, a tool call.
+ */
+export type Item = Exclude<TranscriptItem, ToolCard> | ToolItem;
+
+export interface Round {
+  id: string;
+  /** The launch event that opened it; null for events that came before any launch. */
+  launch: LaunchEvent | null;
+  who: Who | null;
+  items: Item[];
+}
+
+export interface Transcript {
+  rounds: Round[];
+  /** Tool cards by call id. omp reports one call in several event styles, sometimes twice: they all land in one card. */
+  tools: Map<string, ToolItem>;
+  next: number;
+}
+
+export const emptyTranscript = (): Transcript => ({ rounds: [], tools: new Map(), next: 0 });
+
+const SESSION_MODEL = /session init:.*?model=([\w.\-:]+)/;
+
+function newId(t: Transcript): string {
+  return `i${t.next++}`;
+}
+
+function addRound(t: Transcript, launch: LaunchEvent | null): Round {
+  const r: Round = { id: `r${t.rounds.length}`, launch, who: launch ? launchWho(launch) : null, items: [] };
+  t.rounds.push(r);
+  return r;
+}
+
+function currentRound(t: Transcript): Round {
+  return t.rounds[t.rounds.length - 1] ?? addRound(t, null);
+}
+
+function setToolName(card: ToolItem, name: string | null | undefined): void {
+  if (name) card.name = name;
+  else if (!card.name) card.name = 'tool';
+  card.icon = (card.name.split(/[_:]/).pop() ?? '').toLowerCase();
+}
+
+function cardFor(t: Transcript, round: Round, call: string): ToolItem {
+  let c = call ? t.tools.get(call) : undefined;
+  if (!c) {
+    c = { type: 'tool', id: call ? `call:${call}` : newId(t), call, name: '', icon: '', summary: '', intent: '', body: '', output: null, status: 'running' };
+    if (call) t.tools.set(call, c);
+    round.items.push(c);
+  }
+  return c;
+}
+
+/**
+ * Fold `events` into the transcript. Returns how many of them showed something
+ * (a reader scrolled away is told that many arrived).
+ */
+export function applyEvents(t: Transcript, events: readonly TranscriptEvent[]): number {
+  let shown = 0;
+  for (const raw of events) {
+    const e = knownEvent(raw);
+    if (!e) continue;
+    if (e.type === 'launch') {
+      addRound(t, e);
+      shown++;
+      continue;
+    }
+    const r = currentRound(t);
+    switch (e.type) {
+      case 'message_start':
+      case 'message_end':
+        if (e.role !== 'user' || !e.text) continue;
+        r.items.push({ type: 'prompt', id: newId(t), text: e.text });
+        break;
+      case 'turn_end':
+        if (!e.thinking) continue;
+        r.items.push({ type: 'reasoning', id: newId(t), text: e.thinking });
+        break;
+      case 'acall':
+      case 'tool_execution_start':
+      case 'tool_execution_update': {
+        const c = cardFor(t, r, e.call);
+        if (c.output === null) {
+          setToolName(c, e.tool);
+          c.summary = firstLine(e.cmd);
+          c.intent = e.intent || '';
+          c.body = e.cmd || c.body;
+          if (e.web_query) c.query = e.web_query;
+          if (e.web_fetch) c.page = e.web_fetch;
+        } else if (!c.summary && e.cmd) {
+          c.summary = firstLine(e.cmd); // a late duplicate may only add the summary
+        }
+        break;
+      }
+      case 'aresult':
+      case 'tool_execution_end': {
+        const c = cardFor(t, r, e.call);
+        if (c.output !== null && !e.out) break; // a repeated, empty result must not blank the real one
+        setToolName(c, e.tool);
+        c.status = e.err ? 'error' : 'ok';
+        if (!c.summary && c.body) c.summary = firstLine(c.body);
+        c.output = e.out || '(no output)';
+        if (c.query) c.links = webResults(c.output);
+        break;
+      }
+      case 'message_update': {
+        if (!e.delta) continue;
+        const last = r.items[r.items.length - 1];
+        if (last?.type === 'message') last.text += e.delta;
+        else r.items.push({ type: 'message', id: newId(t), text: e.delta });
+        break;
+      }
+      case 'auto_retry_start':
+        r.items.push({ type: 'event', id: newId(t), icon: '↻', title: '', text: e.err ?? '' });
+        break;
+      case 'notice': {
+        const model = SESSION_MODEL.exec(e.text || '')?.[1];
+        if (model) {
+          r.who ??= { agent: '', model: '', role: '' };
+          if (!r.who.model) r.who.model = model;
+        }
+        r.items.push({ type: 'notice', id: newId(t), text: (e.text || '').replace(/\s+/g, ' ').trim() });
+        break;
+      }
+    }
+    shown++;
+  }
+  return shown;
+}

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;
+}