@contraagent/api 0.0.0-stage → 0.1.0

package/src/spend.ts

@@ -0,0 +1,108 @@
+// What the coding agents spent: tokens and cost, summed per attempt, task, kind
+// and run from the journal. A row without usage or cost (a Python task, a task
+// that never started, an agent that reports none) adds nothing and is not
+// counted as zero. Pure.
+import type { JournalRow, ModelUsage } from './types.js';
+
+export interface Spend {
+  input: number;
+  output: number;
+  /** Input served from the prompt cache. */
+  cache_read: number;
+  /** Input written to the prompt cache. */
+  cache_creation: number;
+  /** API calls. */
+  calls: number;
+  /** USD as the coding agents report it; null when no row reported a cost. */
+  cost: number | null;
+  /** Rows that reported tokens or a cost. */
+  reported: number;
+}
+
+export const emptySpend = (): Spend => ({ input: 0, output: 0, cache_read: 0, cache_creation: 0, calls: 0, cost: null, reported: 0 });
+
+/** Every token of a spend: input, output and both cache kinds. */
+export const totalTokens = (s: Spend): number => s.input + s.output + s.cache_read + s.cache_creation;
+
+/** Add one row's usage and cost to `s` (in place); returns `s`. */
+export function addRow(s: Spend, r: JournalRow): Spend {
+  const u = r.usage;
+  if (!u && (r.cost_usd === null || r.cost_usd === undefined)) return s;
+  if (u) {
+    s.input += u.input ?? 0;
+    s.output += u.output ?? 0;
+    s.cache_read += u.cache_read ?? 0;
+    s.cache_creation += u.cache_creation ?? 0;
+    s.calls += u.calls ?? 0;
+  }
+  if (r.cost_usd !== null && r.cost_usd !== undefined) s.cost = (s.cost ?? 0) + r.cost_usd;
+  s.reported++;
+  return s;
+}
+
+/** The spend of some rows; null when none of them reported any. */
+export function spendOf(rows: readonly JournalRow[]): Spend | null {
+  const s = emptySpend();
+  for (const r of rows) addRow(s, r);
+  return s.reported ? s : null;
+}
+
+/** One row's spend; null when it reported none. */
+export const rowSpend = (r: JournalRow): Spend | null => spendOf([r]);
+
+export interface SpendGroup {
+  /** A task key, or a kind. */
+  id: string;
+  kind: string;
+  unit: string;
+  spend: Spend;
+  /** Fraction (0..1) of the run's reported cost; null when the run reported none. */
+  share: number | null;
+}
+
+function group(journal: readonly JournalRow[], idOf: (r: JournalRow) => string): SpendGroup[] {
+  const by = new Map<string, SpendGroup>();
+  const total = emptySpend();
+  for (const r of journal) {
+    addRow(total, r);
+    const id = idOf(r);
+    let g = by.get(id);
+    if (!g) by.set(id, (g = { id, kind: r.kind, unit: r.unit ?? '', spend: emptySpend(), share: null }));
+    addRow(g.spend, r);
+  }
+  const out = [...by.values()].filter((g) => g.spend.reported);
+  for (const g of out) g.share = total.cost ? (g.spend.cost ?? 0) / total.cost : null;
+  // Most expensive first; by tokens when no cost was reported.
+  return out.sort((a, b) => (b.spend.cost ?? 0) - (a.spend.cost ?? 0) || totalTokens(b.spend) - totalTokens(a.spend));
+}
+
+/** Spend per task (key), most expensive first. */
+export const spendByTask = (journal: readonly JournalRow[]): SpendGroup[] => group(journal, (r) => r.key);
+
+/** Spend per kind, most expensive first. */
+export const spendByKind = (journal: readonly JournalRow[]): SpendGroup[] =>
+  group(journal, (r) => r.kind).map((g) => ({ ...g, unit: '' }));
+
+/** What a model's use is measured by: its cost, its tokens, its time, its agent sessions. */
+export type ModelMeasure = 'cost' | 'tokens' | 'time' | 'sessions';
+
+/** Every token a model's sessions used: input, output and both cache kinds. */
+export const modelTokens = (m: ModelUsage): number => (m.input ?? 0) + (m.output ?? 0) + (m.cache_read ?? 0) + (m.cache_creation ?? 0);
+
+/** A model's use by `measure`; null for a cost no session on it reported. */
+export function modelValue(m: ModelUsage, measure: ModelMeasure): number | null {
+  switch (measure) {
+    case 'cost':
+      return m.cost_usd ?? null;
+    case 'tokens':
+      return modelTokens(m);
+    case 'time':
+      return m.wall_s ?? 0;
+    case 'sessions':
+      return m.sessions;
+  }
+}
+
+/** The measures some of `models` has a value for, in the order a reader picks them. */
+export const modelMeasures = (models: readonly ModelUsage[]): ModelMeasure[] =>
+  (['cost', 'tokens', 'time', 'sessions'] as const).filter((x) => models.some((m) => (modelValue(m, x) ?? 0) > 0));

package/src/store.ts

@@ -0,0 +1,338 @@
+// The monitor's data, live: the run list, the selected run's feed folded into a
+// `RunState`, and a change notification. No UI framework: a Lit controller, a
+// React hook or plain code can subscribe alike.
+import { ApiError, createMonitorClient, type MonitorClient } from './client.js';
+import type { RunFeedOpener } from './export.js';
+import { openRunFeed, type FeedOptions, type Unsubscribe } from './feed.js';
+import { emptyRunState, reduceRun, rowId, type RunAction, type RunState } from './run-state.js';
+import { isRunPanel } from './panels.js';
+import type { Hosts, Info, JournalRow, JsonObject, RunFeedMessage, RunSummary, Trends, TrendsQuery } from './types.js';
+
+export interface MonitorSnapshot {
+  info: Info;
+  runs: RunSummary[];
+  /** The hosts behind the runs, on a hub (`Info.hosts`); null elsewhere and until they arrive. */
+  hosts: Hosts | null;
+  /** The run whose feed is open; '' for none. */
+  run: string;
+  state: RunState;
+  /** The feed is connected. */
+  connected: boolean;
+  /** Journal rows (by `rowId`) that arrived in the last few seconds, after the replay. */
+  fresh: ReadonlySet<string>;
+  /** The run list has been answered: `runs` is the server's, not the empty start. */
+  runsLoaded: boolean;
+  /** Why the last request for `info`, `runs` or (on a hub) `hosts` got no answer; null while all are answered. */
+  error: ApiError | null;
+  /** The trends of the period last asked for (`loadTrends`); null until one is asked for. */
+  trends: TrendsView | null;
+}
+
+/** The trends of one period, and the trend panels' bodies over it. */
+export interface TrendsView {
+  query: TrendsQuery;
+  /** null until the first answer for this query. */
+  data: Trends | null;
+  /** Each trend panel's body (`Panel(scope="trends")`), by name, as it arrives. */
+  panels: Readonly<Record<string, JsonObject>>;
+  loading: boolean;
+  /** Why the last request for the trends got no answer. */
+  error: ApiError | null;
+}
+
+export interface StoreOptions {
+  baseUrl?: string;
+  client?: MonitorClient;
+  feed?: FeedOptions;
+  /** Opens a run's feed instead of the server's `/events` (an export's: `openExportFeed`). */
+  openRunFeed?: RunFeedOpener;
+  /** How often the run list (and on a hub, the host list) is refreshed; 0: never (an export). */
+  runsEveryMs?: number;
+  /** Feed messages are folded in batches this far apart. */
+  batchMs?: number;
+  /** How long a new journal row counts as fresh. */
+  freshMs?: number;
+}
+
+const DEFAULT_INFO: Info = { title: 'contraagent', panels: [], api_version: '' };
+
+/** A client given in the options may throw something else: it counts as no response from `url`. */
+const asApiError = (e: unknown, url: string): ApiError => (e instanceof ApiError ? e : new ApiError(url, 'network'));
+
+export class MonitorStore {
+  readonly client: MonitorClient;
+  private snap: MonitorSnapshot = {
+    info: DEFAULT_INFO,
+    runs: [],
+    hosts: null,
+    run: '',
+    state: emptyRunState(),
+    connected: false,
+    fresh: new Set(),
+    runsLoaded: false,
+    error: null,
+    trends: null,
+  };
+  /** The trends asked for last (`loadTrends`), kept fresh with the run list; null: none. */
+  private trendsQuery: TrendsQuery | null = null;
+  /** Counts the trend requests: an answer to an older one is dropped. */
+  private trendsAsked = 0;
+  /** The run list's records (`runsKey`) the trends shown were asked over: a refresh asks again only when they changed. */
+  private trendsOver: string | null = null;
+  /** A refresh is under way: a call meanwhile does nothing, and the next one is scheduled after it ends. */
+  private refreshing = false;
+  /** A trends request a refresh started is under way: no second one until it ends. */
+  private trendsBusy = false;
+  /** Why the last request for `info`, for `runs`, and for `hosts` got no answer. */
+  private infoError: ApiError | null = null;
+  private runsError: ApiError | null = null;
+  private hostsError: ApiError | null = null;
+  private infoLoaded = false;
+  private stopped = false;
+  private readonly listeners = new Set<(s: MonitorSnapshot) => void>();
+  private readonly rowListeners = new Set<(row: JournalRow) => void>();
+  private closeFeed: Unsubscribe | null = null;
+  private queue: RunAction[] = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly opts: Required<Pick<StoreOptions, 'runsEveryMs' | 'batchMs' | 'freshMs'>> & StoreOptions;
+
+  constructor(opts: StoreOptions = {}) {
+    this.opts = { runsEveryMs: 5000, batchMs: 50, freshMs: 4000, ...opts };
+    this.client = opts.client ?? createMonitorClient(opts.baseUrl === undefined ? {} : { baseUrl: opts.baseUrl });
+  }
+
+  get snapshot(): MonitorSnapshot {
+    return this.snap;
+  }
+
+  /** Called on every change, with the new snapshot. */
+  subscribe(fn: (s: MonitorSnapshot) => void): Unsubscribe {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  /** Called for each journal row that arrives after the replay: a task that just finished. */
+  onNewRow(fn: (row: JournalRow) => void): Unsubscribe {
+    this.rowListeners.add(fn);
+    return () => this.rowListeners.delete(fn);
+  }
+
+  /**
+   * Load the title, panels and run list, and keep the run list fresh. A request
+   * that gets no answer sets `error`; the title and panels are asked for again
+   * with each refresh until they arrive.
+   */
+  async start(): Promise<void> {
+    this.stopped = false;
+    await this.refresh();
+    this.schedule();
+  }
+
+  /** The next refresh, `runsEveryMs` after this one ended: refreshes never overlap, however slow the answers. */
+  private schedule(): void {
+    if (this.stopped || this.opts.runsEveryMs <= 0 || this.pollTimer) return;
+    this.pollTimer = setTimeout(() => {
+      this.pollTimer = null;
+      void this.refresh().finally(() => this.schedule());
+    }, this.opts.runsEveryMs);
+  }
+
+  private async refresh(): Promise<void> {
+    if (this.refreshing) return;
+    this.refreshing = true;
+    try {
+      if (!this.infoLoaded) await this.loadInfo();
+      await this.refreshRuns();
+    } finally {
+      this.refreshing = false;
+    }
+    // The trends are asked for again only when the runs' records or the trend panels (a
+    // panel list that arrived after them) changed, and not awaited here: a slow trend
+    // panel holds back no run list.
+    const query = this.trendsQuery;
+    if (query && !this.trendsBusy && !this.stopped && this.trendsKey() !== this.trendsOver) {
+      this.trendsBusy = true;
+      void this.fetchTrends(query).finally(() => (this.trendsBusy = false));
+    }
+  }
+
+  /** What the trends are made of, as far as the run list says: each run and its last record; and the trend panels asked for over them. */
+  private trendsKey(): string {
+    const runs = this.snap.runs.map((r) => `${r.run}\t${r.last_ts}\t${r.attempts}`).join('\n');
+    return `${runs}\n\n${this.trendPanelNames().join('\n')}`;
+  }
+
+  private trendPanelNames(): string[] {
+    return this.snap.info.panels.filter((p) => p.scope === 'trends').map((p) => p.name);
+  }
+
+  /**
+   * Load the trends of `query` (`/api/trends`) and the trend panels over it, and keep them
+   * fresh with the run list until `closeTrends`. The trends of another query stay shown
+   * until the new ones arrive (`loading`).
+   */
+  async loadTrends(query: TrendsQuery): Promise<void> {
+    const same = this.snap.trends && JSON.stringify(this.snap.trends.query) === JSON.stringify(query);
+    this.trendsQuery = query;
+    this.set({ trends: { query, data: same ? this.snap.trends!.data : (this.snap.trends?.data ?? null), panels: same ? this.snap.trends!.panels : {}, loading: true, error: null } });
+    await this.fetchTrends(query);
+  }
+
+  /** Stop keeping the trends fresh (the page left them). */
+  closeTrends(): void {
+    this.trendsQuery = null;
+  }
+
+  /**
+   * Ask for the trends of `query` and each trend panel over it. Each answer is shown as it
+   * arrives, so a slow panel holds back neither the trends nor another panel; an answer to
+   * an older request is dropped.
+   */
+  private async fetchTrends(query: TrendsQuery): Promise<void> {
+    const asked = ++this.trendsAsked;
+    this.trendsOver = this.trendsKey();
+    const view = (): TrendsView | null => (asked === this.trendsAsked && !this.stopped ? this.snap.trends : null);
+    const names = this.trendPanelNames();
+    const trends = this.client.trends(query).then(
+      (data) => {
+        const v = view();
+        if (v) this.set({ trends: { ...v, query, data, loading: false, error: null } });
+      },
+      (e: unknown) => {
+        const v = view();
+        if (v) this.set({ trends: { ...v, query, loading: false, error: asApiError(e, `${this.client.baseUrl}/api/trends`) } });
+      },
+    );
+    const panel = (name: string, body: JsonObject) => {
+      const v = view();
+      if (v) this.set({ trends: { ...v, panels: { ...v.panels, [name]: body } } });
+    };
+    const bodies = names.map((n) =>
+      this.client.trendsPanel(n, query).then(
+        (body) => panel(n, body),
+        (e: unknown) => panel(n, { error: String(e) }),
+      ),
+    );
+    await Promise.allSettled([trends, ...bodies]);
+  }
+
+  private async loadInfo(): Promise<void> {
+    try {
+      const before = this.panelNames();
+      const info = await this.client.info();
+      if (this.stopped) return;
+      this.infoLoaded = true;
+      this.infoError = null;
+      this.set({ info });
+      // A run opened before the panel list arrived listens for no panel: open it again.
+      if (this.snap.run && this.panelNames() !== before) this.reopen();
+    } catch (e) {
+      this.infoError = asApiError(e, `${this.client.baseUrl}/api/info`);
+    }
+  }
+
+  /** Fetch the run list, and on a hub the host list beside it: both refresh together, so a run's host reads the same in both. */
+  async refreshRuns(): Promise<void> {
+    const [runs, hosts] = await Promise.allSettled([this.client.runs(), this.snap.info.hosts ? this.client.hosts() : Promise.resolve(null)]);
+    if (this.stopped) return;
+    // A failed request keeps the last list.
+    const patch: Partial<MonitorSnapshot> = {};
+    if (runs.status === 'fulfilled') {
+      patch.runs = runs.value;
+      patch.runsLoaded = true;
+      this.runsError = null;
+    } else this.runsError = asApiError(runs.reason, `${this.client.baseUrl}/api/runs`);
+    if (hosts.status === 'fulfilled') {
+      patch.hosts = hosts.value;
+      this.hostsError = null;
+    } else this.hostsError = asApiError(hosts.reason, `${this.client.baseUrl}/api/hosts`);
+    const error = this.infoError ?? this.runsError ?? this.hostsError;
+    // The same failure again keeps the same `error`.
+    if (error?.message !== this.snap.error?.message) patch.error = error;
+    if (Object.keys(patch).length) this.set(patch);
+  }
+
+  private panelNames(): string {
+    return this.snap.info.panels.filter(isRunPanel).map((p) => p.name).join('\n');
+  }
+
+  /** Open the current run's feed again (the server replays it from the start). */
+  private reopen(): void {
+    const run = this.snap.run;
+    this.closeFeed?.();
+    this.closeFeed = null;
+    this.selectRun(run);
+  }
+
+  /** Open `run`'s feed (closing the previous one); '' closes it. */
+  selectRun(run: string): void {
+    if (run === this.snap.run && (this.closeFeed || !run)) return;
+    this.closeFeed?.();
+    this.closeFeed = null;
+    this.queue = [];
+    this.set({ run, state: emptyRunState(), connected: false, fresh: new Set() });
+    if (!run) return;
+    const panels = this.snap.info.panels.filter(isRunPanel).map((p) => p.name);
+    const on = {
+      open: () => {
+        this.push({ event: 'connected' });
+        this.set({ connected: true });
+      },
+      error: () => this.set({ connected: false }),
+      message: (msg: RunFeedMessage) => this.push(msg),
+    };
+    this.closeFeed = this.opts.openRunFeed
+      ? this.opts.openRunFeed(run, panels, on)
+      : openRunFeed(run, panels, on, { ...(this.opts.baseUrl === undefined ? {} : { baseUrl: this.opts.baseUrl }), ...this.opts.feed });
+  }
+
+  /** Close the feed and stop refreshing; an answer that arrives later is dropped. */
+  stop(): void {
+    this.stopped = true;
+    this.closeFeed?.();
+    this.closeFeed = null;
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    this.pollTimer = null;
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+  }
+
+  private push(a: RunAction): void {
+    this.queue.push(a);
+    this.flushTimer ??= setTimeout(() => this.flush(), this.opts.batchMs);
+  }
+
+  private flush(): void {
+    this.flushTimer = null;
+    const batch = this.queue;
+    this.queue = [];
+    // Rows that arrive once the replay is over are new: announce them and mark them fresh.
+    let ready = this.snap.state.ready;
+    const fresh: JournalRow[] = [];
+    for (const a of batch) {
+      if (a.event === 'connected') ready = false;
+      else if (a.event === 'ready') ready = true;
+      else if (a.event === 'journal' && ready) fresh.push(a.data);
+    }
+    const state = reduceRun(this.snap.state, batch);
+    if (!fresh.length) {
+      this.set({ state });
+      return;
+    }
+    const ids = new Set(this.snap.fresh);
+    for (const row of fresh) ids.add(rowId(row));
+    this.set({ state, fresh: ids });
+    for (const row of fresh) for (const fn of this.rowListeners) fn(row);
+    setTimeout(() => {
+      const left = new Set(this.snap.fresh);
+      for (const row of fresh) left.delete(rowId(row));
+      this.set({ fresh: left });
+    }, this.opts.freshMs);
+  }
+
+  private set(patch: Partial<MonitorSnapshot>): void {
+    this.snap = { ...this.snap, ...patch };
+    for (const fn of this.listeners) fn(this.snap);
+  }
+}

package/src/types.ts

@@ -0,0 +1,165 @@
+// Names for the generated schema types. `schema.ts` is generated from the
+// monitor's OpenAPI document (`pnpm gen`); everything here is an alias of it.
+import type { components } from './schema.js';
+import type { PanelBody } from './panels.js';
+
+type S = components['schemas'];
+
+export type { components, paths } from './schema.js';
+
+/** A JSON object whose keys a domain chooses (a panel's body, a contract file's content). */
+export type JsonObject = Record<string, unknown>;
+
+export type Info = S['Info'];
+/** What an export holds (`Info.export`): set only when the monitor reads one. */
+export type ExportInfo = S['ExportInfo'];
+export type PanelInfo = S['PanelInfo'];
+export type RunSummary = S['RunSummary'];
+export type Hosts = S['Hosts'];
+export type HostSummary = S['HostSummary'];
+export type AccountQuota = S['AccountQuota'];
+/** What the runs of a period add up to (`/api/trends`). */
+export type Trends = S['Trends'];
+export type TrendKind = S['TrendKind'];
+export type TrendQuota = S['TrendQuota'];
+export type TrendRun = S['TrendRun'];
+/** Which runs `/api/trends` sums: days `from` to `to` (YYYY-MM-DD) in the time zone `tz`, of one `run_group`. */
+export interface TrendsQuery {
+  from?: string;
+  to?: string;
+  tz?: string;
+  run_group?: string;
+}
+
+export type JournalRow = S['JournalRow'];
+/** How one attempt ended (`JournalRow.stop`): a `Stop` of the Python package, or `skipped`. */
+export type Stop = JournalRow['stop'];
+export type Hop = S['Hop'];
+export type SkippedHop = S['SkippedHop'];
+/** Why a credential rests (a cap or the quota rule): what a `SkippedHop` and a `CredentialRest` share. */
+export type Rest = Pick<S['SkippedHop'], 'credential' | 'window' | 'pct' | 'cap' | 'rule' | 'until'>;
+export type TokenUsage = S['TokenUsage'];
+export type QuotaReading = S['QuotaReading'];
+export type JournalPage = S['JournalPage'];
+
+export type Executor = NonNullable<S['PlanNode']['executor']>;
+
+export type Plan = S['Plan'];
+export type PlanNode = S['PlanNode'];
+export type PlanGroup = S['PlanGroup'];
+export type DeferralCause = S['DeferralCause'];
+export type QuotaCap = S['QuotaCap'];
+export type CredentialRest = S['CredentialRest'];
+export type ModelUsage = S['ModelUsage'];
+export type PreflightRecord = S['PreflightRecord'];
+export type DroppedRoute = S['DroppedRoute'];
+export type Substitution = S['Substitution'];
+export type KeptKind = S['KeptKind'];
+export type TaskState = PlanNode['state'];
+export type Frame = S['Frame'];
+export type Loop = S['Loop'];
+export type FlowCallNode = S['FlowCallNode'];
+export type FlowState = FlowCallNode['state'];
+export type TimeBoxRecord = S['TimeBoxRecord'];
+
+export type Outputs = S['Outputs'];
+export type OutputTally = S['OutputTally'];
+export type ContractRecord = S['ContractRecord'];
+export type ContractSpec = S['ContractSpec'];
+export type ContractField = S['ContractField'];
+export type ContractStatus = NonNullable<ContractSpec['status']>;
+export type FileView = S['FileView'];
+
+export type TaskDefinition = S['TaskDefinition'];
+export type DefinitionFile = S['DefinitionFile'];
+
+export type CursorView = S['CursorView'];
+export type UnitPosition = S['UnitPosition'];
+
+export type Procs = S['Procs'];
+export type ProcNode = S['ProcNode'];
+export type AgentProcess = S['AgentProcess'];
+export type InflightPythonTask = S['InflightPythonTask'];
+
+export type TaskDetail = S['TaskDetail'];
+export type TaskLaunch = S['TaskLaunch'];
+export type TaskIO = S['TaskIO'];
+export type UpstreamTask = S['UpstreamTask'];
+export type DownstreamTask = S['DownstreamTask'];
+
+// --- transcripts -----------------------------------------------------------
+
+export type StreamPage = S['StreamPage'];
+export type LaunchEvent = S['LaunchEvent'];
+export type MessageUpdateEvent = S['MessageUpdateEvent'];
+export type ToolStartEvent = S['ToolStartEvent'];
+export type ToolEndEvent = S['ToolEndEvent'];
+export type ToolCallEchoEvent = S['ToolCallEchoEvent'];
+export type ToolResultEchoEvent = S['ToolResultEchoEvent'];
+/** Named apart from the DOM's `MessageEvent`. */
+export type TranscriptMessageEvent = S['MessageEvent'];
+export type NoticeEvent = S['NoticeEvent'];
+export type RetryEvent = S['RetryEvent'];
+export type OtherEvent = S['OtherEvent'];
+
+/** One transcript event as the wire carries it: a known model, or an `OtherEvent`. */
+export type TranscriptEvent = StreamPage['events'][number];
+
+/** The transcript events the monitor renders, discriminated by `type`. */
+export type KnownTranscriptEvent =
+  | LaunchEvent
+  | MessageUpdateEvent
+  | ToolStartEvent
+  | ToolEndEvent
+  | ToolCallEchoEvent
+  | ToolResultEchoEvent
+  | TranscriptMessageEvent
+  | NoticeEvent
+  | RetryEvent;
+
+const KNOWN_TYPES: ReadonlySet<string> = new Set<KnownTranscriptEvent['type']>([
+  'launch',
+  'message_update',
+  'tool_execution_start',
+  'tool_execution_update',
+  'tool_execution_end',
+  'acall',
+  'aresult',
+  'message_start',
+  'message_end',
+  'turn_end',
+  'notice',
+  'auto_retry_start',
+]);
+
+/** The event as one of the known models, or null for any other `type`. */
+export function knownEvent(e: TranscriptEvent): KnownTranscriptEvent | null {
+  return KNOWN_TYPES.has(e.type) ? (e as KnownTranscriptEvent) : null;
+}
+
+// --- live feeds --------------------------------------------------------------
+
+/** One message of `/events?run=`: `event` is the SSE event name, `data` its parsed JSON. */
+export type RunMessage = S['RunEvent'];
+// `PanelMessage` is the one whose `event` is a plain string; every other row
+// would also fit its shape, so it is told apart by that, not with `Exclude`.
+type FixedRunMessage = RunMessage extends infer M
+  ? M extends { event: infer E }
+    ? string extends E
+      ? never
+      : M
+    : never
+  : never;
+export type PanelEventName = `panel:${string}`;
+/** A panel's message, with its event name typed. */
+export interface PanelMessage {
+  event: PanelEventName;
+  data: PanelBody;
+}
+/** A run feed message with every `event` name a literal (or `panel:<name>`). */
+export type RunFeedMessage = FixedRunMessage | PanelMessage;
+/** The SSE event names with a fixed meaning, and what each one carries. */
+export type RunEventData = { [M in FixedRunMessage as M['event']]: M['data'] };
+export type RunEventName = keyof RunEventData;
+
+export type StreamMessage = S['StreamMessage'];