Building panels

Code, UI text and commit messages are English. A further plugin root (src/plugins_<name>/) may keep its panels in another language (<html lang>).

This skill is the craft. /ui/kit shows the components themselves — each in every state, rendered from the same files a panel loads. Look there instead of copying markup from old panels.

What a panel is

An HTML page the shell shows in an iframe: docked as a tab next to the chat or detached as a floating window. Each panel is open once; opening it again brings it to the front. It is opened through the catalog (GET /api/ui/catalog): the panel launcher, the command palette and the entry points in the chat all read the same list. Opened directly in a browser tab the same page works too — it then shows dialogs and toasts itself. The button "Open in a new browser tab" on the tab and the window bar takes it there. A tab of its own has no chat to follow: a panel with a session context gets the chat's session pinned as ?session_id= and so shows the same as in the frame. If <pk-session all> is set to "all sessions", the tab starts there (?session_scope=all) and stays pinned all the same: the choice "this session" then names one. The way back: in its own tab the kit puts "Open in ScarabHive" into the head — the shell opens with this panel on this page (/?panel=<path of the page>; docked, or where it is already open), on "all sessions" if it is set there. A pinned session opens in the chat as well; the pin stays, because a panel can hang more on it than the session it follows (message_debugger filters by it).

The iframe is a boundary for style, crashes and life cycle, not a security boundary: panels run with allow-same-origin and the shell's cookie. Do not embed foreign code as a panel.

1. The catalog entry (schema.yaml)

web_ui:
  panel:
    endpoint: "/plugins/{{ name }}/"
    title: "Message Debugger"
    description: "Captured message turns and raw API requests and responses"
    icon: bug
    category: debug
    keywords: [requests, responses, llm]
    window: {width: 1000, height: 700}
    contexts:
      request: "/plugins/{{ name }}/?request_id={request_id}"
  endpoints:
    - path: "/"
      method: "GET"
      handler: "render_panel"
      response_type: "html"

Who sees the panel is not in the block: the catalog shows it to the roles that both layers of the route security in config/security.yaml let open the endpoint: auth.endpoint_security (app-wide) and auth.plugin_security. If a panel is for admins only, a rule for its routes belongs in the configuration — then visibility and access match automatically.

web_ui knows exactly these two keys: panel and endpoints. Other keys (button, menu, requires_auth, roles, …) are an error. src/agent_system/ui/catalog.py (plugin_panel) is the parser — the validator uses the same one; at run time a broken entry drops out of the catalog with an error log.

The plugin has to be registered as a web plugin and hand out its schema: it provides get_web_router() and get_schema_data() — the registry reads web_ui from get_schema_data(); without the method the panel is missing without a message. Schema-based plugins inherit both from SchemaBasedPluginWebInterface and build the router with SchemaRouterGenerator from web_ui.endpoints. The endpoint lives under /plugins/<instance>/ — the schema router serves it there, and only there may the shell frame it.

2. The page

Route: render the template through ui_templates() — it finds the plugin's templates first and the kit's after them:

from agent_system.ui.resources import ui_templates

templates = ui_templates(Path(__file__).parent / "templates")

async def render_panel(self, request: Request):
    return templates.TemplateResponse(request, "panel.html", {"plugin": self.name})

Template:

{% extends "kit/panel_base.html" %}
{% from "kit/macros.html" import icon %}
{% block title %}Message Debugger{% endblock %}
{% block toolbar %}<pk-refresh interval="5"></pk-refresh>{% endblock %}
{% block content %}
<div class="pk-tabs" role="tablist" data-pk-tabs>
  <button class="pk-tab" role="tab" aria-selected="true" aria-controls="tab-turns" data-tab="turns">Turns</button>
  <button class="pk-tab" role="tab" aria-selected="false" aria-controls="tab-raw" data-tab="raw">Raw requests</button>
</div>
<section id="tab-turns" role="tabpanel"><div id="turns"></div></section>
<section id="tab-raw" role="tabpanel" hidden></section>
{% endblock %}
{% block scripts %}<script type="module" src="/plugins/{{ plugin }}/static/panel.js"></script>{% endblock %}

Script and own CSS live in the plugin's static/ folder; if the plugin serves it through get_static_assets(), it is reachable under /plugins/<name>/static/.

panel_base.html sets the theme from the cookie (no flash), loads kit.css and panel-kit.js, and in the frame hides its own title — the tab or the window bar carries it there; the toolbar stays. Further blocks: head, lang (de for a German panel).

Icons in the template: {{ icon('refresh-cw') }}, {{ icon('bug', size='sm', label='Bug') }}. A figure: {{ stat('Open', 12, key='open', sub='3 new', pressed=false) }}; a process's steps: {{ steps([{'label': 'Plan', 'state': 'done'}, {'label': 'Build', 'sub': '2 open', 'state': 'current'}], label='Phases') }} (dots=true for dots only; lang = the page's language, for the hidden words a screen reader hears for done, warn and ahead) — the twins of stat() and .pk-steps. A run's or job's status: {{ status('running', label=true, pill=true, lang='de') }} (from "kit/macros.html" import status; lang as the page's <html lang>, so it reads like the script's status()).

3. panel-kit.js

import { api, html, render, icon, session } from '/static/kit/panel-kit.js';

The pattern of a loader — the newest answer wins, what did not change stays, an error keeps what is shown and says so:

async function load() {
  try {
    const data = await api(`${base}/jobs?${formQuery(filters)}`, { latest: 'jobs', quiet: true });
    notice(stale, '');
    update(list, data.jobs.length ? rows(data.jobs) : emptyState('list-todo', 'No jobs'));
  } catch (error) {
    if (isAborted(error)) return;
    notice(stale, `Not refreshed (${errorText(error)}) — shown is the last state.`);
  }
}

Language: the kit speaks the language of <html lang> (de for a German panel) — dialog buttons, refresh menu, pager, copy toast.

Example:

async function load() {
  const turns = await api(`/plugins/message_debugger/turns?session_id=${encodeURIComponent(session.id)}`);
  render(document.getElementById('turns'), turns.length
    ? html`<table class="pk-table">${turns.map((t) => html`<tr><td>${t.agent}</td><td class="pk-num">${t.tokens}</td></tr>`)}</table>`
    : html`<div class="pk-empty">${icon('history')}<div class="pk-empty-title">Nothing captured yet</div></div>`);
}
document.addEventListener('refresh', load);
session.onChange(load);
load();

Sortable tables need no script of their own: after render() the kit sorts every <table class="pk-table" data-pk-sort="<name>"> with a <thead> that it rendered (the enclosing one too, when only the tbody is new).

• A click anywhere in the header cell sorts, a .pk-num column largest first, any other A–Z; the second click reverses. On the column the table is sorted by right now (also through aria-sort in the markup), the first click already reverses. The kit puts the header content into a <button class="pk-sort" data-key="sort:<name>:<header text>"> (keyboard); through the data-key it gets the focus back after a redraw — a selector of your own on [data-key] therefore hits it as well. Headers without text, with a control of their own (link, button, input, select, label, summary, anything with tabindex) or with data-pk-nosort stay silent; data-pk-nosort also where the values have no order (a row of badges).
• The choice holds across every redraw (auto-refresh) and is tied to the header text, not the column number; a column that is only sometimes there does not shift it. The name separates the tables of a page. It also survives a reload: the kit remembers it per panel path in localStorage under pk.sort:<pathname> (table name → header text and direction), like the refresh tick. Only a plain name is remembered ([\w.:-], at most 40 characters) and only the last twelve per panel — a name a panel builds from an input (the SQL panel names its table after the query) stays in the page and does not go to disk. A broken entry counts as none.
• Sorting goes by data-sort-value, else by the text. If all values of a column are numbers, as numbers; all ISO timestamps, as points in time (without a zone as UTC, as our databases write them); otherwise the whole column naturally as text ("B9" before "B10"). Empty or a single dash always comes last. Every cell whose text is not its value (toLocaleString() with a thousands separator, "1.2 s", "0.300¢", a badge, a shortened text) gets data-sort-value="${raw ?? ''}".
• aria-sort="descending" in the markup is the order until the user chooses. If the panel sorts its rows by a column today, that mark belongs on the header and the JS sorting goes.
• Do not make sortable: key-value tables, tables with pairs of rows (a detail row under each entry) and lists loaded page by page on the server — the server sorts those. A list "the newest N" is sorted by the kit within those N.
• One header row, one <tbody> (only the first is sorted), no colspan. Rows keep their attributes when re-sorted; handlers through data-id/data-index keep working, code that reads the order in the DOM does not.

Resizable columns come with every .pk-table that has a one-row <thead> and two columns or more — sortable or not, no markup of your own. Dragging a head's right edge sets that column's width, a double click on the edge fits it to its widest cell (a row whose cells are not one per column, a detail row with colspan, does not count). Once one is set the table lays out fixed: a set column keeps its width, the last column (no grip) and any not set share the rest. A cell of text that does not fit ends in "…" and shows the whole text on hover (a title of the page's own stays); a cell holding blocks (div, p, pre, lists, details, a form) wraps instead. The widths follow the header text (two heads with the same text count apart) and hold through every render(); a table named by data-pk-cols (or its data-pk-sort) keeps them per panel path across reloads, in localStorage under pk.cols:<pathname> (same plain-name rule as sorting). Text you want to wrap goes into a block (<div>), not straight into the <td>. Opt out with data-pk-noresize.

Phone and tablet come with the same tables, no markup of your own:

• 640 px and narrower (a phone, and a panel docked narrow beside the chat): a .pk-table with a one-row <thead> of two columns or more lays out as cards, one per row, each value beside its column's name. The kit copies the head's text into each cell's data-pk-label on every render() and marks the table pk-table--cards; a head without text (a checkbox, the actions) labels nothing, a row that is not one cell per column (a detail row with colspan) spans its card. The head stays above the cards as a row that wraps, so sorting and a select-all box keep working; column widths wait for a wider frame. A value the panel keeps on one line wraps there anyway, and an empty cell to edit (data-edit) stays in its card. A column the panel hides on narrow screens with a class of its own needs .pk-table--cards td.<class> { display: none; } too. data-pk-nocards keeps a table a table (a grid of numbers that only reads across).
• A touch screen wider than that (pointer: coarse): the table box scrolls sideways itself, so the head, filters and tabs stay in view. With a mouse the panel body scrolls, as above — a box's scrollbar would sit at the table's end, out of reach.
• Checked at 390 and 820 px: no page may scroll sideways as a whole. A .pk-search keeps a floor width even with pk-grow, so a row of searches wraps instead of shrinking them to their icons; the page head puts its toolbar on a line of its own on a phone.

AI tasks and agent runs — a panel whose work an agent may take on: initAiTasks(base, host, {onChange}) from /static/kit/ai-tasks.js puts the "AI" button in the toolbar and the "Agent runs" sheet on the page; the plugin's web class inherits AiTaskRoutes (agent_system/plugins/agent_tasks.py, its routes named in schema.yaml). What a run does live comes from /static/kit/run-events.js (followRuns: one stream per tab, shared with the shell); the events and states are in docs/run_events.md.

4. Look

• Components instead of your own: pk-btn (--primary, --danger, --ghost, --icon, --sm), pk-input/pk-select/pk-textarea/pk-check/pk-switch in pk-field and pk-form, pk-tabs, pk-dialog (--wide; --resizable with a pk-field--grow that takes the room, size kept per panel), pk-drop (--over) for a file drop target, pk-menu, pk-table in pk-table-wrap, pk-card, pk-stats/pk-stat (a <button class="pk-stat"> when a click leads to what it counts), pk-badge (--ok/--warn/--danger/--info carry their tone's mark by themselves -- status is never colour alone; --danger --strong filled for the gravest), pk-dot, pk-empty, pk-skeleton, pk-spinner, pk-progress (--ok/--warn/--danger), pk-code, pk-kv, pk-json, pk-callout (--danger/--warn/--info/--ok), pk-details (on a <details>), pk-prose (reading text; pk-prose--breaks keeps stored line breaks), pk-text--ok/--warn/--danger/--info (a value in a tone colour), pk-code--full (code without a height cap), pk-menu-item[aria-selected] (the chosen suggestion), a disabled pk-menu-item (looks it), pk-btn[aria-pressed="true"] and the current item of a list as pk-btn[aria-current="true"] (marked, also under the pointer — no CSS of your own for it), pk-tab-count in a pk-tab (keeps its room as the count comes and goes); layout with pk-stack, pk-row, pk-grow, pk-toolbar, pk-filters (filter row above a list; a bare pk-select in it is as wide as its choices), pk-split (list on the left, detail on the right, the detail stays put; 2:3, --list-wide 3:2, --even 1:1; a pk-table-wrap in it scrolls sideways in its column — no overflow-x of your own), pk-section-title (the small uppercase heading over a group), pk-form--cols (two columns, one when narrow; pk-field--wide spans both), pk-steps/pk-step (an <ol>; data-state="done|current|warn|danger|ahead", aria-current="step" on the current; pk-step-label, pk-step-sub; pk-steps--dots for an onboarding; the steps() macro), pk-list-item (a two-line entry to choose, on a button or pk-btn: pk-list-item-name, pk-list-item-sub, aria-current="true"), pk-legend with pk-swatch[data-tone="ok|warn|danger|info|accent|muted"], pk-code--lines (a .pk-code-line per line, number from data-line or counted; --hit/--add/--del/--hunk), pk-tree (nested <ul> of <details>/<summary>), pk-segmented (a radiogroup of <label>s with radios), pk-choice (an option card: a <label> around its radio or checkbox), pk-sidebar-layout with pk-sidebar (sidebar next to the main area: width draggable at the corner, the kit remembers the width per panel, stacked when narrow — every sidebar takes this one, none of your own), a panel's pages as <nav class="pk-tabs"> with <a class="pk-tab" aria-current="page">; for runs and pipelines pk-status (through status()), pk-pipeline (stages as columns with lines between, role="group" with its aria-label) with pk-pipeline-stage/pk-pipeline-jobs, pk-job (a pill; a button when it opens something, pk-job-count for a group), pk-pipeline--mini (the stage row in a list), pk-timeline (who did what when, an optional body), pk-detail-layout (one thing's page: header, main column, a sidebar of facts on the right that goes below when narrow).
• Colours, spacing, radii, type only through tokens: --surface-0…3, --text-primary/secondary/muted, --border-subtle/default/strong, --accent*, --ok/--warn/--danger/--info (+ -subtle), --space-1…8, --radius-sm/md/lg, --text-xs…xl, --font-ui, --font-mono. Every value holds in light and dark. A hex value in a panel is an error — if a token is missing, it belongs in the kit.
• Own CSS only for what is really the panel's own (a canvas, a diagram the kit has no part for), in a file next to the script, built from tokens.
• hidden hides reliably, whatever display a class sets.

5. Prohibitions

• No alert/confirm/prompt — the kit replaces them; the native call fails loudly (console + toast). Test: tests/ui/test_kit.py.
• No innerHTML with data except through html`…` /render. Server data neither: agent names, tool arguments, titles come from models.
• No window.parent, no window.top — the shell speaks only through the protocol. Session, theme and dialogs come through the kit.
• No raw fetch in panel code.
• No buttons, tabs, modals, toasts, refresh buttons of your own, no emoji as icons.
• No CDN — libraries go to static/vendor/.

6. The protocol (for the curious and the shell)

Every message carries type. The kit speaks it; a panel only calls the functions above.

What a panel says before pk:init (title, path) the kit holds back and sends after the handshake. Without a shell (a browser tab of its own, a foreign frame) no pk:init comes, and the kit shows dialogs and toasts itself.

7. Checking

1. python src/scripts/validate_plugin.py src/plugins/<name> — the web_ui block goes through the catalog parser.
2. pytest tests/ui -q — among other things every icon named in the code exists, no kit user calls native dialogs (covered are templates on panel_base.html and scripts that import panel-kit.js), catalog rules, the shell in a real browser.
3. Visual check in both themes: open the panel in the shell, docked and detached, switch the theme with the button in the head. Open it directly under its URL in a browser tab — it has to work there too.
4. Panel logic with branches gets a browser test after the pattern of tests/ui/test_shell_browser.py (run_app_test_page with a stub app) or tests/ui/test_kit_js.py — and a mutation probe: change the served file in memory, the test has to go red.

8. Migrating an existing panel

One plugin at a time.

1. Inventory: which endpoints, which states (empty, error, loading), which actions (delete → confirm with danger), which parameters does it read (session_id, request_id)? Only what it really reads becomes contexts. If it reads session_id, <pk-session> belongs in the toolbar and session.shown in place of pinned || session.id.
2. Route on ui_templates(), template on kit/panel_base.html.
3. Delete the embedded <style>; move what remains onto tokens. Own .btn, .modal, .tab, .toast, .badge → kit classes.
4. Inline script into a module next to the template (static/panel.js), fetch → api, string HTML → html`…` , delete the escapeHtml copy, toggleAutoRefresh → <pk-refresh>, guessing the session through window.parent → session.
5. Emoji → icon(). Not in the sprite? Add it to static/kit/icons.svg from Lucide (same stroke width), do not leave it as an emoji.
6. Remove dead parts of the old panel (branches never reached, duplicate handlers, unused endpoints) instead of carrying them along.
7. Check as in § 7, then the visual check — the old and the new panel side by side once: if a function is missing, the migration is not done.