Elements of @contraagent/ui

Generated from the custom-elements.json of @contraagent/ui: 27 elements.

• <ca-contracts>
• <ca-definition>
• <ca-definitions>
• <ca-hosts>
• <ca-journal-table>
• <ca-kpis>
• <ca-model-usage>
• <ca-monitor>
• <ca-overview>
• <ca-panel-body>
• <ca-panel-view>
• <ca-pipeline-graph>
• <ca-proc-tree>
• <ca-procs-view>
• <ca-quota>
• <ca-run-driver>
• <ca-run-picker>
• <ca-services>
• <ca-spend-breakdown>
• <ca-task-table>
• <ca-task-view>
• <ca-theme-switch>
• <ca-timeline>
• <ca-toasts>
• <ca-transcript>
• <ca-trends>
• <ca-workers>

<ca-contracts>

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).

CaContracts | src/elements/lists/ca-contracts.ts | Live: @contraagent/ui | Live: Element gallery

Property	Attribute	Type	Description
outputs	none	Outputs | null
run	run	string	The run, to show paths inside its directory short.
journal	none	JournalRow[]	The run's journal: a failed task's card shows why it failed. Optional.
plan	none	Plan | null	The run's plan: with the journal, what happened to the task that writes a missing input. Optional.

Event	Detail and meaning
ca-open-task	{key, view}: a link to the task's input, output or transcript

<ca-definition>

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.

CaDefinition | src/elements/shared/ca-definition.ts

Property	Attribute	Type	Description
definition	none	TaskDefinition | null
memory	memory	string	Remember open files and the rendered/source choice under this id (in the history entry, or the embedded monitor's memory).

<ca-definitions>

What defines each kind of task in a run: a list of kinds, and the selected one's definition. Fetches /definitions itself; while the run is live and a kind has not recorded its definition yet, it asks again. A pick sends ca-navigate {def}.

CaDefinitions | src/elements/lists/ca-definitions.ts | Live: @contraagent/ui | Live: Element gallery

Property	Attribute	Type	Description
client	none	MonitorClient
run	run	string
live	live	boolean	The run is live: definitions may still appear.
journal	none	JournalRow[]	The run's journal and plan: tasks and attempts per kind, and which kinds should have a definition.
plan	none	Plan | null
selected	none	string | null	The selected kind (null: the first with a plugin, else the first).

Event	Detail and meaning
ca-navigate	{def}: another kind was selected

<ca-hosts>

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.

CaHosts | src/elements/shell/ca-hosts.ts

Property	Attribute	Type	Description
hosts	none	Hosts | null	The host list (/api/hosts); null until it arrives.

<ca-journal-table>

The run's history: every finished attempt, newest first (journal.jsonl), with a chip per outcome that filters by it (ca-filter). A row opens the task's detail, with a click or with Enter.

CaJournalTable | src/elements/lists/ca-journal-table.ts | Live: @contraagent/ui | Live: Live data | Live: Element gallery

Property	Attribute	Type	Description
rows	none	JournalRow[]
plan	none	Plan | null	The run's plan: with the rows, why a task did not start, as the tasks list says it. Optional.
fresh	none	ReadonlySet<string>	Rows (by rowId) that just arrived: they flash once.
kind	kind	string
stop	stop	string	A stop; 'bad' (every attempt that did not complete), 'fixup' (output sent back) or 'retried' (tasks retried after a failed try).
q	q	string
run	run	string	The run id: paths inside the run directory are shown relative to it.
extras	none	readonly string[]	The pipeline's own journal columns (RunSummary.row_extras): a column each.
replayMarks	replay-marks	boolean	The run is a replay that also launched (mixedReplay): each attempt played from its recording is marked, and counted in a filter.

Event	Detail and meaning
ca-filter	{stop}: a chip was toggled: a stop value, 'fixup' or 'retried' ('' clears)
ca-open-task	{key}: an attempt's row was opened (its task's key; a Python task with view: 'output')

<ca-kpis>

The run in numbers, as <cae-stat-tiles>: tasks and how they ended (with plan; from the journal alone otherwise), attempts, failed attempts, agent time, retries, corrections and model switches (kpiTiles). The parts of <cae-stat-tiles> are its own: a page styles them as ca-kpis::part(tile).

CaKpis | src/elements/overview/ca-kpis.ts | Live: @contraagent/ui | Live: Theming | Live: Element gallery

Property	Attribute	Type	Description
journal	none	JournalRow[]
plan	none	Plan	The scheduled tasks; without it, tasks are counted from the journal.

Event	Detail and meaning
ca-navigate	{tab: 'journal', stop}: the history filtered to what a tile counts (bad, invalid_input, retried, fixup)
ca-open-task	{key}: the one task a tile counts

Part	Meaning
tiles	the grid of tiles
tile	each tile (data-id is its id, data-tone its tone)
label	a tile's label
value	a tile's value
sub	each line under the value
action	a tile's link

<ca-model-usage>

What each model was used for in a run (Plan.models): the share of each model in the chosen measure (cost, tokens, time or agent sessions) as one bar, and a table of every model with its share and every measure, and its peak context when a session on it reported one. A model keeps its colour, and its place, in the order it was first used, whatever the measure; past six models the later ones share one colour as "Other models".

CaModelUsage | src/elements/overview/ca-model-usage.ts

Property	Attribute	Type	Description
models	none	readonly ModelUsage[]

<ca-monitor>

The whole monitor: header, run switcher, tabs, filters and the views, live. It owns the data (MonitorStore) and the view route (ViewRouter); every view below it only renders what it is given and sends ca-* events back up.

CaMonitor | src/elements/shell/ca-monitor.ts | Live: @contraagent/ui | Live: Embed the monitor | Live: Element gallery

Property	Attribute	Type	Description
baseUrl	base-url	string	Where the monitor's API is served, such as http://127.0.0.1:8787, or a path of this page's origin, such as /monitor (contraagent monitor --base-path writes it into the page it serves); '' is this page's origin. A server on another origin must allow this page's (contraagent monitor --cors-origin). It takes effect whenever it is set, before or after the element connects: a change closes the old server's feeds and opens the run named by run, else the new server's newest run. A request that gets no JSON answer (a network error, a status outside 2xx, or an HTML page from a server without the API) is shown above the view, with its URL and cause, and written to the console.
exportUrl	export	string	An export to read instead of a server (contraagent monitor export): its data/ directory, relative to the page (export="data/") or absolute. The monitor then makes no request to an API and opens no feed: it reads the export's files, which hold no transcripts and no processes. Set, it outranks base-url.
history	history	ViewRouterMode	url: the monitor is the page. The view route lives in the address bar (Back and reload return to it), and the monitor sets the page's title, lang and theme. memory: for a monitor embedded in another page. The view route, the scroll positions and the open sections live in the element, and the page's URL, history, title and <html> attributes stay the host's. A change after connecting takes effect at once: memory keeps the view route shown, url reads the address bar's.
shortcuts	shortcuts	ShortcutScope | ''	Where the single-key shortcuts (1 to 9 for the tabs, r for the runs, / for the filter) work: page, anywhere in the page except in a text field; element, only while the focus is inside the monitor; off, nowhere. Unset: page with history="url", element with history="memory".
run	run	string	The run to open first (in memory mode, or when the URL names none). A change after connecting opens that run.
locale	locale	Locale | ''	The language to show (en, ja). Unset: the reader's earlier choice, else the browser's language. The header's switch changes it and remembers it.
theme	theme	ThemeChoice | ''	The theme: contraagent-dark, contraagent-light, system (one of the two, as the system's colour scheme), github-dark, github-light, one-dark, nord or high-contrast. Unset: the reader's earlier choice, else contraagent-dark. The header's control changes it and remembers it. The theme shown is reflected as data-ca-theme (on <html> too, with history="url").
live	live	boolean	Reflects whether the run is live (the logo moves).
shownTheme	none	ThemeName	The theme shown now.

<ca-overview>

The run on one page, in the order a reader checks it: whether it runs, what runs now, the tasks with a problem (causes first) and the outputs; the pipeline graph (every task, by layer of the flow) and the figures; where the tokens, the cost and the subscription went, the process tree (while running), the resume cursor and the pipeline's own panels; then a timeline. A card takes the width its content needs. Sends ca-open-task and ca-navigate.

CaOverview | src/elements/overview/ca-overview.ts

Property	Attribute	Type	Description
state	none	RunState
summary	none	RunSummary | undefined
host	none	HostSummary | undefined	The run's host (a hub).
info	none	Info
run	run	string
layer	layer	string	The pipeline graph's layer (ViewRoute.layer).
unit	unit	string	The unit highlighted in the pipeline graph (ViewRoute.unit).
sel	sel	string	What is selected in the pipeline graph (ViewRoute.sel).

Event	Detail and meaning
ca-navigate	{tab, stop?}: a link to another tab or a panel; {layer, unit, sel}: a layer of the pipeline graph, or what is selected in it
ca-open-task	{key, view?}: a task with a problem, or the task that started a service, was clicked

<ca-panel-body>

A pipeline's own view drawn from its typed body (PanelBody): tiles, a table, charts, a status grid, notes, code, trees, and blocks of them one under another, each under its title (folded when the body says collapsed). A tree whose nodes hold code shows the selected node's code beside it; a node with a link leads to a body of the panel (its anchor), a run panel's tab or a task. A body of another shape, inside blocks, is shown as a JSON tree.

CaPanelBody | src/elements/lists/ca-panel-body.ts | Live: Element gallery

Property	Attribute	Type	Description
body	none	PanelBody | undefined

Event	Detail and meaning
ca-navigate	a tree node's link to a run panel's tab or a task was chosen

<ca-panel-view>

A view the pipeline added (monitor.Panel), updating live: a typed body as tiles, a table and charts, any other as a JSON tree.

CaPanelView | src/elements/lists/ca-panel-view.ts

Property	Attribute	Type	Description
name	name	string	The panel's registered name.
panel	none	PanelInfo | undefined	Its title, description and icon from /api/info.
data	none	PanelBody | undefined	Its body; undefined until the feed has sent it.

<ca-pipeline-graph>

The run as a graph of its flow, one layer at a time (<cae-layered-graph> draws it). A layer shows the kinds of the tasks its function created (a kind node each, joined to the ones it waits for) and the functions it called (a function node each, holding their tasks); nodes created in one loop are drawn in a loop box, with its last pass ("up to 3 passes") and, when its units ran different numbers of passes, how many ran each ("1 pass: 4 | 2 passes: 1"); a nested loop's box is inside it, and a dotted edge inside each box, from its last layer back to its first, is the return to its next pass. A kind node names who runs its tasks (✦ and an accent: an agent task; ⚙: a Python task); a function node and a loop box carry the mark of an inner view (their layer, their passes). Inside a node, one mark per unit, at the same place in every node, so a unit can be followed across the layer: a task in a kind node, a flow call in a function node; in a loop box, the unit's latest pass, with the number of passes it ran when more than 1. A mark of several tasks shows the most severe state among them (failed, running, not started, waiting, skipped, done); a flow call's mark counts every task of it and of the flow calls it started, and its own error (raised or closed) as failed. A node's count is its tasks done of its tasks, with the others by state, and a function node names its flow calls that stopped with an error. A problem has a square mark (failed: red; not started: hatched), every other state a round one. Above 200 marks, a node shows a bar of its counts and names its failed marks. A solid edge waits for an output; a dashed edge was created after a result; an edge from outside the layer starts at a named stub. A click selects a mark, a node or a loop box (sel); the card beside it shows its facts and links to where it leads: a mark to its task detail, a kind node to its tasks, a function node to its layer, a loop box to its passes. A double click, or Enter, follows the first of them. Hovering or focusing a mark highlights its unit and the tasks joined to it, as the selected mark does. The graph opens on the first layer with more than one node (a static flow's kinds), or on a single function node whose flow call raised; a layer the run does not have opens that one, with a line naming it, and the view route is set right in place (a function named by its qualified name alone opens its layer when the run reaches it by one flow path). A loop's passes are a row per unit and a column per node and pass, a nested loop's passes as a group of columns inside each pass of the outer one, the units sortable by number of passes or by status (<cae-mark-matrix>). The breadcrumb, shown on every layer below the top (a loop named by its file and line), and Escape go back up. On a narrow screen the graph runs top to bottom. "Graph | Table" changes the view; in a loop's passes, "Graph" opens the layer the loop is in, with its box selected. A height set on the element (or given it by a flex or grid container) is the graph's, less the outline's line above it: the drawing fits in it.

CaPipelineGraph | src/elements/overview/ca-pipeline-graph.ts | Live: @contraagent/ui | Live: Events and the view route | Live: Element gallery

Event	Detail and meaning
ca-open-task	{key, view?}: a mark's task detail was opened (a task that did not start opens on its input, a Python task on its output)
ca-navigate	{sel}: a mark, a node, a table row or a loop box was selected, or the selection cleared; {tab: 'tasks', kind}: a kind node's tasks (kind '' for a node of several kinds); {layer, unit?}: a function's layer, a loop's passes, a flow call's function or the breadcrumb, or Escape; {layer, unit, sel}: "Graph" in a loop's passes, its box selected; {layer, unit, sel, replace: true}: the view route's layer set right

<ca-proc-tree>

The run's live process tree (its first root): pid, command, and how long each has run.

CaProcTree | src/elements/lists/ca-proc-tree.ts

Property	Attribute	Type	Description
procs	none	Procs | null

<ca-procs-view>

A live run's processes: each coding-agent launch (opens its transcript with ca-open-task), each Python task, and the process tree.

CaProcsView | src/elements/lists/ca-procs-view.ts

Property	Attribute	Type	Description
procs	none	Procs | null
unresponsive	unresponsive	boolean	The run's host stopped reporting (a hub): whether it runs is not known.
exported	exported	boolean	Read from an export (Info.export): it holds no processes.

Event	Detail and meaning
ca-open-task	{key}: a launch was clicked

<ca-quota>

Subscription usage over the run, per account (credential): for the weekly and the 5-hour window, the account's first reading and its last, and when each window resets. Readings come at session starts and are account-wide. The accounts are the run's (journal), or given (accounts: a hub's, over every run of every host, Hosts.quota). With the run's quota caps and rests (caps, rests, rule: Plan.quota_caps, .rests, .quota_rule), each window shows its cap, and each account whether it is paused and its rests.

CaQuota | src/elements/overview/ca-quota.ts

Property	Attribute	Type	Description
journal	none	JournalRow[]
accounts	none	readonly AccountUsage[] | null	Each account's first and last reading, highest weekly use first; null: from journal.
caps	none	readonly QuotaCap[]	The run's quota caps, by credential (Plan.quota_caps).
rests	none	readonly CredentialRest[]	Each rest of a credential in the run, in start order (Plan.rests).
rule	rule	string	The run's quota rule, module.qualname (Plan.quota_rule); '' for none.
live	live	boolean	The run is live: a rest with no reset time (a rule's) stands only while it is.

<ca-run-driver>

The run's own process: running (pid, run group, how many tasks at once, command line), or not running, and then how it finished: with errors, or with tasks not done (from plan). On a hub, a run whose host stopped reporting (summary.unresponsive) is neither: no report from its host, since host.last_seen. Under it, the models the run's preflight found available, replaced or not available (plan.preflight); a run its preflight ended names the kinds that did it.

CaRunDriver | src/elements/overview/ca-run-driver.ts

Property	Attribute	Type	Description
procs	none	Procs | null
summary	none	RunSummary | undefined
plan	none	Plan
host	none	HostSummary | undefined	The run's host (a hub): when it last reported.

<ca-run-picker>

The run switcher: runs grouped by recency, searchable, keyboard driven. A dialog: its search field (a combobox) holds the focus while it is open (Tab stays in it), and the arrow keys move through the list (aria-activedescendant). Sends ca-select-run for a pick and ca-close when it should be closed (Escape, or a pick); the host returns the focus. While nothing is searched, the first options are the pages of no run: the trends, and on a hub the hosts. On a hub (hub), the runs are grouped by host, each group headed by its host's state; a host filter (a select, the dialog's second Tab stop) shows one host's runs.

CaRunPicker | src/elements/shell/ca-run-picker.ts

Property	Attribute	Type	Description
runs	none	RunSummary[]
current	current	string	The run shown now.
open	open	boolean
hub	hub	boolean	The runs come from many hosts (Info.hosts): group them by host, with a host filter and the hosts page.
hosts	none	HostSummary[]	The host list (a hub).
page	page	Page	The page of no run shown now (trends, hosts; it is the current option); '' while a run is shown.

Event	Detail and meaning
ca-select-run	{run}: a run was picked
ca-navigate	{page, run: ''}: a page of no run was picked (trends, or on a hub hosts)
ca-close	the picker should close

<ca-services>

The run's services (Plan.services): each start of the long-lived helper a claim name stands for, one per row, with its state, its claim name, its address, when it started and stopped and why, and the task whose claim started it.

CaServices | src/elements/overview/ca-services.ts

Property	Attribute	Type	Description
services	none	readonly ServiceSpan[]	Each start of a service, in start order (Plan.services).
nodes	none	readonly PlanNode[]	The run's tasks (Plan.nodes): the task that started a service is named by its kind and unit.
live	live	boolean	Whether the run still runs: a service with no stop recorded is running only then.

Event	Detail and meaning
ca-open-task	the task chip of the task that started a service was clicked

<ca-spend-breakdown>

Where a run's tokens and cost went: per kind, a bar of its tokens (input, cache read, cache write, output) with its cost and share of the run's cost, most expensive first; then the most expensive tasks.

CaSpendBreakdown | src/elements/overview/ca-spend-breakdown.ts

Property	Attribute	Type	Description
journal	none	JournalRow[]
top	top	number	How many of the most expensive tasks to list.

Event	Detail and meaning
ca-open-task	{key}: one of the most expensive tasks was clicked

<ca-task-table>

Every task of the run, one row each (deriveRun(...).rows: the plan joined with the journal, so a task that never ran is a row too): what happened to it, its attempts, time, tokens and cost. A row opens the task's detail (ca-open-task), with a click or with Enter.

CaTaskTable | src/elements/lists/ca-task-table.ts | Live: @contraagent/ui | Live: Element gallery

Property	Attribute	Type	Description
journal	none	JournalRow[]	The run's journal and plan: the tasks are the plan's, what happened to them the journal's.
plan	none	Plan | null
kind	kind	string	Only this kind ('' for all).
q	q	string	A text filter over the kind, unit, key and last stop.
live	live	boolean	The run is running: a task that has not started is waiting; in a run that is over, it did not run.
run	run	string	The run id: paths in a cause are shown relative to it.

Event	Detail and meaning
ca-open-task	{key}: a task's row was opened (its key; a Python task with view: 'output')

<ca-task-view>

One task: who ran it, every finished attempt, and four views of it: the transcript (live), its input (params, upstream outputs, declared inputs, the prompt), its output (files against their contracts, the result, who uses it) and its definition. Sends ca-navigate with view or round, and ca-open-task for a linked task.

CaTaskView | src/elements/task/ca-task-view.ts | Live: @contraagent/ui | Live: Element gallery

Property	Attribute	Type	Description
client	none	MonitorClient
baseUrl	base-url	string
run	run	string
taskKey	none	string | null	A task key; null when there is no task to show.
view	view	TaskView
round	none	number | null	The round shown, 1-based; null follows the latest.
live	live	boolean	The run is live.
journal	none	JournalRow[]	The whole run's journal: the subscription readings other tasks took after this one, and what happened to the tasks it reads from. Optional.
plan	none	Plan | null	The run's plan: whether a task with no attempt is waiting or not started, and which earlier task stopped it. Optional.
exported	exported	boolean	Read from an export (Info.export): it holds no transcript.
replayMarks	replay-marks	boolean	The run is a replay that also launched (mixedReplay): each attempt played from its recording is marked.

Event	Detail and meaning
ca-navigate	{view} or {round}: another view or round of this task
ca-open-task	{key}: an upstream or downstream task was clicked

<ca-theme-switch>

The theme control in the monitor's header: a button that opens a menu of the themes. Arrow keys, Home and End move in the menu; Enter or Space chooses; Escape closes it.

CaThemeSwitch | src/elements/shell/ca-theme-switch.ts

Property	Attribute	Type	Description
value	value	ThemeChoice	The current choice.
system	system	ThemeName	The theme system shows now, by the system's colour scheme.

Event	Detail and meaning
ca-choose-theme	{theme}: a theme (or system) was chosen

<ca-timeline>

Every finished attempt as a bar as long as it took, on its kind's lane, the running ones growing until now (the last six hours of the run), as <cae-lanes> (lanesFromJournal).

CaTimeline | src/elements/overview/ca-timeline.ts | Live: @contraagent/ui | Live: Element gallery

Property	Attribute	Type	Description
journal	none	JournalRow[]
plan	none	Plan | null	The run's plan: with the journal, why a task did not start, as the tasks list says it. Optional.
procs	none	Procs | null
live	live	boolean	The run is live: its running tasks are drawn, growing every second.
run	run	string	The run drawn; the bars grow in when a run is first drawn, not on every update.

<ca-toasts>

Short notices in a corner; each leaves on its own after a few seconds. A screen reader hears each one: a failure at once, the others when it is idle.

CaToasts | src/elements/shell/ca-toasts.ts

<ca-transcript>

The transcript of one task: every round (one session of the coding agent, with its command line and prompt), chat bubbles, collapsible tool cards (a web search shows its query and the pages it returned as links, a web page read its URL as a link), tailed live. A round is a try (a new session) or a fix-up (the same session, sent back because its output failed its checks); give it the task's journal rows (.rows) and each round says how it ended. It draws them with <cae-transcript>. Give it .events to show a saved transcript, or run + stream (and base-url) to tail one from the monitor. A new .events that starts with the same event objects as the last one is that transcript grown: its new events are added below and what is drawn stays. Sends ca-navigate with round when the reader picks a round, and a non-bubbling ca-rounds (RoundsChangedDetail) whenever its rounds or the shown round change.

CaTranscript | src/elements/task/ca-transcript.ts | Live: Element gallery

Property	Attribute	Type	Description
events	none	TranscriptEvent[] | null	A saved transcript to show as is (no feed).
run	run	string
stream	none	string | null	The transcript's task key (TaskDetail.stream).
baseUrl	base-url	string
client	none	MonitorClient | null	For "load earlier"; one is made from base-url when absent.
live	live	boolean	The task is running: show it working; when not, a call still marked running was interrupted.
round	none	number | null	The round to show, 1-based; null follows the latest.
rows	none	JournalRow[]	The task's journal rows (finished tries): each round then says how it ended.
mode	mode	'full' | 'tabs' | 'none'	full; tabs: only the round picker (another view of the task is shown); none: hidden.

Event	Detail and meaning
ca-navigate	{round}: the reader picked a round (null for the latest)
ca-rounds	{launches, shown, rounds}, not bubbling: the rounds' launch events and what each was, for a host that shows a round's prompt

<ca-trends>

The trends: what the runs of a period add up to (/api/trends), section by section: the totals, the cost of each day, each kind and each model, the subscription usage, the attempts not done, the tool calls denied, the tasks not run, when runs start, and the runs; then the pipeline's own trend panels. Above them, the period (the last 7, 14 or 30 days, or two dates), its time zone and a run group; an export's period is fixed and named instead. When a trend panel names a tab, the page has tabs: the first holds the trends and the trend panels of no tab, each other one the panels of its tab.

CaTrends | src/elements/trends/ca-trends.ts

Property	Attribute	Type	Description
view	none	TrendsView | null
days	days	number	The period: the last days days (0: from to to).
from	from	string
to	to	string
tz	tz	string	The time zone the days are counted in.
group	group	string	Only the runs of this run group ('': every run).
groups	none	readonly string[]	The run groups there are to choose from.
panels	none	readonly PanelInfo[]	The pipeline's trend panels (Panel(scope="trends")).
exported	exported	boolean	An export: its period is the one it holds.
tab	tab	string	The open tab: a trend panel's tab ('': the first, the trends).

Event	Detail and meaning
ca-navigate	{days, from, to, tz, group}: another period, time zone or run group; {trendsTab}: another tab

<ca-workers>

What runs now: one card per running task (an agent session opens its transcript), the rest idle, up to the number of tasks the run runs at once (max_concurrent). Sends ca-open-task.

CaWorkers | src/elements/overview/ca-workers.ts

Property	Attribute	Type	Description
procs	none	Procs | null
live	live	boolean	The run is live; when not, every slot is idle.

Event	Detail and meaning
ca-open-task	{key}: a running agent launch was clicked