@contraagent/ui 0.0.0-stage → 0.1.0

package/src/core/view-route.ts

@@ -0,0 +1,177 @@
+// Where the monitor is: one typed value, kept in the URL. Pure: parsing and
+// formatting only; `view-router.ts` binds it to the browser's history.
+
+export const BUILTIN_TABS = ['overview', 'tasks', 'journal', 'outputs', 'definitions', 'procs', 'stream'] as const;
+export type BuiltinTab = (typeof BUILTIN_TABS)[number];
+/** A built-in view, or a panel the pipeline registered (`panel:<name>`). */
+export type Tab = BuiltinTab | `panel:${string}`;
+
+/** What the task view shows next to (or instead of) the transcript. */
+export const TASK_VIEWS = ['transcript', 'input', 'output', 'definition'] as const;
+export type TaskView = (typeof TASK_VIEWS)[number];
+
+/** A page that is not one run's: `hosts`, the hosts behind a hub's runs; `trends`, the runs of a period. */
+export type Page = '' | 'hosts' | 'trends';
+
+/** The lengths of a period the trends page offers, in days, ending today. */
+export const TREND_DAYS = [7, 14, 30] as const;
+
+export interface ViewRoute {
+  /** '' for a run's views; `hosts` for the hosts (on a hub), with no run. */
+  page: Page;
+  /** The run; '' until one is picked. */
+  run: string;
+  tab: Tab;
+  /** stream tab: the task key whose transcript is open (null: the latest, `latestTask`). */
+  key: string | null;
+  /** stream tab: what the task view shows. */
+  view: TaskView;
+  /** stream tab: the round shown, 1-based (null: follow the latest). */
+  round: number | null;
+  /** definitions tab: the selected kind (null: the default one). */
+  def: string | null;
+  /** tasks and journal tabs: only this kind (kept, and out of the URL, while another tab is shown). */
+  kind: string;
+  /** journal tab: only this stop ('bad': every attempt that did not complete). */
+  stop: string;
+  /** tasks and journal tabs: a text filter. */
+  q: string;
+  /** overview tab: the pipeline graph's layer, its segments joined by `/` ('': the layer the graph opens on). */
+  layer: string;
+  /** overview tab: the unit highlighted in the pipeline graph. */
+  unit: string;
+  /** overview tab: what is selected in the pipeline graph's layer (a node, a loop box or a mark; '' for nothing). */
+  sel: string;
+  /** trends page: the period, the last `days` days (0: the days `from` to `to`, YYYY-MM-DD). */
+  days: number;
+  from: string;
+  to: string;
+  /** trends page: the time zone its days are counted in ('': the browser's). */
+  tz: string;
+  /** trends page: only the runs of this run group. */
+  group: string;
+  /** trends page: the open tab, a trends panel's `tab` ('': the first, the trends). */
+  trendsTab: string;
+}
+
+export type ViewRoutePatch = Partial<ViewRoute>;
+
+export const DEFAULT_VIEW_ROUTE: ViewRoute = {
+  page: '',
+  run: '',
+  tab: 'overview',
+  key: null,
+  view: 'transcript',
+  round: null,
+  def: null,
+  kind: '',
+  stop: '',
+  q: '',
+  layer: '',
+  unit: '',
+  sel: '',
+  days: 14,
+  from: '',
+  to: '',
+  tz: '',
+  group: '',
+  trendsTab: '',
+};
+
+const isTab = (t: string): t is Tab => (BUILTIN_TABS as readonly string[]).includes(t) || /^panel:.+/.test(t);
+const isTaskView = (v: string): v is TaskView => (TASK_VIEWS as readonly string[]).includes(v);
+
+export function parseViewRoute(search: string): ViewRoute {
+  const p = new URLSearchParams(search);
+  const tab = p.get('tab') ?? '';
+  const view = p.get('view') ?? '';
+  const round = Number(p.get('round'));
+  const page: Page = p.get('page') === 'hosts' ? 'hosts' : p.get('page') === 'trends' ? 'trends' : '';
+  const from = p.get('from') ?? '';
+  const to = p.get('to') ?? '';
+  const range = /^\d{4}-\d{2}-\d{2}$/.test(from) && /^\d{4}-\d{2}-\d{2}$/.test(to);
+  const days = Number(p.get('days'));
+  return {
+    page,
+    // A page of no run names none.
+    run: page ? '' : (p.get('run') ?? ''),
+    // The trends page's `tab` is its own (`trendsTab`), not a run's.
+    tab: page !== 'trends' && isTab(tab) ? tab : 'overview',
+    key: p.get('key') || null,
+    view: isTaskView(view) ? view : 'transcript',
+    round: Number.isInteger(round) && round > 0 ? round : null,
+    def: p.get('def') || null,
+    kind: p.get('kind') ?? '',
+    stop: p.get('stop') ?? '',
+    q: p.get('q') ?? '',
+    layer: p.get('layer') ?? '',
+    unit: p.get('unit') ?? '',
+    sel: p.get('sel') ?? '',
+    days: range ? 0 : (TREND_DAYS as readonly number[]).includes(days) ? days : DEFAULT_VIEW_ROUTE.days,
+    from: range ? from : '',
+    to: range ? to : '',
+    tz: p.get('tz') ?? '',
+    group: p.get('group') ?? '',
+    trendsTab: page === 'trends' ? (p.get('tab') ?? '') : '',
+  };
+}
+
+/** The query string for a view route: only what differs from the defaults, and only what its tab uses. */
+export function formatViewRoute(r: ViewRoute): string {
+  if (r.page === 'hosts') return '?page=hosts';
+  if (r.page === 'trends') {
+    const p = new URLSearchParams({ page: 'trends' });
+    if (r.days === 0 && r.from && r.to) {
+      p.set('from', r.from);
+      p.set('to', r.to);
+    } else if (r.days !== DEFAULT_VIEW_ROUTE.days) p.set('days', String(r.days));
+    if (r.tz) p.set('tz', r.tz);
+    if (r.group) p.set('group', r.group);
+    if (r.trendsTab) p.set('tab', r.trendsTab);
+    return `?${p.toString()}`;
+  }
+  const p = new URLSearchParams();
+  if (r.run) p.set('run', r.run);
+  if (r.tab !== 'overview') p.set('tab', r.tab);
+  if (r.tab === 'stream') {
+    if (r.key) p.set('key', r.key);
+    if (r.view !== 'transcript') p.set('view', r.view);
+    if (r.round != null) p.set('round', String(r.round));
+  }
+  if (r.tab === 'definitions' && r.def) p.set('def', r.def);
+  if (r.tab === 'overview' && r.layer) p.set('layer', r.layer);
+  if (r.tab === 'overview' && r.unit) p.set('unit', r.unit);
+  if (r.tab === 'overview' && r.sel) p.set('sel', r.sel);
+  // The filters of the Tasks and History tabs: kept while another tab is shown (going back finds them), named in the URL only on their tabs.
+  const filtered = r.tab === 'tasks' || r.tab === 'journal';
+  if (filtered && r.kind) p.set('kind', r.kind);
+  if (r.tab === 'journal' && r.stop) p.set('stop', r.stop);
+  if (filtered && r.q) p.set('q', r.q);
+  const s = p.toString();
+  return s ? `?${s}` : '';
+}
+
+/** Apply a patch. Leaving a task (another key, run) forgets its view and round; another run forgets every selection. */
+export function applyPatch(r: ViewRoute, patch: ViewRoutePatch): ViewRoute {
+  const next = { ...r, ...patch };
+  if (patch.run !== undefined && patch.run !== r.run) {
+    Object.assign(next, { key: null, def: null, round: null, layer: '', unit: '', sel: '', ...patch });
+  }
+  // A selection belongs to its layer.
+  if (patch.layer !== undefined && patch.layer !== r.layer && patch.sel === undefined) next.sel = '';
+  if (patch.key !== undefined && patch.key !== r.key) {
+    if (patch.view === undefined) next.view = 'transcript';
+    if (patch.round === undefined) next.round = null;
+  }
+  return next;
+}
+
+/**
+ * Whether going from `a` to `b` is a move to another place (a new history entry,
+ * so Back returns) or only a refinement of this one (the entry is replaced, so
+ * typing in a filter, highlighting a unit or selecting in the graph does not fill the history).
+ */
+export function isNewPlace(a: ViewRoute, b: ViewRoute): boolean {
+  const place = (r: ViewRoute) => formatViewRoute({ ...r, kind: '', stop: '', q: '', unit: '', sel: '' });
+  return place(a) !== place(b);
+}

package/src/core/view-router.ts

@@ -0,0 +1,66 @@
+// The view route, bound to the browser's history: navigating pushes an entry for a
+// new place and replaces it for a refinement (a filter), Back and Forward
+// restore it. In `memory` mode (an embedded monitor) the URL is left alone.
+import { applyPatch, formatViewRoute, isNewPlace, parseViewRoute, type ViewRoute, type ViewRoutePatch } from './view-route.js';
+
+export type ViewRouterMode = 'url' | 'memory';
+/** Why the view route changed: the page loaded, the app navigated, or the reader went Back/Forward. */
+export type ViewRouteCause = 'init' | 'push' | 'replace' | 'pop';
+
+export class ViewRouter {
+  private current: ViewRoute;
+
+  constructor(
+    private readonly mode: ViewRouterMode,
+    private readonly onChange: (viewRoute: ViewRoute, cause: ViewRouteCause) => void,
+    initial?: ViewRoutePatch,
+    /** Called before a new history entry is pushed: what is kept per entry belongs to the one being left. */
+    private readonly onLeave: () => void = () => {},
+  ) {
+    const base = mode === 'url' ? parseViewRoute(location.search) : parseViewRoute('');
+    this.current = applyPatch(base, initial ?? {});
+  }
+
+  get viewRoute(): ViewRoute {
+    return this.current;
+  }
+
+  start(): void {
+    if (this.mode === 'url') {
+      history.scrollRestoration = 'manual';
+      addEventListener('popstate', this.onPop);
+    }
+    this.onChange(this.current, 'init');
+  }
+
+  stop(): void {
+    if (this.mode === 'url') removeEventListener('popstate', this.onPop);
+  }
+
+  /**
+   * Go to the view route with `patch` applied. A new place pushes a history entry,
+   * a refinement replaces it; `replace` forces replacing (a default filled in,
+   * not a step the reader took).
+   */
+  navigate(patch: ViewRoutePatch, opts: { replace?: boolean } = {}): void {
+    const next = applyPatch(this.current, patch);
+    if (formatViewRoute(next) === formatViewRoute(this.current)) return;
+    const push = !opts.replace && isNewPlace(this.current, next);
+    this.current = next;
+    if (this.mode === 'url') {
+      const url = `${location.pathname}${formatViewRoute(next)}${location.hash}`;
+      if (push) {
+        this.onLeave();
+        history.pushState({}, '', url);
+      } else {
+        history.replaceState(history.state, '', url);
+      }
+    }
+    this.onChange(next, push ? 'push' : 'replace');
+  }
+
+  private readonly onPop = (): void => {
+    this.current = parseViewRoute(location.search);
+    this.onChange(this.current, 'pop');
+  };
+}

package/src/define/all.ts

@@ -0,0 +1,13 @@
+// Registers every `ca-*` element, and the `cae-*` elements they render.
+import './monitor.js';
+import './overview.js';
+import './pipeline-graph.js';
+import './task-view.js';
+import './transcript.js';
+import './task-table.js';
+import './journal-table.js';
+import './contracts.js';
+import './definitions.js';
+import './kpis.js';
+import './timeline.js';
+import './procs.js';

package/src/define/contracts.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/contracts`: registers <ca-contracts>, the checked files, and the elements it renders.
+export * from '../elements/lists/ca-contracts.js';

package/src/define/definitions.ts

@@ -0,0 +1,3 @@
+// `@contraagent/ui/definitions`: registers <ca-definitions> and <ca-definition>, the task definitions.
+export * from '../elements/lists/ca-definitions.js';
+export * from '../elements/shared/ca-definition.js';

package/src/define/journal-table.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/journal-table`: registers <ca-journal-table>, a run's history, and <cae-data-table>.
+export * from '../elements/lists/ca-journal-table.js';

package/src/define/kpis.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/kpis`: registers <ca-kpis>, a run's figures, and <cae-stat-tiles>.
+export * from '../elements/overview/ca-kpis.js';

package/src/define/monitor.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/monitor`: registers <ca-monitor>, the whole monitor, and every element it renders.
+export * from '../elements/shell/ca-monitor.js';

package/src/define/overview.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/overview`: registers <ca-overview>, a run's overview, and the elements it renders.
+export * from '../elements/overview/ca-overview.js';

package/src/define/pipeline-graph.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/pipeline-graph`: registers <ca-pipeline-graph>, and the `cae-*` elements it renders.
+export * from '../elements/overview/ca-pipeline-graph.js';

package/src/define/procs.ts

@@ -0,0 +1,3 @@
+// `@contraagent/ui/procs`: registers <ca-procs-view> and <ca-proc-tree>, a run's processes.
+export * from '../elements/lists/ca-procs-view.js';
+export * from '../elements/lists/ca-proc-tree.js';

package/src/define/task-table.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/task-table`: registers <ca-task-table>, and <cae-data-table>.
+export * from '../elements/lists/ca-task-table.js';

package/src/define/task-view.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/task-view`: registers <ca-task-view>, one task in detail, and the elements it renders.
+export * from '../elements/task/ca-task-view.js';

package/src/define/timeline.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/timeline`: registers <ca-timeline>, the agent sessions in time, and <cae-lanes>.
+export * from '../elements/overview/ca-timeline.js';

package/src/define/transcript.ts

@@ -0,0 +1,2 @@
+// `@contraagent/ui/transcript`: registers <ca-transcript>, a task's transcript, and <cae-transcript>.
+export * from '../elements/task/ca-transcript.js';

package/src/elements/lists/ca-contracts.ts

@@ -0,0 +1,204 @@
+import { deriveRun, isPython, runRelative, type ContractRecord, type ContractSpec, type ContractStatus, type JournalRow, type Outputs, type Plan, type TaskOutcome } from '@contraagent/api';
+import { localized, msg, str } from '@lit/localize';
+import { LitElement, css, html, nothing } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { repeat } from 'lit/directives/repeat.js';
+import { emit } from '../../core/events.js';
+import { RememberedSet } from '../../core/memory.js';
+import type { TaskView } from '../../core/view-route.js';
+import { base } from '@contraagent/elements/styles';
+import { executorIcon, executorIconStyles } from '../../words/executor.js';
+import { kindUnit } from '../../words/format.js';
+import { correctionTip, correctionsLabel, notRunText, type Producer } from '../../words/contract.js';
+import { contractChip, contractStyles, fieldCheckTable, fileConditions, inputChip } from '../shared/contract-parts.js';
+
+const CT_ORDER: readonly ContractStatus[] = ['invalid', 'refused', 'failed', 'running', 'pending', 'valid'];
+
+/** Output contracts per status, worst first; a line of text when none is declared. */
+export function ctChips(outputs: Outputs | null) {
+  const t = outputs?.tally;
+  const chips = t ? CT_ORDER.filter((k) => t[k]) : [];
+  return chips.length
+    ? chips.map((k) => contractChip(k, t?.[k]))
+    : html`<span class="meta">${msg('No checked files')}</span>`;
+}
+
+const shortPath = (p: string) => p.split('/').slice(-2).join('/');
+
+/** A task as the reader names it: "kind · unit" (a run-scope task: its kind). */
+export const taskName = (c: { key: string; kind?: string; unit?: string }): string =>
+  kindUnit({ kind: c.kind || c.key, unit: c.unit && c.unit !== c.key ? c.unit : '' });
+
+/** Problems first (the order of `CT_ORDER`), then by task. */
+const rank = (s: ContractStatus | null | undefined) => (s ? CT_ORDER.indexOf(s) : CT_ORDER.length);
+
+/**
+ * The files each task must write (`OutputContract`) and read (`InputContract`),
+ * problems first, each checked field by field against its schema. Links open
+ * the task (`ca-open-task`).
+ *
+ * @fires ca-open-task - `{key, view}`: a link to the task's input, output or transcript
+ */
+@customElement('ca-contracts')
+@localized()
+export class CaContracts extends LitElement {
+  static override styles = [
+    base,
+    contractStyles,
+    executorIconStyles,
+    css`
+      :host { display: block; container-type: inline-size; }
+      .ct-row { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 10px; }
+      details.ct { border-top: 1px solid var(--line); }
+      details.ct > summary { list-style: none; cursor: pointer; padding: 7px 4px; display: flex; flex-wrap: wrap; align-items: center; gap: 4px 10px; }
+      details.ct > summary > * { min-width: 0; overflow-wrap: anywhere; }
+      details.ct > summary::-webkit-details-marker { display: none; }
+      details.ct > summary::before { content: '▸'; color: var(--text-muted); width: 10px; transition: transform 0.15s; }
+      details.ct[open] > summary::before { transform: rotate(90deg); }
+      details.ct > summary:hover { background: var(--raise); border-radius: 8px; }
+      .k-ic { margin-right: 0; }
+      .ct-f { margin-left: auto; white-space: nowrap; }
+      .ct-body { padding: 4px 10px 14px 24px; }
+      @container (max-width: 480px) {
+        .ct-body { padding: 4px 0 14px 12px; }
+      }
+      .ct-links { margin-top: 10px; font-size: 12px; }
+      .lead { margin: -4px 0 10px; }
+      .one { display: flex; align-items: center; gap: 10px; padding: 7px 4px 7px 24px; border-top: 1px solid var(--line); flex-wrap: wrap; }
+      .why { color: var(--text-2); font-size: 12px; }
+    `,
+  ];
+
+  @property({ attribute: false }) outputs: Outputs | null = null;
+  /** The run, to show paths inside its directory short. */
+  @property() run = '';
+  /** The run's journal: a failed task's card shows why it failed. Optional. */
+  @property({ attribute: false }) journal: JournalRow[] = [];
+  /** The run's plan: with the journal, what happened to the task that writes a missing input. Optional. */
+  @property({ attribute: false }) plan: Plan | null = null;
+  private outcomes: ReadonlyMap<string, TaskOutcome> = new Map();
+
+  /** Which contracts the reader opened, kept across Back and reload. */
+  private readonly open = new RememberedSet('contracts:open', this);
+
+  override render() {
+    const cs = this.outputs?.contracts ?? [];
+    this.outcomes = this.plan ? deriveRun(this.journal, this.plan).outcomes : new Map<string, TaskOutcome>();
+    if (!cs.length) {
+      return html`<div class="blank"><span class="ic" aria-hidden="true">▣</span><b>${msg('No checked files')}</b>
+        <span>${msg('No task declares an OutputContract or an InputContract')}</span></div>`;
+    }
+    const outs = cs
+      .flatMap((c) => (c.outputs ?? []).map((o) => [c, o] as const))
+      .sort(([a, x], [b, y]) => rank(x.status) - rank(y.status) || a.key.localeCompare(b.key));
+    const ins = cs.flatMap((c) => (c.inputs ?? []).map((i) => [c, i] as const));
+    return html`<div class="g12">
+      <section class="panel c12">
+        <h3 title=${msg('OutputContract')}>${msg('Outputs')}
+          <span class="r">${msg('Files each task must write')}</span></h3>
+        <div class="ct-row">${ctChips(this.outputs)}</div>
+        ${repeat(outs, ([c, o]) => `out|${c.key}|${o.path}`, ([c, o]) => this.outRow(c, o))}
+      </section>
+      ${ins.length
+        ? html`<section class="panel c12">
+            <h3 title=${msg('InputContract')}>${msg('Inputs')}
+              <span class="r">${msg('Files each task reads')}</span></h3>
+            ${repeat(ins, ([c, i]) => `in|${c.key}|${i.path}`, ([c, i]) => this.inRow(c, i))}
+          </section>`
+        : nothing}
+    </div>`;
+  }
+
+  private details(id: string, summary: unknown, body: unknown) {
+    return html`<details class="ct" ?open=${this.open.has(id)}
+      @toggle=${(e: Event) => this.open.set(id, (e.target as HTMLDetailsElement).open)}>
+      <summary class="ct-sum">${summary}</summary>
+      <div class="ct-body">${body}</div>
+    </details>`;
+  }
+
+  private link(key: string, view: TaskView, text: string) {
+    return html`<a class="lnk" href="#" @click=${(e: Event) => {
+      e.preventDefault();
+      emit(this, 'ca-open-task', { key, view });
+    }}>${text}</a>`;
+  }
+
+  private who(c: ContractRecord) {
+    const py = isPython(c);
+    const kindName = py ? msg('Python task') : msg('Agent task');
+    return html`${executorIcon(py, kindName)}
+      <b class="jmono" title=${c.key}>${taskName(c)}</b>`;
+  }
+
+  /** Who writes each output file: for naming the task a missing input should have come from. */
+  private producerOf = (path: string): Producer | undefined => {
+    for (const c of this.outputs?.contracts ?? []) {
+      const o = (c.outputs ?? []).find((x) => x.path === path);
+      if (o) return { name: taskName(c), written: !!o.file.exists, outcome: this.outcomes.get(c.key)?.outcome };
+    }
+    return undefined;
+  };
+
+  /** The reason of a task's last journal row (run-relative), when the journal was given. */
+  private reasonOf(key: string): string {
+    for (let i = this.journal.length - 1; i >= 0; i--) {
+      const r = this.journal[i];
+      if (r?.key === key) return runRelative(r.reason, this.run);
+    }
+    return '';
+  }
+
+  private outRow(c: ContractRecord, o: ContractSpec) {
+    // A task that never ran: one line saying why, nothing to open.
+    if (o.status === 'refused') {
+      return html`<div class="one">
+        ${contractChip('refused')}${this.who(c)}
+        <span class="why">${notRunText(o, this.run, this.producerOf)}</span>
+      </div>`;
+    }
+    const f = o.file;
+    const status = o.status;
+    const rounds = o.rounds ?? 0;
+    const errors = o.errors ?? [];
+    const name = taskName(c);
+    // The chip says why there is no file; the size column shows a size only when there is one.
+    return this.details(
+      `out|${c.key}|${o.path}`,
+      html`${contractChip(status)}
+        ${rounds > 1 ? html`<span class="meta" title=${correctionTip()}>${correctionsLabel(rounds, status === 'valid')}</span>` : nothing}
+        ${this.who(c)}
+        <span class="jmono jdim ct-path" title=${o.path}>${shortPath(o.path)}</span>
+        ${status === 'failed' && this.reasonOf(c.key) ? html`<span class="why">${this.reasonOf(c.key)}</span>` : nothing}
+        <span class="meta ct-f">${f.exists ? `${f.size ?? 0} B` : !status ? msg('No file') : nothing}</span>`,
+      html`${fileConditions(o, 'output')}
+        ${fieldCheckTable(o)}
+        ${errors.length ? html`<h4>${msg('Errors')}</h4><pre class="ct-err">${errors.map((e) => runRelative(e, this.run)).join('\n')}</pre>` : nothing}
+        <div class="ct-links">
+          ${this.link(c.key, 'output', msg(str`${name}: input and output`))}
+          ${isPython(c) ? nothing : html`<br />${this.link(c.key, 'transcript', msg(str`${name}: transcript`))}`}
+        </div>`,
+    );
+  }
+
+  private inRow(c: ContractRecord, i: ContractSpec) {
+    const f = i.file;
+    const ok = !!f.exists;
+    return this.details(
+      `in|${c.key}|${i.path}`,
+      html`${inputChip(i)}
+        ${this.who(c)}
+        <span class="jmono jdim ct-path" title=${i.path}>${shortPath(i.path)}</span>
+        <span class="meta ct-f">${ok ? `${f.size ?? 0} B` : msg('No file')}</span>`,
+      html`${fileConditions(i, 'input')}
+        ${fieldCheckTable(i)}
+        <div class="ct-links">${this.link(c.key, 'input', msg(str`${taskName(c)}: input`))}</div>`,
+    );
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ca-contracts': CaContracts;
+  }
+}