@contraagent/api 0.0.0-stage → 0.1.0

package/src/derive.ts

@@ -0,0 +1,155 @@
+// Everything the views count and list about a run's tasks, derived once per
+// state change: the outcomes, the rows, the counts and the problems. Every view
+// reads `deriveRun(journal, plan)`, so "N of M tasks done" and every cause read
+// the same on every screen. Pure; memoized on the identity of its inputs.
+import { isLaunched, outcomeCounts, problems, taskOutcomes, taskRows } from './outcomes.js';
+import type { Outcome, Problems, TaskOutcome, TaskRow } from './outcomes.js';
+import type { HostSummary, JournalRow, Plan, PlanNode, RunSummary } from './types.js';
+
+export interface RunCounts extends Record<Outcome, number> {
+  total: number;
+  /** done + recovered: "N of M tasks done" in every view. */
+  doneTotal: number;
+  /** done + recovered + partial + skipped: nothing is left to do. */
+  finished: number;
+}
+
+/** Tries (journal rows that ran) and rows of tasks that never started (a refusal, a skip). */
+export interface TryCounts {
+  tries: number;
+  notStarted: number;
+}
+
+export interface RunDerived {
+  /** Every task of the run, by key: the plan joined with the journal. */
+  outcomes: ReadonlyMap<string, TaskOutcome>;
+  /** The same tasks as rows, in plan order. */
+  rows: readonly TaskRow[];
+  counts: RunCounts;
+  problems: Problems;
+  /** The tasks' kinds, sorted. */
+  kinds: readonly string[];
+  tries: TryCounts;
+}
+
+const NO_PLAN: Plan = { nodes: [], groups: [] };
+
+/** Run state replaces the journal and the plan arrays on every change (`reduceRun`), so their identity is the key. */
+const memo = new WeakMap<readonly JournalRow[], WeakMap<Plan, RunDerived>>();
+
+/**
+ * What the views show about a run's tasks. Without a plan, the tasks are the
+ * journal's only. The same `journal` and `plan` objects give the same result object.
+ */
+export function deriveRun(journal: readonly JournalRow[], plan: Plan | null | undefined = NO_PLAN): RunDerived {
+  const p = plan ?? NO_PLAN;
+  let byPlan = memo.get(journal);
+  if (!byPlan) memo.set(journal, (byPlan = new WeakMap()));
+  let d = byPlan.get(p);
+  if (!d) byPlan.set(p, (d = derive(journal, p)));
+  return d;
+}
+
+function derive(journal: readonly JournalRow[], plan: Plan): RunDerived {
+  const outcomes = taskOutcomes(journal, plan);
+  const c = outcomeCounts(outcomes);
+  return {
+    outcomes,
+    rows: taskRows(outcomes, plan),
+    counts: { ...c, doneTotal: c.done + c.recovered, finished: c.done + c.recovered + c.partial + c.skipped },
+    problems: problems(outcomes),
+    kinds: [...new Set([...outcomes.values()].map((t) => t.kind))].sort(),
+    tries: tryCounts(journal),
+  };
+}
+
+/** Tries (journal rows that ran) and rows of tasks that never started: the one way the UI counts them. */
+export function tryCounts(journal: readonly JournalRow[]): TryCounts {
+  const tries = journal.filter(isLaunched).length;
+  return { tries, notStarted: journal.length - tries };
+}
+
+export interface Progress {
+  total: number;
+  /** Plan state `done`: done and done after retrying. */
+  done: number;
+  /** Plan state `partial`: ok, the output a placeholder. */
+  partial: number;
+  skipped: number;
+  /** Finished (done, partial and skipped) out of all, in percent. */
+  pct: number;
+}
+
+/** How far a run is, from the plan's groups. */
+export function progress(plan: Plan): Progress {
+  const total = plan.groups.reduce((a, g) => a + g.total, 0);
+  const done = plan.groups.reduce((a, g) => a + g.done, 0);
+  const partial = plan.groups.reduce((a, g) => a + (g.partial ?? 0), 0);
+  const skipped = plan.groups.reduce((a, g) => a + g.skipped, 0);
+  return { total, done, partial, skipped, pct: Math.round((100 * (done + partial + skipped)) / Math.max(1, total)) };
+}
+
+/** How a run's tasks ended, from the plan: for a run that is over, in place of a progress bar. */
+export function result(plan: Plan): { done: number; partial: number; skipped: number; failed: number; notStarted: number; left: number } {
+  const count = (...states: PlanNode['state'][]) => plan.nodes.filter((n) => states.includes(n.state)).length;
+  return { done: count('done'), partial: count('partial'), skipped: count('skipped'), failed: count('failed'), notStarted: count('blocked'), left: count('pending', 'running') };
+}
+
+/** How long a run took, wall clock: from its start to its last activity (null when unknown). */
+export function elapsedS(r: Pick<RunSummary, 'started_at' | 'last_ts'> | undefined): number | null {
+  const a = Date.parse(r?.started_at ?? '');
+  const b = Date.parse(r?.last_ts ?? '');
+  return Number.isNaN(a) || Number.isNaN(b) ? null : Math.max(0, (b - a) / 1000);
+}
+
+// --- a run's process and its host ----------------------------------------------
+
+/**
+ * A run's process, as every view names it: `running`; `unresponsive`, its host
+ * last reported it alive and has stopped reporting (a hub only), so whether it
+ * still runs is not known; or `stopped`.
+ */
+export type RunActivity = 'running' | 'unresponsive' | 'stopped';
+
+/** What a run's process is doing, from the run list and (when its feed is open) the feed's `procs.alive`. */
+export function runActivity(summary: Pick<RunSummary, 'running' | 'unresponsive'> | undefined, alive = false): RunActivity {
+  if (alive || summary?.running) return 'running';
+  return summary?.unresponsive ? 'unresponsive' : 'stopped';
+}
+
+/** The host that drives a run, from the host list. */
+export const hostOf = (hosts: readonly HostSummary[] | undefined, summary: Pick<RunSummary, 'host_id'> | undefined): HostSummary | undefined =>
+  summary?.host_id ? hosts?.find((h) => h.host_id === summary.host_id) : undefined;
+
+/** A run's name without its host: a hub names a run `<run_id>@<host_id>`; any other name as it is. */
+export function runIdOf(r: Pick<RunSummary, 'run' | 'host_id'>): string {
+  const n = r.run.length - (r.host_id?.length ?? 0) - 1;
+  return r.host_id && n > 0 && r.run.endsWith(`@${r.host_id}`) ? r.run.slice(0, n) : r.run;
+}
+
+/** One host's runs. */
+export interface HostGroup {
+  hostId: string;
+  /** The host as the host list has it; undefined for a host the list does not have yet. */
+  host: HostSummary | undefined;
+  runs: RunSummary[];
+}
+
+const ACTIVITY_ORDER: RunActivity[] = ['running', 'unresponsive', 'stopped'];
+
+/**
+ * Runs by host, in the host list's order (then the host ids it does not have,
+ * sorted): in each, the running runs, then those whose host stopped reporting,
+ * then the rest, each in the order given (the run list's: most recent first).
+ */
+export function hostGroups(runs: readonly RunSummary[], hosts: readonly HostSummary[] = []): HostGroup[] {
+  const ids = [...new Set(runs.map((r) => r.host_id ?? ''))];
+  const known = hosts.map((h) => h.host_id);
+  const rank = (r: RunSummary) => ACTIVITY_ORDER.indexOf(runActivity(r));
+  return [...known.filter((id) => ids.includes(id)), ...ids.filter((id) => !known.includes(id)).sort()].map((hostId) => ({
+    hostId,
+    host: hosts.find((h) => h.host_id === hostId),
+    // A stable sort: equal runs keep the order given.
+    runs: runs.filter((r) => (r.host_id ?? '') === hostId).sort((a, b) => rank(a) - rank(b)),
+  }));
+}

package/src/export.ts

@@ -0,0 +1,158 @@
+// An export (`contraagent monitor export`): the monitor's views of some runs,
+// written as files and read with no server. The client maps each endpoint to its
+// file; the feed replays a run's files once and ends with `ready`.
+import { ApiError, type MonitorClient } from './client.js';
+import type { FeedHandlers, Unsubscribe } from './feed.js';
+import type {
+  CursorView,
+  Info,
+  JournalPage,
+  JsonObject,
+  Outputs,
+  Plan,
+  RunFeedMessage,
+  RunSummary,
+  TaskDefinition,
+  TaskDetail,
+  Trends,
+} from './types.js';
+
+/** A client of an export: the monitor's client, and the files the server sends over its feed instead. */
+export interface ExportClient extends MonitorClient {
+  /** A file of the export, `data/<path>` (cached): the endpoints' answers, and `plan`, `outputs`, `cursor`. */
+  file<T>(path: string): Promise<T>;
+}
+
+export interface ExportClientOptions {
+  fetch?: typeof globalThis.fetch;
+}
+
+const seg = encodeURIComponent;
+
+/**
+ * The name task `key`'s files take in a run directory and in an export, without a
+ * suffix: `key` with every character but a letter, a digit, `-`, `_` and `.` turned
+ * into `_`, as are a leading `.` and each `..` (Python's `file_name`, `runs/layout.py`).
+ */
+export function taskFileName(key: string): string {
+  const name = Array.from(key, (ch) => (/^[\p{L}\p{N}._-]$/u.test(ch) ? ch : '_'))
+    .join('')
+    .replace(/\.\.+/g, (m) => '_'.repeat(m.length));
+  return name.startsWith('.') ? `_${name.slice(1)}` : name || '_';
+}
+
+/**
+ * A `MonitorClient` over an export at `baseUrl` (its `data/`, relative to the page or
+ * absolute). An endpoint is a file: `info.json`, `runs.json`, `runs/<run>/journal.json`,
+ * `runs/<run>/tasks/<file>.json` (`taskFileName`) ... A task's file leaves out its rows and its
+ * definition, which the run's journal and definitions hold: the client puts them back.
+ * A view the export does not hold (a transcript, the hosts) answers `ApiError` 404.
+ * An endpoint of no run is a file under `data/` (`trends.json`, `trends/panels/<name>.json`):
+ * a new endpoint is one method here, `file<T>('<its file>')`, beside its entry in the
+ * Python `VIEWS` (`contraagent/monitor/views.py`) or `SITE_FILES` (`contraagent/monitor/export.py`).
+ */
+export function createExportClient(baseUrl: string, options: ExportClientOptions = {}): ExportClient {
+  const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+  const fetch = options.fetch ?? globalThis.fetch;
+  const cache = new Map<string, Promise<unknown>>();
+
+  function file<T>(path: string): Promise<T> {
+    let p = cache.get(path);
+    if (!p) {
+      p = load(base + path);
+      // A failed read is tried again next time.
+      p.catch(() => cache.delete(path));
+      cache.set(path, p);
+    }
+    return p as Promise<T>;
+  }
+
+  async function load(url: string): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await fetch(new Request(url));
+    } catch {
+      throw new ApiError(url, 'network');
+    }
+    const type = (response.headers.get('Content-Type') ?? '').split(';')[0]!.trim().toLowerCase();
+    if (!response.ok) throw new ApiError(url, 'status', response.status, type);
+    try {
+      return (await response.json()) as unknown;
+    } catch {
+      throw new ApiError(url, 'not-json', response.status, type);
+    }
+  }
+
+  const run = (r: string, path: string): string => `runs/${seg(r)}/${path}`;
+  const absent = (path: string): Promise<never> => Promise.reject(new ApiError(base + path, 'status', 404));
+
+  return {
+    baseUrl: base.replace(/\/$/, ''),
+    file,
+    info: () => file<Info>('info.json'),
+    runs: () => file<RunSummary[]>('runs.json'),
+    hosts: () => absent('hosts.json'),
+    async journal(r, since = 0): Promise<JournalPage> {
+      const page = await file<JournalPage>(run(r, 'journal.json'));
+      return since > 0 ? { entries: page.entries.slice(since), total: page.total } : page;
+    },
+    definitions: (r) => file<TaskDefinition[]>(run(r, 'definitions.json')),
+    async task(r, key): Promise<TaskDetail> {
+      const [detail, journal, definitions, plan] = await Promise.all([
+        file<TaskDetail>(run(r, `tasks/${seg(taskFileName(key))}.json`)),
+        file<JournalPage>(run(r, 'journal.json')),
+        file<TaskDefinition[]>(run(r, 'definitions.json')),
+        file<Plan>(run(r, 'plan.json')),
+      ]);
+      const rows = journal.entries.filter((e) => e.key === key);
+      const kind = rows.at(-1)?.kind ?? plan.nodes.find((n) => n.key === key)?.kind;
+      return { ...detail, rows, definition: definitions.find((d) => d.kind === kind) ?? null };
+    },
+    stream: (r, key) => absent(run(r, `streams/${seg(taskFileName(key))}.json`)),
+    panel: (r, name) => file<JsonObject>(run(r, `panels/${seg(name)}.json`)),
+    // An export holds one period's trends (`Info.export`): a query for another is answered with it.
+    trends: () => file<Trends>('trends.json'),
+    trendsPanel: (name) => file<JsonObject>(`trends/panels/${seg(name)}.json`),
+  };
+}
+
+/** A cursor file: `{}` when the run keeps no cursor. */
+const isCursor = (c: CursorView | Record<string, never>): c is CursorView => Object.keys(c).length > 0;
+
+/** A run feed opener, as `openRunFeed` is: what `MonitorStore` opens a run's feed with. */
+export type RunFeedOpener = (run: string, panels: readonly string[], on: FeedHandlers<RunFeedMessage>) => Unsubscribe;
+
+/**
+ * The run feed of an export: the run's journal rows, plan, outputs, cursor and panels,
+ * each once, then `ready`; nothing after. A file it cannot read stops it with `error`.
+ */
+export function openExportFeed(client: ExportClient): RunFeedOpener {
+  return (r, panels, on) => {
+    let closed = false;
+    void (async () => {
+      try {
+        const [journal, plan, outputs, cursor, bodies] = await Promise.all([
+          client.journal(r),
+          client.file<Plan>(`runs/${seg(r)}/plan.json`),
+          client.file<Outputs>(`runs/${seg(r)}/outputs.json`),
+          client.file<CursorView | Record<string, never>>(`runs/${seg(r)}/cursor.json`),
+          Promise.all(panels.map((p) => client.panel(r, p).catch((e: unknown): JsonObject => ({ error: String(e) })))),
+        ]);
+        if (closed) return;
+        on.open?.();
+        const send = (m: RunFeedMessage) => !closed && on.message(m);
+        for (const row of journal.entries) send({ event: 'journal', data: row });
+        send({ event: 'plan', data: plan });
+        send({ event: 'outputs', data: outputs });
+        send({ event: 'cursor', data: isCursor(cursor) ? cursor : null });
+        panels.forEach((p, i) => send({ event: `panel:${p}`, data: bodies[i] ?? {} }));
+        send({ event: 'ready', data: { journal: journal.total } });
+      } catch {
+        if (!closed) on.error?.();
+      }
+    })();
+    return () => {
+      closed = true;
+    };
+  };
+}

package/src/feed.ts

@@ -0,0 +1,81 @@
+// The live half of the monitor API: Server-Sent Events, parsed into typed messages.
+import type { RunEventName, RunFeedMessage, StreamPage } from './types.js';
+
+/** Every SSE event name of `/events` with a fixed meaning; panels add `panel:<name>`. */
+export const RUN_EVENT_NAMES = [
+  'journal',
+  'procs',
+  'plan',
+  'outputs',
+  'cursor',
+  'ready',
+] as const satisfies readonly RunEventName[];
+
+// A name missing from the list above fails to compile here.
+type Missing = Exclude<RunEventName, (typeof RUN_EVENT_NAMES)[number]>;
+const _exhaustive: [Missing] extends [never] ? true : never = true;
+void _exhaustive;
+
+export interface FeedHandlers<M> {
+  message(msg: M): void;
+  /** The connection opened, or re-opened after a drop (the server then starts over). */
+  open?(): void;
+  /** The connection dropped; the browser retries on its own. */
+  error?(): void;
+}
+
+export interface FeedOptions {
+  /** Where the monitor is served, as for the client; '' (the default) is the page's own origin. */
+  baseUrl?: string;
+  /** For tests and non-browser hosts. */
+  EventSource?: typeof globalThis.EventSource;
+}
+
+/** A feed to stop. */
+export type Unsubscribe = () => void;
+
+function connect(url: string, names: readonly string[], on: FeedHandlers<{ event: string; data: unknown }>, opts: FeedOptions): Unsubscribe {
+  const ES = opts.EventSource ?? globalThis.EventSource;
+  const es = new ES(url);
+  es.onopen = () => on.open?.();
+  es.onerror = () => on.error?.();
+  for (const name of names) {
+    es.addEventListener(name, (ev) => {
+      on.message({ event: name, data: JSON.parse((ev as globalThis.MessageEvent<string>).data) as unknown });
+    });
+  }
+  return () => es.close();
+}
+
+const q = encodeURIComponent;
+const base = (opts: FeedOptions): string => (opts.baseUrl ?? '').replace(/\/$/, '');
+
+/**
+ * `/events?run=`: the run, live. The server replays the whole journal on every
+ * (re)connect and then sends `ready`; `panels` are the panel names from
+ * `/api/info` to listen for.
+ */
+export function openRunFeed(
+  run: string,
+  panels: readonly string[],
+  on: FeedHandlers<RunFeedMessage>,
+  opts: FeedOptions = {},
+): Unsubscribe {
+  const names = [...RUN_EVENT_NAMES, ...panels.map((p) => `panel:${p}`)];
+  return connect(`${base(opts)}/events?run=${q(run)}`, names, on, opts);
+}
+
+/** `/events/stream`: one transcript, tailed. The first page is the tail; each later one only what is new. */
+export function openStreamFeed(
+  run: string,
+  key: string,
+  on: FeedHandlers<StreamPage>,
+  opts: FeedOptions = {},
+): Unsubscribe {
+  return connect(
+    `${base(opts)}/events/stream?run=${q(run)}&key=${q(key)}`,
+    ['stream'],
+    { ...on, message: (m) => on.message(m.data as StreamPage) },
+    opts,
+  );
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './client.js';
+export * from './feed.js';
+export * from './run-state.js';
+export * from './store.js';
+export * from './export.js';
+export * from './outcomes.js';
+export * from './derive.js';
+export * from './spend.js';
+export * from './quota.js';
+export * from './reasons.js';
+export * from './panels.js';

package/src/outcomes.ts

@@ -0,0 +1,267 @@
+// What happened to each task, in the terms a reader asks about: did it finish,
+// fail, never start, or fail and then recover; and for a problem, which task
+// caused it. Folded from the journal (finished attempts) and the plan (every
+// queued task and what it waits for). Pure.
+import type { DeferralCause, JournalRow, Plan, PlanNode, TaskState } from './types.js';
+
+/**
+ * - `done`: its last attempt completed, first time.
+ * - `recovered`: a try that ran failed at least once, then its last attempt completed.
+ * - `partial`: its last attempt was partial (stop `partial`): ok, its output a placeholder; not done, not failed.
+ * - `failed`: it ran and its last attempt failed.
+ * - `not_started`: it never ran: an input was missing or off-contract, or it waits behind a task that failed.
+ * - `running`, `waiting` (queued, not started yet), `skipped`.
+ */
+export type Outcome = 'done' | 'recovered' | 'partial' | 'failed' | 'not_started' | 'running' | 'waiting' | 'skipped';
+
+export interface TaskOutcome {
+  key: string;
+  kind: string;
+  unit: string;
+  executor: 'agent' | 'python';
+  outcome: Outcome;
+  /** Its journal rows, oldest first (a refusal included). */
+  attempts: JournalRow[];
+  /** The rows of tries that actually ran (`isLaunched`), oldest first. */
+  tries: JournalRow[];
+  /** For a task that did not start: the failed task upstream that stopped it, if one is known. */
+  cause: string | null;
+  /** For a task the queue deferred (never launched): why, as the run recorded it; '' when it was not. */
+  deferred: string;
+  /** The same as data, for words of a reader's language; null when it was not deferred, or the run recorded no cause. */
+  deferredCause: DeferralCause | null;
+  /** For a task deferred by a flow call's own deadline (`time_box`): that flow call's function (`module.qualname`); '' otherwise. */
+  deferredIn: string;
+}
+
+/** The function of the flow call whose own deadline (`time_box`) deferred a task (`cause.flow_call`); '' for the run's deadline or another cause. */
+export function deferredIn(plan: Pick<Plan, 'flow_calls'> | null | undefined, cause: DeferralCause | null | undefined): string {
+  const id = cause?.flow_call;
+  return id ? (plan?.flow_calls?.find((c) => c.id === id)?.function ?? '') : '';
+}
+
+const isOk = (r: JournalRow) => r.ok;
+
+/**
+ * The row is a real try: the task ran. A task refused before launch
+ * (`invalid_input`) or skipped also gets a journal row, but never ran: it is
+ * not a try, not an agent session, and not a failed attempt.
+ */
+export const isLaunched = (r: JournalRow): boolean => r.stop !== 'invalid_input' && r.stop !== 'skipped';
+
+/**
+ * A task's outcome from its plan node (if any) and its journal rows, oldest
+ * first. `recovered` needs a try that ran and failed: a refusal before launch
+ * (`invalid_input`) is not a failed attempt, so "not started, then done" is `done`.
+ */
+export function outcomeOf(node: Pick<PlanNode, 'state'> | undefined, attempts: readonly JournalRow[]): Outcome {
+  if (node?.state === 'running') return 'running';
+  const last = attempts[attempts.length - 1];
+  if (!last) return node?.state === 'blocked' ? 'not_started' : 'waiting';
+  if (last.stop === 'skipped') return 'skipped';
+  if (last.stop === 'invalid_input') return 'not_started';
+  if (last.stop === 'partial') return 'partial';
+  if (isOk(last)) return attempts.some((a) => isLaunched(a) && !isOk(a)) ? 'recovered' : 'done';
+  return 'failed';
+}
+
+/**
+ * The retries in `journal`, oldest first: the tries that ran (`isLaunched`)
+ * after an earlier try of the same task ran and failed, as in `recovered`. A
+ * try after a refusal (`invalid_input`) is not a retry.
+ */
+export function retries(journal: readonly JournalRow[]): JournalRow[] {
+  const failed = new Set<string>();
+  const out: JournalRow[] = [];
+  for (const r of journal) {
+    if (!isLaunched(r)) continue;
+    if (failed.has(r.key)) out.push(r);
+    if (!isOk(r)) failed.add(r.key);
+  }
+  return out;
+}
+
+/**
+ * A plan node's state as an outcome: `blocked` is `not_started` and `pending`
+ * is `waiting`. Plan state `done` covers both `done` and `recovered`.
+ */
+export function planOutcome(state: TaskState): Outcome {
+  switch (state) {
+    case 'blocked':
+      return 'not_started';
+    case 'pending':
+      return 'waiting';
+    default:
+      return state;
+  }
+}
+
+/** Nothing is left to do for the task in this run: done, done after retrying, partial (its later tasks run on its output), or skipped. */
+export const isFinished = (o: Outcome): boolean => o === 'done' || o === 'recovered' || o === 'partial' || o === 'skipped';
+
+/** Every task of the run (from the plan, and from the journal for tasks the plan does not list), by key. */
+export function taskOutcomes(journal: readonly JournalRow[], plan: Plan): Map<string, TaskOutcome> {
+  const rows = new Map<string, JournalRow[]>();
+  for (const r of journal) {
+    let list = rows.get(r.key);
+    if (!list) rows.set(r.key, (list = []));
+    list.push(r);
+  }
+  const nodes = new Map(plan.nodes.map((n) => [n.key, n]));
+  const keys = [...new Set([...plan.nodes.map((n) => n.key), ...rows.keys()])];
+  const out = new Map<string, TaskOutcome>();
+  for (const key of keys) {
+    const node = nodes.get(key);
+    const attempts = rows.get(key) ?? [];
+    const first = attempts[0];
+    out.set(key, {
+      key,
+      kind: node?.kind ?? first?.kind ?? '',
+      unit: node?.unit ?? first?.unit ?? '',
+      executor: node?.executor ?? first?.executor ?? 'agent',
+      outcome: outcomeOf(node, attempts),
+      attempts,
+      tries: attempts.filter(isLaunched),
+      cause: null,
+      deferred: node?.deferred ?? '',
+      deferredCause: node?.deferred_cause ?? null,
+      deferredIn: deferredIn(plan, node?.deferred_cause),
+    });
+  }
+  // A task that did not start: follow what it waits for to the task that actually failed.
+  const rootOf = (key: string, seen: Set<string>): string | null => {
+    for (const dep of nodes.get(key)?.after ?? []) {
+      if (seen.has(dep)) continue;
+      seen.add(dep);
+      const d = out.get(dep);
+      if (d?.outcome === 'failed') return dep;
+      if (d?.outcome === 'not_started') {
+        const r = rootOf(dep, seen);
+        if (r) return r;
+      }
+    }
+    return null;
+  };
+  for (const t of out.values()) if (t.outcome === 'not_started') t.cause = rootOf(t.key, new Set());
+  return out;
+}
+
+export interface Problem {
+  /** The task that failed. */
+  task: TaskOutcome;
+  /** The tasks that did not start because of it. */
+  stopped: TaskOutcome[];
+}
+
+export interface Problems {
+  /** Failed tasks, the latest first, each with the tasks it stopped. */
+  failed: Problem[];
+  /** Tasks that did not start for a reason of their own. */
+  notStarted: TaskOutcome[];
+  /** Partial tasks: ok, their output a placeholder. */
+  partial: TaskOutcome[];
+  /** Tasks done after retrying. */
+  recovered: TaskOutcome[];
+}
+
+/**
+ * What is wrong with the run, causes first: each failed task with the tasks
+ * it stopped, then tasks that did not start for a reason of their own (an
+ * input that was never produced by a task). Tasks that recovered are not
+ * problems: they are listed apart, after them.
+ */
+export function problems(outcomes: ReadonlyMap<string, TaskOutcome>): Problems {
+  const failed = new Map<string, Problem>();
+  for (const t of outcomes.values()) if (t.outcome === 'failed') failed.set(t.key, { task: t, stopped: [] });
+  const notStarted: TaskOutcome[] = [];
+  for (const t of outcomes.values()) {
+    if (t.outcome !== 'not_started') continue;
+    const p = t.cause ? failed.get(t.cause) : undefined;
+    if (p) p.stopped.push(t);
+    else notStarted.push(t);
+  }
+  const lastTs = (t: TaskOutcome) => t.attempts[t.attempts.length - 1]?.ts ?? '';
+  return {
+    failed: [...failed.values()].sort((a, b) => lastTs(b.task).localeCompare(lastTs(a.task))),
+    notStarted,
+    partial: [...outcomes.values()].filter((t) => t.outcome === 'partial'),
+    recovered: [...outcomes.values()].filter((t) => t.outcome === 'recovered'),
+  };
+}
+
+/** How many tasks the run has, and how they ended. */
+export function outcomeCounts(outcomes: ReadonlyMap<string, TaskOutcome>): Record<Outcome, number> & { total: number } {
+  const c = { done: 0, recovered: 0, partial: 0, failed: 0, not_started: 0, running: 0, waiting: 0, skipped: 0, total: 0 };
+  for (const t of outcomes.values()) {
+    c[t.outcome]++;
+    c.total++;
+  }
+  return c;
+}
+
+/**
+ * One task of the run as a list shows it: what happened to it (`TaskOutcome`)
+ * and what its tries add up to. A task that never ran has no tries: `wall_s` 0,
+ * `last_ts` and `last_stop` ''.
+ */
+export interface TaskRow extends TaskOutcome {
+  /** Its loop pass (the innermost loop of its flow path), from 1; null outside a loop. */
+  pass: number | null;
+  /** Time of its tries, summed, in seconds. */
+  wall_s: number;
+  /** When its last journal row was written; '' for none. */
+  last_ts: string;
+  /** The stop of its last journal row; '' for none. */
+  last_stop: string;
+  /** A waiting task: the keys of the earlier tasks it waits for that have not finished, in plan order. */
+  waits_for: string[];
+  /** The names it holds while it runs (`claims`); empty for none. */
+  claims: string[];
+  /** Its task call's `priority`: a tie-breaker in the queue's order; 0 by default. */
+  priority: number;
+}
+
+/** The innermost loop pass of a plan node's flow path; null outside a loop (a pass not counted reads as the first). */
+export function loopPass(node: Pick<PlanNode, 'flow'> | undefined): number | null {
+  const frames = Array.isArray(node?.flow) ? node.flow : [];
+  for (let i = frames.length - 1; i >= 0; i--) {
+    const loops = frames[i]?.loops ?? [];
+    const inner = loops[loops.length - 1];
+    if (inner) return typeof inner.pass === 'number' && inner.pass >= 1 ? inner.pass : 1;
+  }
+  return null;
+}
+
+/**
+ * Every task of the run, one row each, from its outcomes (`taskOutcomes`): the
+ * plan joined with the journal, so a task that never ran (waiting, not started)
+ * is a row too. In plan order. Views read them from `deriveRun(...).rows`.
+ */
+export function taskRows(outcomes: ReadonlyMap<string, TaskOutcome>, plan: Plan): TaskRow[] {
+  const nodes = new Map(plan.nodes.map((n) => [n.key, n]));
+  return [...outcomes.values()].map((t) => {
+    const last = t.attempts[t.attempts.length - 1];
+    const node = nodes.get(t.key);
+    return {
+      ...t,
+      pass: loopPass(node),
+      wall_s: t.tries.reduce((s, r) => s + (r.wall_s || 0), 0),
+      last_ts: last?.ts ?? '',
+      last_stop: last?.stop ?? '',
+      waits_for:
+        t.outcome === 'waiting' ? (node?.after ?? []).filter((d) => !isFinished(outcomes.get(d)?.outcome ?? 'waiting')) : [],
+      claims: node?.claims ?? [],
+      priority: node?.priority ?? 0,
+    };
+  });
+}
+
+/** The task to open by default: a running agent task, else the agent task that ran last (it has a transcript); never a Python task. Its key, or null. */
+export function latestTask(rows: readonly TaskRow[]): string | null {
+  const agent = rows.filter((t) => t.executor !== 'python');
+  const running = agent.find((t) => t.outcome === 'running');
+  if (running) return running.key;
+  const ran = (t: TaskRow) => t.tries[t.tries.length - 1]?.ts ?? '';
+  const last = agent.filter(ran).sort((a, b) => ran(b).localeCompare(ran(a)))[0];
+  return last?.key ?? null;
+}