@contraagent/api 0.0.0-stage → 0.1.0

package/src/panels.ts

@@ -0,0 +1,51 @@
+// Panel bodies: what a pipeline's own view returns (`monitor.Panel`). A typed body
+// (tiles, a table, charts, blocks of them) is drawn with the monitor's elements;
+// any other JSON object is shown as a JSON tree.
+import type { components } from './schema.js';
+import type { JsonObject, PanelInfo } from './types.js';
+
+type S = components['schemas'];
+
+export type TilesBody = S['TilesBody'];
+export type PanelTile = S['PanelTile'];
+export type TableBody = S['TableBody'];
+export type TableColumn = S['TableColumn'];
+export type ColumnsBody = S['ColumnsBody'];
+export type LinesBody = S['LinesBody'];
+export type HeatmapBody = S['HeatmapBody'];
+export type HBarsBody = S['HBarsBody'];
+export type HBar = S['HBar'];
+export type StatusGridBody = S['StatusGridBody'];
+export type GridCell = S['GridCell'];
+export type NoteBody = S['NoteBody'];
+export type BlocksBody = S['BlocksBody'];
+export type ChartSeries = S['ChartSeries'];
+/** How a number of a body is written: `pct` is a fraction (0.97 is 97%), `duration` seconds, `datetime` an ISO time. */
+export type ValueFormat = NonNullable<TableColumn['format']>;
+
+/** A body with a `type`: drawn with the monitor's own elements. */
+export type TypedPanelBody =
+  | TilesBody
+  | TableBody
+  | ColumnsBody
+  | LinesBody
+  | HeatmapBody
+  | HBarsBody
+  | StatusGridBody
+  | NoteBody
+  | BlocksBody;
+/** What a panel returns: a typed body, or any JSON object. */
+export type PanelBody = TypedPanelBody | JsonObject;
+
+/** The `type` of each typed body. */
+export const PANEL_TYPES = ['tiles', 'table', 'columns', 'lines', 'heatmap', 'hbars', 'status_grid', 'note', 'blocks'] as const;
+
+/** `body` as a typed body, or null when it is any other JSON object (a JSON tree). */
+export function typedBody(body: unknown): TypedPanelBody | null {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return null;
+  const type = (body as { type?: unknown }).type;
+  return typeof type === 'string' && (PANEL_TYPES as readonly string[]).includes(type) ? (body as TypedPanelBody) : null;
+}
+
+/** A panel computed per run: a tab of each run, sent on its live feed (a trends panel is not). */
+export const isRunPanel = (p: Pick<PanelInfo, 'scope'>): boolean => (p.scope ?? 'run') === 'run';

package/src/quota.ts

@@ -0,0 +1,78 @@
+// A subscription's utilization as the coding agent reported it. Claude Code
+// sends a reading when a session starts or resumes, never when it ends; every
+// reading is account-wide (parallel tasks and anything else on the account
+// share it). So a try has readings at its session starts, and the closest
+// reading after it ended is whatever session started next. Pure.
+import type { JournalRow, QuotaReading } from './types.js';
+
+/** A reading, and the row (try) it came with. */
+export interface SourcedReading {
+  reading: QuotaReading;
+  key: string;
+  attempt: number;
+}
+
+const at = (r: QuotaReading): number => Date.parse(r.observed_at ?? '');
+
+const usable = (r: QuotaReading): boolean =>
+  !Number.isNaN(at(r)) && (r.five_hour_pct != null || r.seven_day_pct != null);
+
+/** Every reading of the run, oldest first. */
+export function runReadings(journal: readonly JournalRow[]): SourcedReading[] {
+  const out: SourcedReading[] = [];
+  for (const row of journal) {
+    for (const reading of row.quota ?? []) {
+      if (usable(reading)) out.push({ reading, key: row.key, attempt: row.attempt ?? 0 });
+    }
+  }
+  return out.sort((a, b) => at(a.reading) - at(b.reading));
+}
+
+/** One account's utilization over the run: the credential that reported it, and the account (`account`, a digest; '' when not known). */
+export interface AccountUsage {
+  credential: string;
+  account?: string;
+  first: QuotaReading;
+  last: QuotaReading;
+}
+
+/** The account a reading is of: its credential and its account digest. `ambient` on two coding agents is two accounts. */
+export const accountKey = (r: { credential?: string | null; account?: string | null }): string => `${r.credential ?? ''}\u0000${r.account ?? ''}`;
+
+/** Per account, the run's first and last reading; the account with the highest weekly use first. */
+export function runAccounts(journal: readonly JournalRow[]): AccountUsage[] {
+  const by = new Map<string, QuotaReading[]>();
+  for (const { reading } of runReadings(journal)) {
+    const k = accountKey(reading);
+    let list = by.get(k);
+    if (!list) by.set(k, (list = []));
+    list.push(reading);
+  }
+  const out: AccountUsage[] = [];
+  for (const list of by.values()) {
+    const first = list[0];
+    const last = list[list.length - 1];
+    if (first && last) out.push({ credential: last.credential ?? '', account: last.account ?? '', first, last });
+  }
+  return out.sort((a, b) => (b.last.seven_day_pct ?? 0) - (a.last.seven_day_pct ?? 0));
+}
+
+export interface TryQuota {
+  /** The try's first reading: usage when its (first) session started. */
+  start: QuotaReading | null;
+  /** The first reading of the same account received after the try ended (`row.ts`), if any. */
+  next: QuotaReading | null;
+}
+
+/** One try's readings: at its start, and the next one observed after it ended. */
+export function tryQuota(row: JournalRow, readings: readonly SourcedReading[]): TryQuota {
+  const own = (row.quota ?? []).filter(usable).sort((a, b) => at(a) - at(b));
+  const ended = Date.parse(row.ts);
+  const start = own[0] ?? null;
+  const account = start === null ? '' : accountKey(start);
+  const next =
+    start === null || Number.isNaN(ended)
+      ? undefined
+      : readings.find((r) => at(r.reading) > ended && accountKey(r.reading) === account);
+  return { start, next: next?.reading ?? null };
+}

package/src/reasons.ts

@@ -0,0 +1,57 @@
+// What a journal row's `reason` says, read as data: the inputs a refusal names,
+// and paths cut to the run directory. Pure; the words for them are the UI's.
+
+/** One input a task was refused for, read from its `invalid input: ...` reason. */
+export interface InputProblem {
+  /** The file, as the reason gives it (absolute). */
+  path: string;
+  /** The key of the task that writes it, when the reason names one. */
+  producer: string;
+  /**
+   * `missing`: the file is not there; `checks`: it is there and failed its checks;
+   * `failed`: it is there, written by a task that did not succeed (`producer`).
+   */
+  problem: 'missing' | 'checks' | 'failed';
+}
+
+/**
+ * The inputs a refused task's reason names (`invalid input: input from <key> is
+ * missing: <path>`, `invalid input: input from <key> ended <stop>: <path>`,
+ * `invalid input: <path>: required input is missing`, `invalid input: <path>:
+ * <check error>`), in order; [] for any other reason.
+ */
+export function inputProblems(reason: string | null | undefined): InputProblem[] {
+  const m = /^invalid input:\s*(.*)$/s.exec(reason || '');
+  if (!m) return [];
+  const out: InputProblem[] = [];
+  for (const part of (m[1] ?? '').split('; ')) {
+    let x = /^input from (\S+) is missing: (\S+)/.exec(part);
+    if (x) {
+      out.push({ path: x[2] ?? '', producer: x[1] ?? '', problem: 'missing' });
+      continue;
+    }
+    x = /^input from (\S+) ended \S+: (\S+)/.exec(part);
+    if (x) {
+      out.push({ path: x[2] ?? '', producer: x[1] ?? '', problem: 'failed' });
+      continue;
+    }
+    x = /^(\S+?): required input is missing/.exec(part);
+    if (x) {
+      out.push({ path: x[1] ?? '', producer: '', problem: 'missing' });
+      continue;
+    }
+    x = /^(\S+?): /.exec(part);
+    if (x && !out.some((o) => o.path === x?.[1])) out.push({ path: x[1] ?? '', producer: '', problem: 'checks' });
+  }
+  return out;
+}
+
+/**
+ * A text from the run (a failure reason) with absolute paths inside the run
+ * directory cut to the part after `runs/<run>/`: `out/summarize/zeta.json`.
+ */
+export function runRelative(text: string | null | undefined, run: string): string {
+  if (!text || !run) return text ?? '';
+  const esc = run.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return text.replace(new RegExp(`(?:/[^\\s:'"]*)?/${esc}/`, 'g'), '');
+}

package/src/run-state.ts

@@ -0,0 +1,166 @@
+// What the live feed of one run folds into, and the questions the views ask of it.
+// Pure: no I/O, no clock unless passed in.
+import { runActivity } from './derive.js';
+import type {
+  CursorView,
+  JournalRow,
+  JsonObject,
+  Outputs,
+  Plan,
+  Procs,
+  RunFeedMessage,
+  RunSummary,
+} from './types.js';
+
+/** The newest rows kept; older ones drop off the front. */
+export const JOURNAL_CAP = 4000;
+
+export interface RunState {
+  /** Finished attempts in arrival order, at most `JOURNAL_CAP`. */
+  journal: JournalRow[];
+  /** Null until the first `procs` message. */
+  procs: Procs | null;
+  plan: Plan;
+  outputs: Outputs;
+  /** Null for a run that keeps no cursor. */
+  cursor: CursorView | null;
+  panels: Record<string, JsonObject>;
+  /** The feed's replay is over (`ready`): a journal row after this is new. */
+  ready: boolean;
+}
+
+export function emptyRunState(): RunState {
+  return {
+    journal: [],
+    procs: null,
+    plan: { nodes: [], groups: [], flow_calls: [] },
+    outputs: { contracts: [], tally: { valid: 0, invalid: 0, refused: 0, pending: 0, failed: 0, running: 0 } },
+    cursor: null,
+    panels: {},
+    ready: false,
+  };
+}
+
+/** A feed message, or the feed (re)connecting: the server then replays the journal from the start. */
+export type RunAction = RunFeedMessage | { event: 'connected' };
+
+/** Fold a batch of actions into the state. The journal is copied once per batch, not per row. */
+export function reduceRun(state: RunState, actions: readonly RunAction[]): RunState {
+  let next = state;
+  let rows: JournalRow[] | null = null;
+  const flush = () => {
+    if (!rows) return;
+    const all = next.journal.concat(rows);
+    next = { ...next, journal: all.length > JOURNAL_CAP ? all.slice(all.length - JOURNAL_CAP) : all };
+    rows = null;
+  };
+  for (const a of actions) {
+    if (a.event === 'journal') {
+      (rows ??= []).push(a.data);
+      continue;
+    }
+    flush();
+    switch (a.event) {
+      case 'connected':
+        next = { ...next, journal: [], ready: false };
+        break;
+      case 'ready':
+        next = { ...next, ready: true };
+        break;
+      case 'procs':
+        next = { ...next, procs: a.data };
+        break;
+      case 'plan':
+        next = { ...next, plan: a.data };
+        break;
+      case 'outputs':
+        next = { ...next, outputs: a.data };
+        break;
+      case 'cursor':
+        next = { ...next, cursor: a.data };
+        break;
+      default:
+        next = { ...next, panels: { ...next.panels, [a.event.slice('panel:'.length)]: a.data } };
+    }
+  }
+  flush();
+  return next;
+}
+
+// --- selectors ----------------------------------------------------------------
+
+/** A finished attempt that neither completed, nor was partial (ok, its output a placeholder), nor was skipped. */
+export const isBad = (row: { stop?: string | undefined }): boolean =>
+  !!row.stop && row.stop !== 'completed' && row.stop !== 'partial' && row.stop !== 'skipped';
+
+/** A Python task (the journal, plan and contracts say who executed it). */
+export const isPython = (x: { executor?: string | undefined }): boolean => x.executor === 'python';
+
+/**
+ * Which start of the run each of one task's journal rows (in journal order) belongs
+ * to, 0 for the first start that ran it: a resumed run numbers a task's attempts
+ * from 0 again, so a row whose attempt is not above the one before it begins the
+ * next start that ran the task.
+ */
+export function runStarts(rows: readonly { attempt?: number | null | undefined }[]): number[] {
+  let start = 0;
+  return rows.map((r, i) => {
+    const before = rows[i - 1];
+    if (before && (r.attempt ?? 0) <= (before.attempt ?? 0)) start++;
+    return start;
+  });
+}
+
+/** A stable identity for a journal row. */
+export const rowId = (row: JournalRow): string => `${row.ts}|${row.key}`;
+
+export const runRow = (runs: readonly RunSummary[], run: string): RunSummary | undefined =>
+  runs.find((r) => r.run === run);
+
+/** The run's process is alive (by the feed, or by the run list): `runActivity` is `running`. */
+export const isRunLive = (state: RunState, summary: RunSummary | undefined): boolean =>
+  runActivity(summary, !!state.procs?.alive) === 'running';
+
+/** Something running right now: an agent launch or a Python task. */
+export interface Activity {
+  /** `llm` for an agent launch, `py` for a Python task. */
+  cls: 'llm' | 'py';
+  /** Stable across updates: the task key, prefixed by kind of activity. */
+  id: string;
+  kind: string;
+  /** The unit; '' for a task of the whole run. */
+  unit: string;
+  detail: string;
+  /** Seconds it has run, as of the procs message. */
+  ageS: number;
+  /** The task key, for an agent launch (it has a transcript). */
+  key: string;
+}
+
+export function liveActivities(procs: Procs | null): Activity[] {
+  if (!procs) return [];
+  return [
+    ...procs.launches.map(
+      (c): Activity => ({
+        cls: 'llm',
+        id: `c:${c.key}`,
+        kind: c.kind || 'task',
+        unit: c.unit || '',
+        detail: [c.unit, c.model || c.role].filter(Boolean).join(' | '),
+        ageS: c.age_s,
+        key: c.key,
+      }),
+    ),
+    ...procs.python_tasks.map(
+      (p): Activity => ({
+        cls: 'py',
+        id: `p:${p.key}`,
+        kind: p.kind || 'task',
+        unit: p.unit || '',
+        detail: p.unit || 'Python',
+        ageS: p.age_s,
+        key: '',
+      }),
+    ),
+  ];
+}