@contraagent/ui 0.0.0-stage → 0.1.0

package/src/elements/shared/ca-definition.ts

@@ -0,0 +1,206 @@
+import type { DefinitionFile, TaskDefinition } from '@contraagent/api';
+import { localized, msg, str } from '@lit/localize';
+import { LitElement, css, html, nothing, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { highlight, mdFile } from '@contraagent/elements/markdown';
+import { instructionsHtml, markInstructions } from '../../words/prompt.js';
+import { facts as row } from '../../words/format.js';
+import { retryTip } from '../../words/attempts.js';
+import { implementationOfLabel, implementationOfTip, outputOfText, outputOfTip, preserveLabel, preserveTip, retriedExceptionsLabel, retriedExceptionsTip, retriesLabel, retriesText } from '../../words/task-definition.js';
+import { RememberedSet } from '../../core/memory.js';
+import { base, factStyles, prose } from '@contraagent/elements/styles';
+import { contractChipStyles } from './contract-parts.js';
+
+const OPEN_FIRST = new Set(['instructions', 'schema', 'agent']);
+
+/** A long path cut from the left to its last two parts (`…/plugins/docs`); the full path goes in a tooltip. */
+const tail = (p: string): string => {
+  const parts = p.split('/').filter(Boolean);
+  return parts.length > 2 ? `…/${parts.slice(-2).join('/')}` : p;
+};
+
+interface DeclaredContract {
+  io: string;
+  path: string;
+  schema: string;
+}
+
+/**
+ * What defines one kind of task: its role, plugin, params and output, the
+ * contracts it declares, and every file (instructions, the role's agent file,
+ * skills, the schema), markdown rendered with a switch to the source.
+ */
+@customElement('ca-definition')
+@localized()
+export class CaDefinition extends LitElement {
+  static override styles = [
+    base,
+    prose,
+    factStyles,
+    contractChipStyles,
+    css`
+      :host { display: block; }
+      .ct-in { display: flex; align-items: center; gap: 10px; padding: 5px 4px; border-top: 1px solid var(--line); }
+      .df { border-top: 1px solid var(--line); }
+      /* A file: its name opens and closes it (a disclosure button), and a Markdown file has its own toggle beside it. */
+      /* Too narrow for the name and the toggle on one line: the toggle goes under the name. */
+      .df-hd { padding: 6px 2px; display: flex; flex-wrap: wrap; gap: 4px 10px; align-items: center; }
+      .df-sum { flex: 1 1 16em; min-width: 0; display: flex; flex-wrap: wrap; gap: 4px 10px; align-items: center; padding: 0; background: none; border: 0;
+        color: inherit; text-align: start; cursor: pointer; }
+      .df-sum .jmono { min-width: 0; overflow-wrap: anywhere; }
+      .df-tog { flex: none; margin-inline-start: auto; }
+      .df-sum::before { content: '▸'; color: var(--text-muted); width: 10px; flex: none; transition: transform 0.15s; }
+      .df-sum[aria-expanded='true']::before { transform: rotate(90deg); }
+      .py-sig { font-family: var(--mono); font-size: 14px; padding: 10px 14px; background: var(--well); border: 1px solid var(--line);
+        border-radius: 8px; overflow-x: auto; white-space: pre; }
+      .py-where { margin: 6px 2px 12px; font-family: var(--mono); font-size: 11.5px; color: var(--text-muted); overflow-wrap: anywhere; }
+      .py-doc { margin: 0 0 12px; padding: 8px 12px; border-left: 3px solid var(--line2); color: var(--text-2); white-space: pre-wrap; line-height: 1.6; }
+      .src { display: grid; grid-template-columns: auto minmax(0, 1fr); background: var(--well); border: 1px solid var(--line);
+        border-radius: 8px; font-family: var(--mono); font-size: 12px; line-height: 1.55; max-height: 520px; overflow: auto; }
+      .src pre { margin: 0; padding: 10px 12px; white-space: pre; }
+      .src .ln { color: var(--text-muted); text-align: right; user-select: none; border-right: 1px solid var(--line); opacity: 0.7; }
+    `,
+  ];
+
+  @property({ attribute: false }) definition: TaskDefinition | null = null;
+  /** Remember open files and the rendered/source choice under this id (in the history entry, or the embedded monitor's memory). */
+  @property() memory = 'definition';
+
+  private open = new RememberedSet('definition:open', this);
+  private source = new RememberedSet('definition:source', this);
+
+  override willUpdate(changed: Map<string, unknown>): void {
+    if (changed.has('memory')) {
+      this.open = new RememberedSet(`${this.memory}:open`, this);
+      this.source = new RememberedSet(`${this.memory}:source`, this);
+    }
+  }
+
+  override render() {
+    const def = this.definition;
+    if (!def) {
+      return html`<div class="blank"><span class="ic" aria-hidden="true">⌘</span><b>${msg('No definition')}</b></div>`;
+    }
+    if (def.executor === 'python') return this.python(def);
+    const dirs = def.plugin_dirs || [];
+    const output = def.output_from === 'message'
+      ? row(def.output || '', msg('from the final message', { desc: "The task's output is the agent's last message of a session" }))
+      : def.output || '';
+    const preserve = def.preserve ?? [];
+    const facts: [string, string | TemplateResult][] = [
+      ...(def.base_kind ? [[implementationOfLabel(), html`<span class="jmono" title=${implementationOfTip()}>${def.base_kind}</span>`] as [string, TemplateResult]] : []),
+      [msg('Role'), def.role || msg('none', { id: 'none', desc: 'An empty value' })],
+      [
+        dirs.length > 1 ? msg('Plugin directories') : msg('Plugin directory'),
+        dirs.length ? html`${dirs.map((d, i) => html`${i ? ', ' : ''}<span class="jmono" title=${d}>${tail(d)}</span>`)}` : msg('none', { id: 'none', desc: 'An empty value' }),
+      ],
+      [msg('Parameters'), def.params || msg('none', { id: 'none', desc: 'An empty value' })],
+      [
+        msg('Output', { id: 'definition-output', desc: 'The output file of a task definition' }),
+        def.output_of
+          ? html`<span title=${outputOfTip()}>${row(output, outputOfText(def.output_of))}</span>`
+          : output || msg('none', { id: 'none', desc: 'An empty value' }),
+      ],
+      ...(preserve.length
+        ? [[preserveLabel(), html`<span class="jmono" title=${preserveTip()}>${preserve.join(', ')}</span>`] as [string, TemplateResult]]
+        : []),
+      ...((def.validators || []).length ? [[msg('Other checks'), (def.validators || []).join(', ')] as [string, string]] : []),
+      ...(Array.isArray(def.tools) && def.tools.length === 0
+        ? [[msg('Tools', { desc: "The coding agent's tools in a task definition" }), msg('none', { id: 'none', desc: 'An empty value' })] as [string, string]]
+        : []),
+    ];
+    const declared = Array.isArray(def['declared']) ? (def['declared'] as DeclaredContract[]) : [];
+    // The role file this kind runs as goes first, open; other roles' files are folded.
+    const isRole = (f: DefinitionFile) => f.part === 'agent' && !!def.role && f.path.replace(/^.*\//, '') === `${def.role}.md`;
+    const files = [...(def.files || [])].sort((a, b) => Number(isRole(b)) - Number(isRole(a)));
+    return html`<div class="drv-facts" style="margin-bottom:10px">${facts.map(([k, v]) => html`<span><i>${k}</i>${v}</span>`)}</div>
+      ${declared.length
+        ? html`<h4 class="sect-h">${msg('Checked files')}</h4>
+            ${declared.map(
+              (x) => html`<div class="ct-in">
+                <span class="ct-chip">${x.io}</span><span class="jmono">${x.path}</span>
+                <span class="meta" title=${msg('The schema the file is checked against')}>${msg(str`Schema ${x.schema}`)}</span>
+              </div>`,
+            )}`
+        : nothing}
+      ${files.length
+        ? html`<h4 class="sect-h">${msg('Files')}</h4>${files.map((f) => this.file(f, isRole(f), !!def.role))}`
+        : html`<div class="meta">${msg(html`No files | defined in Python code (<code>TaskAdapter</code>)`)}</div>`}`;
+  }
+
+  /** A Python task's kind, shown as its function: signature, where it is, docstring, facts, source. */
+  private python(def: TaskDefinition) {
+    const src = (def.files || []).find((f) => f.part === 'source');
+    const first = def.line ?? 1;
+    const lines = src ? src.text.replace(/\n$/, '').split('\n').length : 0;
+    const retryOn = def.retry_on ?? [];
+    const facts: [string, string | TemplateResult][] = [
+      [msg('Parameters'), def.params && def.params !== 'none' ? def.params : msg('none', { id: 'none', desc: 'An empty value' })],
+      [msg('Output', { id: 'definition-output', desc: 'The output file of a task definition' }), def.output && def.output !== 'none' ? def.output : msg('none', { id: 'none', desc: 'An empty value' })],
+      ...((def.validators || []).length ? [[msg('Other checks'), (def.validators || []).join(', ')] as [string, string]] : []),
+      ...(def.retries ? [[retriesLabel(), html`<span title=${retryTip()}>${retriesText(def.retries)}</span>`] as [string, TemplateResult]] : []),
+      ...(def.retries && retryOn.length
+        ? [[retriedExceptionsLabel(), html`<span class="jmono" title=${retriedExceptionsTip()}>${retryOn.join(', ')}</span>`] as [string, TemplateResult]]
+        : []),
+    ];
+    return html`${def.signature
+        ? html`<div class="py-sig hl">${unsafeHTML(highlight(`def ${def.signature}`, 'python'))}</div>`
+        : nothing}
+      <div class="py-where">
+        ${def.function ?? def.kind}${def.file
+          ? html` | <span title=${def.file}>${def.file.replace(/^.*\//, '')}${def.line ? `:${def.line}` : ''}</span>`
+          : nothing}
+      </div>
+      ${def.doc ? html`<div class="py-doc">${def.doc}</div>` : nothing}
+      <div class="drv-facts" style="margin-bottom:12px">${facts.map(([k, v]) => html`<span><i>${k}</i>${v}</span>`)}</div>
+      ${src
+        ? html`<h4 class="sect-h">${msg('Source')}</h4>
+            <div class="src">
+              <pre class="ln">${Array.from({ length: lines }, (_, i) => first + i).join('\n')}</pre>
+              <pre class="hl">${unsafeHTML(highlight(src.text.replace(/\n$/, ''), 'python'))}</pre>
+            </div>`
+        : nothing}`;
+  }
+
+  private file(f: DefinitionFile, isRole = false, hasRole = false) {
+    const id = `${f.part}|${f.path}`;
+    const isMd = /\.md$/i.test(f.path);
+    const instructions = f.part === 'instructions';
+    const showSource = !isMd || this.source.has(id);
+    // Of the role files, only the one this kind uses opens by default.
+    const openFirst = f.part === 'agent' && hasRole ? isRole : OPEN_FIRST.has(f.part);
+    const isOpen = this.open.has(id) || (openFirst && !this.open.has(`closed:${id}`));
+    const toggle = () => {
+      this.open.set(id, !isOpen);
+      this.open.set(`closed:${id}`, isOpen);
+      this.requestUpdate();
+    };
+    const flip = () => {
+      this.source.set(id, !this.source.has(id));
+      this.requestUpdate();
+    };
+    return html`<div class="df">
+      <div class="df-hd">
+        <button type="button" class="df-sum" aria-expanded=${isOpen ? 'true' : 'false'} @click=${toggle}>
+          <span class="tag">${f.part}</span><span class="jmono">${f.path}</span>
+          ${isRole ? html`<span class="ct-chip">${msg('Role of this kind')}</span>` : nothing}
+        </button>
+        ${isMd
+          ? html`<button type="button" class="df-tog" @click=${flip}>${showSource ? msg('Show rendered') : msg('Show source')}</button>`
+          : nothing}
+      </div>
+      ${!isOpen
+        ? nothing
+        : showSource
+          ? html`<pre class="df-text"><code class="hl">${unsafeHTML(instructions ? instructionsHtml(f.text) : highlight(f.text, f.path))}</code></pre>`
+          : unsafeHTML(mdFile(f.text, instructions ? markInstructions : undefined))}
+    </div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ca-definition': CaDefinition;
+  }
+}

package/src/elements/shared/contract-parts.ts

@@ -0,0 +1,158 @@
+// A contract file read the way a person checks it: each field of its schema
+// against what the file holds. Templates shared by the outputs view and a task's
+// input/output view (`file-card.ts`); their classes are in `contractStyles`.
+import { type ContractSpec, type ContractStatus, type FileView } from '@contraagent/api';
+import { msg, str } from '@lit/localize';
+import { css, html, nothing, type TemplateResult } from 'lit';
+import { facts, localTime } from '../../words/format.js';
+import { contractStatusLabel, contractStatusWhy } from '../../words/contract.js';
+import { preserveLabel, preserveTip } from '../../words/task-definition.js';
+import { statusChip } from '@contraagent/elements/primitives';
+import { verdict, verdictStyles } from '@contraagent/elements/check-table';
+import '@contraagent/elements/check-table/define';
+import { checkRowsFromContract, checkTableStrings, contentObject, rootOf } from '../../adapters/check-rows.js';
+import { contractTone } from '../../lib/tone.js';
+import '@contraagent/elements/json-tree/define';
+
+/** An input file's state: found, or missing (and whether the task needed it). */
+export function inputChip(o: ContractSpec): TemplateResult {
+  const ok = !!o.file.exists;
+  const text = ok ? msg('found') : o.required ? msg('missing (required)') : msg('missing (optional)');
+  return statusChip('ct-chip', { text, tone: ok ? 'done' : o.required ? 'failed' : 'muted' });
+}
+
+/** A checked file's status as a chip, with its cause as the tooltip, and a count after the word when given; '—' without one. */
+export function contractChip(s: ContractStatus | null | undefined, count?: number): TemplateResult {
+  if (!s) return statusChip('ct-chip', { text: '—' });
+  return statusChip('ct-chip', {
+    text: count === undefined ? contractStatusLabel(s) : html`${contractStatusLabel(s)} <b>${count}</b>`,
+    tone: contractTone(s),
+    title: contractStatusWhy(s),
+  });
+}
+
+
+/** The file's content as a tree, or as text when it is not JSON. */
+export function fileContent(f: FileView): TemplateResult {
+  const c = f.content;
+  return c !== null && typeof c === 'object'
+    ? html`<cae-json-tree .value=${c}></cae-json-tree>`
+    : html`<pre class="jtree">${typeof c === 'string' ? c : msg('Not JSON')}</pre>`;
+}
+
+/**
+ * The contract on the left of each row, the file's value on the right, a
+ * verdict per field (`<cae-check-table>`); a text result shows the file itself.
+ */
+export function fieldCheckTable(o: ContractSpec): TemplateResult {
+  const f = o.file;
+  const rows = checkRowsFromContract(o);
+  const whole = html`<details class="ct-raw">
+    <summary>${wholeFile(f)}</summary>
+    ${fileContent(f)}
+  </details>`;
+  // A text result (a text file, or one JSON value) has no fields to check: show the file itself.
+  if (!rows) return f.exists ? whole : html``;
+  // No file: the fields it must have, and nothing to check them against; its status chip says it is not there.
+  if (!f.exists) return rows.length ? html`<cae-check-table .rows=${rows} .showValues=${false} .strings=${checkTableStrings()}></cae-check-table>` : html``;
+  return html`<cae-check-table .rows=${rows} .strings=${checkTableStrings()}></cae-check-table>
+    ${!contentObject(o) ? html`<div class="meta note">${msg('Not a JSON object')}</div>` : nothing}
+    ${whole}`;
+}
+
+/** The fold over a file's content: `Whole file | 1204 B | written Oct 12, 10:38:40`. */
+const wholeFile = (f: FileView): string =>
+  facts(msg('Whole file'), `${f.size ?? 0} B`, f.mtime ? msg(str`written ${localTime(f.mtime, true)}`) : '', f.truncated ? msg('truncated') : '');
+
+/**
+ * The schema as the reader names it: the class name for a model, "text" for a
+ * text result. The class name stays in the tooltip.
+ */
+export function schemaName(o: ContractSpec): TemplateResult {
+  const root = rootOf(o.schema_name);
+  const shown = o.schema_name === 'text' || root === 'str' ? msg('text') : root ?? o.schema_name;
+  return html`<b class="jmono" title=${o.schema_ref || o.schema_name}>${shown}</b>`;
+}
+
+/** What kind of file it must be, in words. */
+export function formatOf(o: ContractSpec): unknown {
+  const tip = o.schema_ref || o.schema_name;
+  if (o.schema_name === 'text') return msg('text file');
+  const root = rootOf(o.schema_name);
+  if (root === 'str') return html`<span title=${tip}>${msg('text (JSON string)')}</span>`;
+  if (root) return html`<span title=${tip}>${msg(str`JSON value of type ${root}`)}</span>`;
+  return msg(html`JSON object, schema ${schemaName(o)}`);
+}
+
+/** The checks beyond the schema (validators), each with its result when the status tells it; null when there are none. */
+export function otherChecks(o: ContractSpec): TemplateResult | null {
+  const names = o.validators ?? [];
+  if (!names.length) return null;
+  const errors = (o.errors ?? []).join('\n');
+  const mark = (n: string) =>
+    o.status === 'valid' ? verdict('pass', msg('passed')) : errors.includes(n) ? verdict('fail', msg('failed checks')) : nothing;
+  return html`${names.map((n, i) => html`${i ? ', ' : ''}<span class="jmono">${n}</span> ${mark(n)}`)}`;
+}
+
+/**
+ * What a contract file must be, as labelled lines a reader can follow without
+ * knowing the contract machinery: its format, and (for an output) whether a file
+ * from before the task counts, or (for an input) when it is checked and whether
+ * the task can start without it.
+ */
+export function fileConditions(o: ContractSpec, role: 'input' | 'output'): TemplateResult {
+  const format = formatOf(o);
+  const checks = otherChecks(o);
+  const rows: [string, unknown, string?][] =
+    role === 'output'
+      ? [
+          [msg('Format'), format],
+          ...(checks ? [[msg('Other checks'), checks, msg('Checks beyond the schema (validators)')] as [string, unknown, string]] : []),
+          [msg('Must be written during the task'), o.fresh ? msg('yes') : msg('no'), o.fresh ? msg('A file from before the task does not count') : msg('A file from before the task counts')],
+          ...(o.preserve?.length
+            ? [[preserveLabel(), html`<span class="jmono">${o.preserve.join(', ')}</span>`, preserveTip()] as [string, unknown, string]]
+            : []),
+        ]
+      : [
+          [msg('Format'), format],
+          ...(checks ? [[msg('Other checks'), checks, msg('Checks beyond the schema (validators)')] as [string, unknown, string]] : []),
+          [msg('Check time'), msg('when the task starts')],
+          [msg('Required'), o.required ? msg('yes') : msg('no')],
+        ];
+  return html`<dl class="conds">
+    ${rows.map(([k, v, tip]) => html`<dt>${k}</dt><dd title=${tip ?? ''}>${v}</dd>`)}
+  </dl>`;
+}
+
+/** A chip that names a checked file's status (`statusChip`), or a neutral label in its shape. */
+export const contractChipStyles = css`
+  .ct-chip { display: inline-block; padding: 1px 10px; border-radius: var(--radius-pill); font-size: 11.5px; background: var(--raise); color: var(--text-2); white-space: nowrap; }
+  .ct-chip b { margin-left: 4px; }
+  /* a checked file's status: tinted by its tone, passed quiet with its ✓ in an outline */
+  .ct-chip[data-tone] { background: var(--tone-bg); color: var(--tone); }
+  .ct-chip[data-tone='done'] { background: none; box-shadow: inset 0 0 0 1px var(--line2); color: var(--text-2); }
+`;
+
+export const contractStyles = css`
+  ${contractChipStyles}
+  ${verdictStyles}
+  .ct-path { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .ct-lead { margin: 2px 0 8px; display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 6px; }
+  /* a name's column as wide as its longest name, up to half the width; a long name or value wraps */
+  .conds { display: grid; grid-template-columns: fit-content(50%) minmax(0, 1fr); gap: 2px 14px; margin: 2px 0 10px; font-size: 12px; }
+  .conds dt { color: var(--text-muted); overflow-wrap: anywhere; }
+  .conds dd { margin: 0; color: var(--text-2); min-width: 0; overflow-wrap: anywhere; }
+  .note { margin-top: 6px; }
+  .ct-raw { margin-top: 8px; }
+  .ct-raw > summary { cursor: pointer; color: var(--text-muted); font-size: 12px; }
+  .ct-err { color: var(--status-failed); white-space: pre-wrap; }
+  .ct-fields { border-collapse: collapse; width: 100%; }
+  .ct-fields td { padding: 2px 10px 2px 0; border: 0; font-size: 12px; }
+  .ct-in { display: flex; align-items: center; gap: 10px; padding: 5px 4px; border-top: 1px solid var(--line); }
+  h4 { margin: 8px 0 6px; font-size: 12px; color: var(--text-2); font-weight: 600; }
+  .io-card { border: 1px solid var(--line); border-radius: 10px; padding: 10px 14px; margin-bottom: 10px; background: var(--raise); }
+  .io-hd { display: flex; align-items: center; gap: 10px; margin-bottom: 6px; }
+  .io-from { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 8px; margin: -2px 0 8px; }
+  .io-hd .ct-path { flex: 1; }
+  .io-card.one .io-hd { margin-bottom: 2px; }
+`;

package/src/elements/shared/file-card.ts

@@ -0,0 +1,49 @@
+// A task's contract file as a card, for a task's input and output panes. Its
+// classes are in `contractStyles`.
+import { runRelative, type ContractSpec } from '@contraagent/api';
+import { msg } from '@lit/localize';
+import { html, nothing, type TemplateResult } from 'lit';
+import { correctionTip, correctionsLabel, notRunText, type Producer } from '../../words/contract.js';
+import { contractChip, fieldCheckTable, fileConditions, inputChip } from './contract-parts.js';
+
+/**
+ * One contract file of a task, as a card: status, path, what it must be, the
+ * field check, the check errors. A task that never ran gets one line saying
+ * why; a task that failed without writing the file gets its status and path
+ * only (the status names the cause).
+ */
+export function ioFileCard(
+  o: ContractSpec,
+  role: 'input' | 'output',
+  run = '',
+  opts: {
+    producerOf?: (path: string) => Producer | undefined;
+    /** Where the file comes from, as a line under its path ("Output of prepare · zeta"). */
+    origin?: unknown;
+    /** In place of the status chip: an input written by an earlier task shows that task's check of it. */
+    chip?: TemplateResult;
+  } = {},
+): TemplateResult {
+  const stat =
+    role === 'output'
+      ? html`${contractChip(o.status)}${(o.rounds ?? 0) > 1
+            ? html` <span class="meta" title=${correctionTip()}>${correctionsLabel(o.rounds, o.status === 'valid')}</span>`
+            : nothing}`
+      : inputChip(o);
+  const head = html`<div class="io-hd">${opts.chip ?? stat}<span class="jmono ct-path" title=${o.path}>${runRelative(o.path, run)}</span></div>${opts.origin
+    ? html`<div class="meta io-from">${opts.origin}</div>`
+    : nothing}`;
+  if (role === 'output' && o.status === 'refused') {
+    return html`<div class="io-card one">${head}<div class="meta">${notRunText(o, run, opts.producerOf)}</div></div>`;
+  }
+  if (role === 'output' && o.status === 'failed' && !o.file.exists) {
+    return html`<div class="io-card one">${head}</div>`;
+  }
+  const errors = o.errors ?? [];
+  return html`<div class="io-card">
+    ${head}
+    ${fileConditions(o, role)}
+    ${fieldCheckTable(o)}
+    ${errors.length ? html`<h4>${msg('Errors')}</h4><pre class="ct-err">${errors.map((e) => runRelative(e, run)).join('\n')}</pre>` : nothing}
+  </div>`;
+}

package/src/elements/shared/prompt-text.ts

@@ -0,0 +1,13 @@
+// A prompt as a reader reads it: markdown with a rendered/source switch, and its
+// leading TELEMETRY line (which run and task it belongs to) apart, so the prose
+// reads as prose.
+import { msg } from '@lit/localize';
+import { html, type TemplateResult } from 'lit';
+import '@contraagent/elements/markdown/define';
+import { splitTelemetry } from '../../words/prompt.js';
+
+/** `text` in a `<cae-markdown>`, in the reader's language. Call it from a `@localized()` element's render. */
+export function promptText(text: string): TemplateResult {
+  const strings = { showRendered: msg('Show rendered'), showSource: msg('Show source') };
+  return html`<cae-markdown .text=${text} .split=${splitTelemetry} .strings=${strings}></cae-markdown>`;
+}

package/src/elements/shared/task-chip.ts

@@ -0,0 +1,18 @@
+// A task named in a list, as a chip of its own: the name keeps its `kind · unit`
+// form without a separator between names, and a click opens the task.
+import { isPython } from '@contraagent/api';
+import { html, type TemplateResult } from 'lit';
+import { emit } from '../../core/events.js';
+
+/**
+ * `name` as a chip that sends `ca-open-task` for `task` (a Python task opens on its
+ * output). A task with no key (a running Python task) is a chip that opens nothing.
+ */
+export function taskChip(from: EventTarget, name: string, task: { key: string; executor?: string }): TemplateResult {
+  if (!task.key) return html`<span class="taskchip">${name}</span>`;
+  const open = (e: Event): void => {
+    e.stopPropagation(); // the row it sits in may open another task
+    emit(from, 'ca-open-task', { key: task.key, ...(isPython(task) ? { view: 'output' as const } : {}) });
+  };
+  return html`<button type="button" class="taskchip" title=${task.key} @click=${open}>${name}</button>`;
+}

package/src/elements/shell/ca-clock.ts

@@ -0,0 +1,27 @@
+import { localized } from '@lit/localize';
+import { LitElement } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { ClockController } from '@contraagent/elements';
+import { getLocale } from '../../core/i18n.js';
+
+/** The wall clock in the header: its own element, so the second tick repaints nothing else. */
+@customElement('ca-clock')
+@localized()
+export class CaClock extends LitElement {
+  constructor() {
+    super();
+    new ClockController(this);
+  }
+  protected override createRenderRoot() {
+    return this;
+  }
+  override render() {
+    return new Date().toLocaleTimeString(getLocale(), { hour12: false });
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ca-clock': CaClock;
+  }
+}

package/src/elements/shell/ca-hosts.ts

@@ -0,0 +1,93 @@
+import type { Hosts, HostSummary } 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 { statusWord } from '@contraagent/elements/primitives';
+import { base } from '@contraagent/elements/styles';
+import { fmtDur, localTime } from '../../words/format.js';
+import { hostStateLabel, hostsLine, noReportCount, runCount } from '../../words/hosts.js';
+import '../overview/ca-quota.js';
+
+/** The column of a host's runs, counted. */
+const runsLabel = () => msg('Runs', { id: 'col-runs', desc: "A column: a host's runs, counted" });
+
+/**
+ * The hosts behind a hub's runs (`/api/hosts`): each host's state, its last
+ * report, the seconds between its reports and its runs; then each account's
+ * utilization over every run of every host, as the overview shows a run's.
+ */
+@customElement('ca-hosts')
+@localized()
+export class CaHosts extends LitElement {
+  static override styles = [
+    base,
+    css`
+      :host { display: block; container-type: inline-size; }
+      .g12 { align-content: start; }
+      table { width: 100%; border-collapse: collapse; font-size: 12.5px; }
+      th, td { text-align: start; padding: 8px 10px; border-top: 1px solid var(--line); vertical-align: baseline; }
+      thead th { border-top: 0; font-size: 11.5px; font-weight: 600; color: var(--text-muted); white-space: nowrap; }
+      tbody th { font-family: var(--mono); font-weight: 600; color: var(--text); overflow-wrap: anywhere; }
+      .num { font-family: var(--mono); font-variant-numeric: tabular-nums; white-space: nowrap; }
+      td.runs { color: var(--text-2); }
+      /* Narrow: one block per host, each value under its column's name. */
+      @container (max-width: 640px) {
+        thead { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
+        tr { display: block; padding: 8px 0; border-top: 1px solid var(--line); }
+        tbody tr:first-child { border-top: 0; }
+        th, td { display: flex; gap: 12px; padding: 2px 0; border: 0; white-space: normal; }
+        td::before { content: attr(data-label); flex: 0 0 9em; color: var(--text-muted); font-family: var(--sans); font-size: 11.5px; }
+      }
+    `,
+  ];
+
+  /** The host list (`/api/hosts`); null until it arrives. */
+  @property({ attribute: false }) hosts: Hosts | null = null;
+
+  private row(h: HostSummary) {
+    const quiet = !h.up;
+    return html`<tr>
+      <th scope="row">${h.host_id}</th>
+      <td data-label=${msg('Status')}>${statusWord({ text: hostStateLabel(h), tone: quiet ? 'attention' : 'done' })}</td>
+      <td data-label=${msg('Last report')} class="num" title=${h.last_seen}>${localTime(h.last_seen, true) || '—'}</td>
+      <td data-label=${msg('Report interval')} class="num">${h.interval_s == null ? '—' : fmtDur(h.interval_s)}</td>
+      <td data-label=${runsLabel()} class="runs"
+        ><span>${runCount(h.runs)}${h.running ? html` | ${msg(str`${h.running} running`)}` : nothing}${h.unresponsive
+          ? html` | <span class="tone-text" data-tone="attention">${noReportCount(h.unresponsive)}</span>`
+          : nothing}</span></td
+      >
+    </tr>`;
+  }
+
+  override render() {
+    const hosts = this.hosts?.hosts ?? [];
+    const quota = this.hosts?.quota ?? [];
+    return html`<div class="g12">
+      <section class="panel c12 enter">
+        <h3>${msg('Hosts')}<span class="r">${hostsLine(hosts)}</span></h3>
+        ${hosts.length
+          ? html`<table>
+              <thead><tr>
+                <th scope="col">${msg('Host')}</th><th scope="col">${msg('Status')}</th><th scope="col">${msg('Last report')}</th>
+                <th scope="col">${msg('Report interval')}</th><th scope="col">${runsLabel()}</th>
+              </tr></thead>
+              <tbody>${hosts.map((h) => this.row(h))}</tbody>
+            </table>`
+          : html`<div class="meta">${msg('No hosts')}</div>`}
+      </section>
+      ${quota.length
+        ? html`<section class="panel c12 enter">
+            <h3 title=${msg('Account-wide | read at each agent session start')}>
+              ${msg('Subscription usage')}<span class="r">${msg('Per account, first → last reading')}</span></h3>
+            <ca-quota .accounts=${quota} .rests=${quota.flatMap((a) => a.rests ?? [])} live></ca-quota>
+          </section>`
+        : nothing}
+    </div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ca-hosts': CaHosts;
+  }
+}