pi-chassis 0.0.0-stage → 0.7.1

package/dist/chassis/api.js

@@ -0,0 +1,676 @@
+/**
+ * Widget registry: the one place info and status widgets are declared.
+ *
+ * A widget is a small object with an id and a render function. The TUI decides where it shows up
+ * (sidebar section, footer segment, or both) from its `slots`, orders it by `order`, and refreshes
+ * it on `refreshMs` or when the widget calls `handle.refresh()`.
+ *
+ *     import { registerWidget } from "../chassis/api.ts";
+ *
+ *     registerWidget(pi, {
+ *       id: "deploy",
+ *       title: "Deploy",
+ *       slots: ["footer", "sidebar"],
+ *       order: 10,
+ *       refreshMs: 30_000,
+ *       render: () => ({ icon: "\uF0E7", text: "staging·v42", color: "brand" }),
+ *       detail: () => ["Last deploy 12m ago"],
+ *     });
+ *
+ * The registry lives on globalThis because pi loads every extension file in its own module scope
+ * (jiti, moduleCache off), so a plain module-level Map would give each extension its own copy.
+ * Widgets registered before chassis loads are kept and shown once it starts.
+ *
+ * Plain `ctx.ui.setStatus()` from other extensions still works: the TUI shows those statuses as
+ * footer segments too, unless a registered widget claims the same key (`statusKey`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getCapabilities, hyperlink } from "@earendil-works/pi-tui";
+import { safeLinkUrl, scrubText } from "./sanitize.js";
+/** A render or detail call slower than this counts as a strike against the widget. */
+export const SLOW_RENDER_MS = 50;
+/** This many slow calls in a row suspend the widget until `/widgets enable ID`. */
+export const SLOW_RENDER_STRIKES = 3;
+/** An `update` that has not settled after this long is abandoned and reported as an error. */
+export const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
+/** Bumped on a breaking change to the registry or WidgetSpec; client.ts checks it. */
+export const API_VERSION = 1;
+/** Version of the tool row API (`registerToolRows`). Bumped on a breaking change to it or to ToolRowSpec. */
+export const TOOL_ROWS_VERSION = 1;
+const PENDING = Symbol.for("pi-chassis/pending");
+const PENDING_TOOL_ROWS = Symbol.for("pi-chassis/pendingToolRows");
+function pendingList() {
+    const g = globalThis;
+    g[PENDING] ??= [];
+    return g[PENDING];
+}
+function pendingToolRowsList() {
+    const g = globalThis;
+    g[PENDING_TOOL_ROWS] ??= [];
+    return g[PENDING_TOOL_ROWS];
+}
+/** Register everything that client.ts queued before the host loaded. */
+export function drainPending() {
+    const list = pendingList().splice(0);
+    for (const item of list) {
+        try {
+            item.attach(registerWidget(item.pi, item.spec));
+        }
+        catch {
+            // one bad registration must not stop the others
+        }
+    }
+    for (const item of pendingToolRowsList().splice(0)) {
+        try {
+            item.attach(registerToolRows(item.specs, { id: item.id }));
+        }
+        catch {
+            // one bad registration must not stop the others
+        }
+    }
+}
+/**
+ * Called once by chassis when it loads: announces the host (so client.ts registers straight into
+ * the registry) and takes over widgets that were queued before it loaded.
+ */
+export function installHost() {
+    const reg = getRegistry();
+    reg.apiVersion = API_VERSION;
+    reg.register = registerWidget;
+    reg.toolRowsVersion = TOOL_ROWS_VERSION;
+    reg.registerToolRows = registerToolRows;
+    drainPending();
+}
+/** Where the settings file is stored. PI_CHASSIS_STATE overrides it (used by tests). */
+export function statePath() {
+    const override = process.env.PI_CHASSIS_STATE;
+    if (override)
+        return override;
+    const dir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+    return join(dir, "chassis.json");
+}
+function loadDisabled() {
+    try {
+        const data = JSON.parse(readFileSync(statePath(), "utf8"));
+        return new Set(Array.isArray(data?.disabledWidgets) ? data.disabledWidgets.filter((x) => typeof x === "string") : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function saveDisabled(ids) {
+    try {
+        const path = statePath();
+        let data = {};
+        if (existsSync(path)) {
+            try {
+                data = JSON.parse(readFileSync(path, "utf8")) ?? {};
+            }
+            catch {
+                data = {};
+            }
+        }
+        data.disabledWidgets = [...ids].sort();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
+    }
+    catch {
+        // Persistence is best effort; the in-memory list still applies for this run.
+    }
+}
+const KEY = Symbol.for("pi-chassis/registry");
+export function getRegistry() {
+    const g = globalThis;
+    g[KEY] ??= {
+        widgets: new Map(),
+        ctx: undefined,
+        requestRender: () => { },
+        listeners: new Set(),
+        version: 0,
+        disabled: loadDisabled(),
+    };
+    // A registry created by an older chassis in the same process lacks newer fields.
+    g[KEY].disabled ??= loadDisabled();
+    return g[KEY];
+}
+/** The registered tool row groups, oldest first (created on first use, so an older registry works). */
+export function toolRowGroups() {
+    const reg = getRegistry();
+    return (reg.toolRows ??= []);
+}
+/** A spec that failed this many finished calls is no longer used until it is registered again. */
+export const TOOL_ROW_FAILURE_LIMIT = 3;
+const toolRowFailures = new WeakMap();
+/** Count a failure of `spec` on a finished call (not while arguments or output were still arriving). */
+export function noteToolRowFailure(spec) {
+    toolRowFailures.set(spec, (toolRowFailures.get(spec) ?? 0) + 1);
+}
+/** Whether `spec` failed too many finished calls to be used for new ones. */
+export function toolRowBroken(spec) {
+    return (toolRowFailures.get(spec) ?? 0) >= TOOL_ROW_FAILURE_LIMIT;
+}
+/** Whether `spec` has the shape chassis needs: a string title, functions to describe and summarize, and `expand` a function if given. */
+function isToolRowSpec(spec) {
+    const s = spec;
+    return !!s && typeof s === "object" && typeof s.title === "string" && typeof s.describe === "function" && typeof s.summarize === "function" && (s.expand === undefined || typeof s.expand === "function");
+}
+/**
+ * Register chassis-styled rows for tools that belong to another extension, by tool name. Returns a
+ * function that removes them (calling it twice is harmless).
+ *
+ * The rows are looked up when a call is drawn, so it does not matter whether the extension that
+ * owns the tool, the one registering the rows or chassis loads first. A call already on screen keeps
+ * the renderer it was created with.
+ *
+ * chassis's own rows for pi's built-in tools (read, write, edit, bash, grep, find, ls) always win: a
+ * spec registered under one of those names is never used. For any other name the most recently
+ * registered spec wins, and removing it brings back the one before it. An entry is used only if
+ * it has a string `title`, function `describe` and `summarize`, and `expand` is a function when
+ * given; any other entry is skipped.
+ *
+ * Pass `{ id }` when the registrant can run more than once in a process (an extension that
+ * registers on every `session_start`, or is loaded again by /reload): registering again with the
+ * same id replaces its earlier group instead of adding another. Without an id, call the returned
+ * remover (for example on `session_shutdown`) before registering again.
+ */
+export function registerToolRows(specs, options) {
+    const groups = toolRowGroups();
+    const id = typeof options?.id === "string" && options.id ? options.id : undefined;
+    const group = { id, specs: new Map() };
+    for (const [name, spec] of Object.entries(specs ?? {})) {
+        if (!name || !isToolRowSpec(spec))
+            continue;
+        toolRowFailures.delete(spec); // registering again gives a spec a fresh start
+        group.specs.set(name, spec);
+    }
+    if (id !== undefined) {
+        for (let i = groups.length - 1; i >= 0; i--)
+            if (groups[i].id === id)
+                groups.splice(i, 1);
+    }
+    groups.push(group);
+    getRegistry().requestRender();
+    return () => {
+        const live = toolRowGroups();
+        const i = live.indexOf(group);
+        if (i < 0)
+            return;
+        live.splice(i, 1);
+        getRegistry().requestRender();
+    };
+}
+/** The registered row spec for a tool, newest registration first, or undefined. */
+export function toolRowFor(toolName) {
+    const groups = toolRowGroups();
+    for (let i = groups.length - 1; i >= 0; i--) {
+        const spec = groups[i].specs.get(toolName);
+        if (spec)
+            return spec;
+    }
+    return undefined;
+}
+/** Make every widget render again (an icon set change, say), dropping cached output. */
+export function invalidateWidgets() {
+    changed(getRegistry());
+}
+function changed(reg) {
+    reg.version++;
+    for (const l of reg.listeners)
+        l();
+    reg.requestRender();
+}
+const messageOf = (e) => (e instanceof Error ? e.message : String(e)).split("\n")[0].slice(0, 200) || "unknown error";
+function runUpdate(reg, entry) {
+    const { spec } = entry;
+    const ctx = reg.ctx;
+    if (reg.disabled.has(spec.id))
+        return;
+    if (!spec.update || !ctx) {
+        changed(reg);
+        return;
+    }
+    // One update at a time: a slow source must not pile up overlapping runs.
+    if (entry.inflight)
+        return;
+    entry.inflight = true;
+    const started = Date.now();
+    const timeoutMs = spec.updateTimeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS;
+    let settled = false;
+    const finish = (err) => {
+        if (settled)
+            return; // a late result after the timeout is ignored
+        settled = true;
+        clearTimeout(timer);
+        entry.inflight = false;
+        entry.lastDurationMs = Date.now() - started;
+        entry.lastUpdateAt = Date.now();
+        if (err !== undefined)
+            entry.error = { phase: "update", message: messageOf(err), at: Date.now() };
+        else if (entry.error?.phase === "update")
+            entry.error = undefined;
+        changed(reg);
+    };
+    const timer = setTimeout(() => finish(new Error(`update timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref?.();
+    try {
+        const r = spec.update(ctx);
+        if (r && typeof r.then === "function") {
+            r.then(() => finish(), (e) => finish(e ?? new Error("update rejected")));
+        }
+        else {
+            finish();
+        }
+    }
+    catch (e) {
+        finish(e ?? new Error("update threw"));
+    }
+}
+function startTimer(reg, entry) {
+    if (entry.timer || !entry.spec.refreshMs || !reg.ctx || reg.disabled.has(entry.spec.id))
+        return;
+    entry.timer = setInterval(() => runUpdate(reg, entry), entry.spec.refreshMs);
+    entry.timer.unref?.();
+}
+/** Remove the pi.on handlers a widget added, so re-registering or disposing doesn't leak them. */
+function unlisten(entry) {
+    for (const off of entry.offs.splice(0)) {
+        try {
+            off();
+        }
+        catch {
+            // the pi instance may already be gone
+        }
+    }
+}
+function stopTimer(entry) {
+    if (entry.timer)
+        clearInterval(entry.timer);
+    entry.timer = undefined;
+}
+/**
+ * Register (or replace) a widget. Returns a handle for on-demand refresh and removal.
+ *
+ * Pass `pi` so the widget's timers follow the session lifecycle: they start on session_start and
+ * stop on session_shutdown. The widget itself stays registered across /reload of chassis.
+ *
+ * Registering from inside a `session_start` handler (as a package that does not import chassis does)
+ * misses that session's own `session_start` event for the widget, so pass the handler's `ctx`.
+ */
+export function registerWidget(pi, spec, ctx) {
+    const reg = getRegistry();
+    if (ctx)
+        reg.ctx ??= ctx;
+    const old = reg.widgets.get(spec.id);
+    if (old) {
+        stopTimer(old);
+        unlisten(old);
+    }
+    const entry = { spec, strikes: 0, offs: [] };
+    reg.widgets.set(spec.id, entry);
+    const listen = (off) => {
+        if (typeof off === "function")
+            entry.offs.push(off);
+    };
+    listen(pi.on("session_start", async (_e, ctx) => {
+        if (reg.widgets.get(spec.id) !== entry)
+            return;
+        // chassis may not have set reg.ctx yet (load order), so use this ctx for the first update.
+        reg.ctx ??= ctx;
+        startTimer(reg, entry);
+        runUpdate(reg, entry);
+    }));
+    listen(pi.on("session_shutdown", async () => {
+        stopTimer(entry);
+    }));
+    if (reg.ctx) {
+        startTimer(reg, entry);
+        runUpdate(reg, entry);
+    }
+    else {
+        changed(reg);
+    }
+    return {
+        refresh: () => {
+            if (reg.widgets.get(spec.id) === entry)
+                runUpdate(reg, entry);
+        },
+        dispose: () => {
+            stopTimer(entry);
+            unlisten(entry);
+            if (reg.widgets.get(spec.id) === entry)
+                reg.widgets.delete(spec.id);
+            changed(reg);
+        },
+    };
+}
+/** Widgets for a slot, sorted by order then id. */
+export function widgetsFor(slot) {
+    return [...getRegistry().widgets.values()]
+        .map((e) => e.spec)
+        .filter((s) => !getRegistry().disabled.has(s.id))
+        .filter((s) => (s.slots ?? ["footer", "sidebar"]).includes(slot))
+        .sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.id.localeCompare(b.id));
+}
+/** setStatus() keys claimed by registered widgets. */
+export function claimedStatusKeys() {
+    const keys = new Set();
+    for (const { spec } of getRegistry().widgets.values()) {
+        keys.add(spec.statusKey ?? spec.id);
+        for (const k of spec.statusKeys ?? [])
+            keys.add(k);
+    }
+    return keys;
+}
+function record(id, phase, err) {
+    const entry = getRegistry().widgets.get(id);
+    if (entry)
+        entry.error = { phase, message: messageOf(err), at: Date.now() };
+}
+const nowMs = () => performance.now();
+/** The cache slot for this call, or undefined when the widget doesn't cache or something changed. */
+function cacheFor(entry, rc) {
+    if (!entry.spec.cacheKey)
+        return undefined;
+    let key;
+    try {
+        key = entry.spec.cacheKey(rc);
+    }
+    catch {
+        return undefined; // a broken key just disables caching for this call
+    }
+    const version = getRegistry().version;
+    const c = entry.cache;
+    if (c && c.key === key && c.theme === rc.theme && c.ctx === rc.ctx && c.width === rc.width && c.version === version)
+        return c;
+    entry.cache = { key, theme: rc.theme, ctx: rc.ctx, width: rc.width, version };
+    return entry.cache;
+}
+/** Time a real (uncached) call. Too many slow ones in a row suspend the widget. */
+function timed(entry, fn) {
+    const t0 = nowMs();
+    try {
+        return fn();
+    }
+    finally {
+        const ms = nowMs() - t0;
+        entry.lastRenderMs = ms;
+        if (ms > SLOW_RENDER_MS) {
+            if (++entry.strikes >= SLOW_RENDER_STRIKES && !entry.suspended) {
+                entry.suspended = true;
+                entry.error = { phase: "render", message: `suspended: ${SLOW_RENDER_STRIKES} slow renders (last ${Math.round(ms)}ms)`, at: Date.now() };
+            }
+        }
+        else {
+            entry.strikes = 0;
+        }
+    }
+}
+const SUSPENDED_VIEW = { text: "suspended", level: "warn" };
+/**
+ * A widget's text is untrusted: it may carry a file name, a branch, a server's reply. Escape
+ * sequences (titles, links, clipboard writes, cursor moves), control characters and bidi controls
+ * are removed and line breaks become spaces, so one value stays on one line and cannot reach the
+ * terminal. SGR colour is kept for widgets that colour their own text; spacing is left as given.
+ */
+const cleanText = (value) => (value === undefined || value === null ? undefined : scrubText(value, true));
+function cleanIcon(icon) {
+    if (typeof icon === "string")
+        return scrubText(icon);
+    if (icon && typeof icon === "object")
+        return icon.plain === undefined ? { nerd: scrubText(icon.nerd) } : { nerd: scrubText(icon.nerd), plain: scrubText(icon.plain) };
+    return icon;
+}
+/** A view with every text field cleaned (see `cleanText`). The colour and level are the widget's own. */
+function cleanView(view) {
+    if (!view || typeof view !== "object")
+        return undefined;
+    const out = { ...view };
+    if (view.icon !== undefined)
+        out.icon = cleanIcon(view.icon);
+    for (const key of ["text", "label", "tag"]) {
+        if (view[key] !== undefined)
+            out[key] = cleanText(view[key]);
+    }
+    return out;
+}
+/** Detail lines cleaned the same way; anything that is not an array of lines yields none. */
+/** Whether the terminal draws OSC 8 links. A failure to find out means no. */
+function terminalLinks() {
+    try {
+        return getCapabilities().hyperlinks;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One detail line as a clean string. Every piece of text goes through `cleanText`, so nothing a
+ * widget passes in can add an escape sequence; the only OSC 8 sequences in the result are the ones
+ * built here, from a URL `safeLinkUrl` accepted around a label that is not empty once cleaned.
+ */
+function cleanDetailLine(line, links) {
+    if (!Array.isArray(line))
+        return cleanText(line) ?? "";
+    let out = "";
+    for (const piece of line) {
+        if (typeof piece === "string") {
+            out += cleanText(piece) ?? "";
+        }
+        else if (piece && typeof piece === "object" && typeof piece.text === "string") {
+            const label = cleanText(piece.text) ?? "";
+            const url = links ? safeLinkUrl(piece.url) : undefined;
+            out += url && label.trim() ? hyperlink(label, url) : label;
+        }
+    }
+    return out;
+}
+const cleanLines = (lines) => {
+    if (!Array.isArray(lines))
+        return [];
+    const links = terminalLinks();
+    return lines.map((l) => cleanDetailLine(l, links));
+};
+/**
+ * Render a widget without letting it throw: a failure is recorded on the widget and returned as
+ * an "error" view. Returns undefined when the widget itself returns undefined (hidden).
+ * Widgets with `cacheKey` are only re-rendered when the key, width, theme, context or registry
+ * version changes; a widget that renders slowly several times in a row is suspended.
+ */
+export function renderWidget(spec, rc) {
+    const entry = getRegistry().widgets.get(spec.id);
+    if (entry?.suspended)
+        return SUSPENDED_VIEW;
+    const cache = entry ? cacheFor(entry, rc) : undefined;
+    if (cache?.view)
+        return cache.view.value;
+    try {
+        const view = cleanView(entry ? timed(entry, () => spec.render(rc)) : spec.render(rc));
+        if (entry?.error?.phase === "render" && !entry.suspended)
+            entry.error = undefined;
+        if (cache && !entry?.suspended)
+            cache.view = { value: view };
+        return entry?.suspended ? SUSPENDED_VIEW : view;
+    }
+    catch (e) {
+        record(spec.id, "render", e);
+        return { text: "error", level: "error" };
+    }
+}
+/** Detail lines of a widget; a failure is recorded and yields no lines. Cached like `renderWidget`. */
+export function detailWidget(spec, rc) {
+    const entry = getRegistry().widgets.get(spec.id);
+    if (entry?.suspended)
+        return [];
+    const cache = entry ? cacheFor(entry, rc) : undefined;
+    if (cache?.lines)
+        return cache.lines.value;
+    try {
+        const lines = cleanLines((entry ? timed(entry, () => spec.detail?.(rc)) : spec.detail?.(rc)) ?? []);
+        if (entry?.error?.phase === "detail")
+            entry.error = undefined;
+        if (cache && !entry?.suspended)
+            cache.lines = { value: lines };
+        return entry?.suspended ? [] : lines;
+    }
+    catch (e) {
+        record(spec.id, "detail", e);
+        return [];
+    }
+}
+/** The last recorded failure of a widget, if any. */
+export function widgetError(id) {
+    return getRegistry().widgets.get(id)?.error;
+}
+/** Turn a widget off or on. The choice is saved and survives restarts. */
+export function setWidgetDisabled(id, disabled) {
+    const reg = getRegistry();
+    const entry = reg.widgets.get(id);
+    if (!entry)
+        return false;
+    if (disabled) {
+        reg.disabled.add(id);
+        stopTimer(entry);
+    }
+    else {
+        reg.disabled.delete(id);
+        if (entry.suspended)
+            entry.error = undefined;
+        entry.suspended = false;
+        entry.strikes = 0;
+        entry.cache = undefined;
+        startTimer(reg, entry);
+        runUpdate(reg, entry);
+    }
+    saveDisabled(reg.disabled);
+    changed(reg);
+    return true;
+}
+/** Run a widget's update now, even outside its timer. */
+export function refreshWidget(id) {
+    const reg = getRegistry();
+    const entry = reg.widgets.get(id);
+    if (!entry)
+        return false;
+    runUpdate(reg, entry);
+    return true;
+}
+/** Snapshot of every registered widget, for `/widgets`. */
+export function widgetInfo() {
+    const reg = getRegistry();
+    return [...reg.widgets.values()]
+        .map((e) => ({
+        id: e.spec.id,
+        title: e.spec.title ?? e.spec.id,
+        slots: e.spec.slots ?? ["footer", "sidebar"],
+        disabled: reg.disabled.has(e.spec.id),
+        refreshMs: e.spec.refreshMs,
+        lastUpdateAt: e.lastUpdateAt,
+        lastDurationMs: e.lastDurationMs,
+        inflight: !!e.inflight,
+        suspended: !!e.suspended,
+        lastRenderMs: e.lastRenderMs,
+        error: e.error,
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Plain-text table for `/widgets list`. */
+export function formatWidgetList(list, now = Date.now()) {
+    if (!list.length)
+        return "No widgets registered.";
+    const ago = (t) => (t === undefined ? "never" : `${Math.max(0, Math.round((now - t) / 1000))}s ago`);
+    return list
+        .map((w) => {
+        const state = w.disabled ? "disabled" : w.suspended ? "suspended" : w.error ? "error" : w.inflight ? "updating" : "ok";
+        const parts = [`${w.id} [${state}]`, w.slots.join("+") || "command", `updated ${ago(w.lastUpdateAt)}`];
+        if (w.lastDurationMs !== undefined)
+            parts.push(`${w.lastDurationMs}ms`);
+        if (w.error)
+            parts.push(`${w.error.phase}: ${w.error.message}`);
+        return parts.join(" · ");
+    })
+        .join("\n");
+}
+/** Palette actions of every enabled, non-suspended widget, in widget order. */
+export function widgetActions() {
+    const reg = getRegistry();
+    const out = [];
+    for (const spec of widgetsForAny()) {
+        const entry = reg.widgets.get(spec.id);
+        if (!entry || entry.suspended)
+            continue;
+        for (const a of spec.actions ?? []) {
+            out.push({ widgetId: spec.id, widgetTitle: spec.title ?? spec.id, id: a.id, label: a.label, description: a.description });
+        }
+    }
+    return out;
+}
+function widgetsForAny() {
+    const reg = getRegistry();
+    return [...reg.widgets.values()]
+        .map((e) => e.spec)
+        .filter((s) => !reg.disabled.has(s.id))
+        .sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.id.localeCompare(b.id));
+}
+/** Palette value for an action: ids are encoded, so they may contain any character. */
+export function widgetActionValue(widgetId, actionId) {
+    return `widget:${encodeURIComponent(widgetId)}:${encodeURIComponent(actionId)}`;
+}
+export function parseWidgetActionValue(value) {
+    const m = value.match(/^widget:([^:]*):([^:]*)$/);
+    if (!m)
+        return undefined;
+    try {
+        return { widgetId: decodeURIComponent(m[1]), actionId: decodeURIComponent(m[2]) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run a widget's `onDetailClick` for the clicked detail line. Resolves to undefined on success, or
+ * to a short message when it failed (also recorded on the widget as an "action" error).
+ */
+export async function runWidgetClick(widgetId, index, ctx) {
+    const reg = getRegistry();
+    const entry = reg.widgets.get(widgetId);
+    const click = entry && !reg.disabled.has(widgetId) && !entry.suspended ? entry.spec.onDetailClick : undefined;
+    if (!entry || !click)
+        return undefined;
+    try {
+        await click(index, ctx);
+        if (entry.error?.phase === "action")
+            entry.error = undefined;
+        changed(reg);
+        return undefined;
+    }
+    catch (e) {
+        record(widgetId, "action", e);
+        changed(reg);
+        return `${entry.spec.title ?? widgetId}: click failed: ${messageOf(e)}`;
+    }
+}
+/**
+ * Run a widget action. Resolves to undefined on success, or to a short message when the action
+ * is unknown or failed (the failure is also recorded on the widget).
+ */
+export async function runWidgetAction(widgetId, actionId, ctx) {
+    const reg = getRegistry();
+    const entry = reg.widgets.get(widgetId);
+    const action = entry && !reg.disabled.has(widgetId) ? entry.spec.actions?.find((a) => a.id === actionId) : undefined;
+    if (!entry || !action)
+        return `No action "${actionId}" on widget "${widgetId}".`;
+    try {
+        await action.run(ctx);
+        if (entry.error?.phase === "action")
+            entry.error = undefined;
+        changed(reg);
+        return undefined;
+    }
+    catch (e) {
+        record(widgetId, "action", e);
+        changed(reg);
+        return `${entry.spec.title ?? widgetId}: ${action.label} failed: ${messageOf(e)}`;
+    }
+}