@femtomc/mu-agent 26.2.105 → 26.2.107

package/README.md

@@ -22,23 +22,29 @@ These are loaded by runtime code and are the single source of truth for default
 ## Bundled starter skills
 
 Bundled starter skills live under `packages/agent/prompts/skills/` and are bootstrapped
-into `~/.mu/skills/` (or `$MU_HOME/skills/`) by the CLI store-initialization path:
-
-- `mu`
-- `memory`
-- `planning`
-- `hud`
-- `orchestration`
-- `control-flow`
-- `code-mode`
-- `tmux`
+into `~/.mu/skills/` (or `$MU_HOME/skills/`) by the CLI store-initialization path.
+They are organized as category meta-skills plus subskills:
+
+- `core`
+  - `mu`
+  - `memory`
+  - `tmux`
+  - `code-mode`
 - `subagents`
-- `heartbeats`
-- `crons`
-- `setup-slack`
-- `setup-discord`
-- `setup-telegram`
-- `setup-neovim`
+  - `planning`
+  - `protocol`
+  - `execution`
+  - `control-flow`
+  - `model-routing`
+  - `hud`
+- `automation`
+  - `heartbeats`
+  - `crons`
+- `messaging`
+  - `setup-slack`
+  - `setup-discord`
+  - `setup-telegram`
+  - `setup-neovim`
 - `writing`
 
 Starter skills are version-synced by CLI bootstrap. Initial bootstrap seeds missing
@@ -83,6 +89,23 @@ Default operator UI theme is `mu-gruvbox-dark`.
 - `/mu brand on|off|toggle` — enable/disable UI branding
 - `/mu hud ...` — HUD command for enabling/inspecting/clearing HUD docs; does not inject HUD metadata into branding footer
 - `/mu help` — dispatcher catalog of registered `/mu` subcommands
+- `/mu ui ...` — inspect interactive `UiDoc`s (`status`/`snapshot`)
+
+## Programmable UI documents
+
+Skills can publish interactive UI state via the `mu_ui` tool. Rendered `UiDoc`s survive session reconnects
+(30 minute retention per session ID), respect revision/version bumps, and route action clicks/taps back to
+plain command text via `metadata.command_text` (the `/answer` flow is the reference pattern).
+
+Actions without `metadata.command_text` are treated as non-interactive and rendered as deterministic fallback rows.
+
+Current runtime behavior is channel-specific:
+
+- Slack renders rich blocks + interactive action buttons.
+- Discord/Telegram/Neovim render text-first docs plus tokenized action callbacks.
+- When interactive controls cannot be rendered, adapters append deterministic text fallback.
+
+See the [Programmable UI substrate guide](../../docs/mu-ui.md) for the full support matrix and workflow.
 
 ## Tooling model (CLI-first)
 

package/dist/extensions/index.d.ts

@@ -3,6 +3,7 @@ export { eventLogExtension } from "./event-log.js";
 export { hudExtension } from "./hud.js";
 export { muOperatorExtension } from "./mu-operator.js";
 export { muServeExtension } from "./mu-serve.js";
+export { uiExtension } from "./ui.js";
 /**
  * Serve-mode extension — single facade that bundles all serve extensions.
  */

package/dist/extensions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQjD;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAA4C,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAA+C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQtC;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAA4C,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAA+C,CAAC"}

package/dist/extensions/index.js

@@ -3,6 +3,7 @@ export { eventLogExtension } from "./event-log.js";
 export { hudExtension } from "./hud.js";
 export { muOperatorExtension } from "./mu-operator.js";
 export { muServeExtension } from "./mu-serve.js";
+export { uiExtension } from "./ui.js";
 const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? "ts" : "js";
 function resolveBundledExtensionPath(moduleBasename) {
     return new URL(`./${moduleBasename}.${RUNTIME_EXTENSION}`, import.meta.url).pathname;

package/dist/extensions/mu-command-dispatcher.d.ts

@@ -4,7 +4,6 @@ export type MuSubcommandRegistration = {
     subcommand: string;
     summary: string;
     usage: string;
-    aliases?: string[];
     handler: MuSubcommandHandler;
 };
 export declare function resetMuCommandDispatcher(): void;

package/dist/extensions/mu-command-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mu-command-dispatcher.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-command-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEvG,MAAM,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAcF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAoHD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAsDnG"}
+{"version":3,"file":"mu-command-dispatcher.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-command-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEvG,MAAM,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAYF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AA+GD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAmBnG"}

package/dist/extensions/mu-command-dispatcher.js

@@ -10,8 +10,7 @@ function isValidSubcommandToken(value) {
     return /^[a-z][a-z0-9_-]*$/.test(value);
 }
 function subcommandUsageSummary(entry) {
-    const aliasSuffix = entry.aliases && entry.aliases.length > 0 ? ` (aliases: ${entry.aliases.join(", ")})` : "";
-    return `- ${entry.usage} — ${entry.summary}${aliasSuffix}`;
+    return `- ${entry.usage} — ${entry.summary}`;
 }
 function renderSubcommandCatalog(state) {
     if (state.entries.size === 0) {
@@ -26,11 +25,7 @@ function renderSubcommandCatalog(state) {
     return lines.join("\n");
 }
 function renderSubcommandHelp(entry) {
-    const lines = [entry.summary, "", `Usage: ${entry.usage}`];
-    if (entry.aliases && entry.aliases.length > 0) {
-        lines.push(`Aliases: ${entry.aliases.map((alias) => `/mu ${alias}`).join(", ")}`);
-    }
-    return lines.join("\n");
+    return [entry.summary, "", `Usage: ${entry.usage}`].join("\n");
 }
 function parseInvocation(args) {
     const trimmed = args.trim();
@@ -48,10 +43,10 @@ function parseInvocation(args) {
 }
 function resolveEntry(state, token) {
     const normalized = normalizeSubcommand(token);
-    if (!normalized)
+    if (!normalized) {
         return null;
-    const canonical = state.aliases.get(normalized) ?? normalized;
-    return state.entries.get(canonical) ?? null;
+    }
+    return state.entries.get(normalized) ?? null;
 }
 function ensureDispatcher(pi) {
     if (singletonState) {
@@ -59,7 +54,6 @@ function ensureDispatcher(pi) {
     }
     const state = {
         entries: new Map(),
-        aliases: new Map(),
     };
     singletonState = state;
     pi.registerCommand("mu", {
@@ -106,40 +100,9 @@ export function registerMuSubcommand(pi, registration) {
     if (!registration.usage.startsWith("/mu ")) {
         throw new Error(`mu subcommand usage must start with '/mu ': ${registration.usage}`);
     }
-    const normalizedAliases = (registration.aliases ?? [])
-        .map((alias) => normalizeSubcommand(alias))
-        .filter((alias) => alias.length > 0 && alias !== normalizedSubcommand);
-    for (const alias of normalizedAliases) {
-        if (!isValidSubcommandToken(alias)) {
-            throw new Error(`Invalid mu subcommand alias: ${alias}`);
-        }
-        if (RESERVED_SUBCOMMANDS.has(alias)) {
-            throw new Error(`Reserved mu subcommand alias: ${alias}`);
-        }
-    }
-    const existing = state.entries.get(normalizedSubcommand);
-    if (existing) {
-        for (const alias of existing.normalizedAliases) {
-            state.aliases.delete(alias);
-        }
-    }
-    for (const alias of normalizedAliases) {
-        const occupiedBy = state.aliases.get(alias);
-        if (occupiedBy && occupiedBy !== normalizedSubcommand) {
-            throw new Error(`mu subcommand alias '${alias}' is already registered by '${occupiedBy}'`);
-        }
-        if (state.entries.has(alias) && alias !== normalizedSubcommand) {
-            throw new Error(`mu subcommand alias '${alias}' conflicts with existing subcommand`);
-        }
-    }
     const entry = {
         ...registration,
         normalizedSubcommand,
-        normalizedAliases,
     };
     state.entries.set(normalizedSubcommand, entry);
-    state.aliases.set(normalizedSubcommand, normalizedSubcommand);
-    for (const alias of normalizedAliases) {
-        state.aliases.set(alias, normalizedSubcommand);
-    }
 }

package/dist/extensions/mu-operator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mu-operator.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-operator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAKlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAInD;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"mu-operator.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-operator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAKnD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/mu-operator.js

@@ -7,8 +7,10 @@
 import { brandingExtension } from "./branding.js";
 import { eventLogExtension } from "./event-log.js";
 import { hudExtension } from "./hud.js";
+import { uiExtension } from "./ui.js";
 export function muOperatorExtension(pi) {
     hudExtension(pi);
+    uiExtension(pi);
     brandingExtension(pi);
     eventLogExtension(pi);
 }

package/dist/extensions/mu-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mu-serve.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-serve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAKlE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,QAIhD;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"mu-serve.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-serve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,QAKhD;AAED,eAAe,gBAAgB,CAAC"}

package/dist/extensions/mu-serve.js

@@ -7,8 +7,10 @@
 import { brandingExtension } from "./branding.js";
 import { eventLogExtension } from "./event-log.js";
 import { hudExtension } from "./hud.js";
+import { uiExtension } from "./ui.js";
 export function muServeExtension(pi) {
     hudExtension(pi);
+    uiExtension(pi);
     brandingExtension(pi);
     eventLogExtension(pi);
 }

package/dist/extensions/ui.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function uiExtension(pi: ExtensionAPI): void;
+export default uiExtension;
+//# sourceMappingURL=ui.d.ts.map

package/dist/extensions/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/extensions/ui.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA4TpF,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,QAiF3C;AAED,eAAe,WAAW,CAAC"}

package/dist/extensions/ui.js

@@ -0,0 +1,335 @@
+import { normalizeUiDocs, parseUiDoc, } from "@femtomc/mu-core";
+import { registerMuSubcommand } from "./mu-command-dispatcher.js";
+const UI_DISPLAY_DOCS_MAX = 16;
+const UI_WIDGET_COMPONENTS_MAX = 6;
+const UI_WIDGET_ACTIONS_MAX = 4;
+const UI_SESSION_KEY_FALLBACK = "__mu_ui_active_session__";
+const STATE_BY_SESSION = new Map();
+const UI_STATE_TTL_MS = 30 * 60 * 1000; // keep session state for 30 minutes after last access
+function createState() {
+    return { docsById: new Map() };
+}
+function pruneStaleStates(nowMs) {
+    for (const [key, entry] of STATE_BY_SESSION.entries()) {
+        if (nowMs - entry.lastAccessMs > UI_STATE_TTL_MS) {
+            STATE_BY_SESSION.delete(key);
+        }
+    }
+}
+function sessionKey(ctx) {
+    const manager = ctx.sessionManager;
+    if (!manager) {
+        return UI_SESSION_KEY_FALLBACK;
+    }
+    const sessionId = manager.getSessionId();
+    return sessionId ?? UI_SESSION_KEY_FALLBACK;
+}
+function ensureState(key) {
+    const nowMs = Date.now();
+    pruneStaleStates(nowMs);
+    const existing = STATE_BY_SESSION.get(key);
+    if (existing) {
+        existing.lastAccessMs = nowMs;
+        return existing.state;
+    }
+    const fresh = createState();
+    STATE_BY_SESSION.set(key, { state: fresh, lastAccessMs: nowMs });
+    return fresh;
+}
+function touchState(key) {
+    const entry = STATE_BY_SESSION.get(key);
+    if (entry) {
+        entry.lastAccessMs = Date.now();
+    }
+}
+function activeDocs(state, maxDocs = UI_DISPLAY_DOCS_MAX) {
+    return normalizeUiDocs([...state.docsById.values()], { maxDocs });
+}
+function preferredDocForState(state, candidate) {
+    const existing = state.docsById.get(candidate.ui_id);
+    if (!existing) {
+        return candidate;
+    }
+    const merged = normalizeUiDocs([existing, candidate], { maxDocs: 2 });
+    const chosen = merged.find((doc) => doc.ui_id === candidate.ui_id);
+    return chosen ?? candidate;
+}
+function short(text, max = 64) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= max) {
+        return normalized;
+    }
+    if (max <= 1) {
+        return "…";
+    }
+    return `${normalized.slice(0, max - 1)}…`;
+}
+function statusSummary(docs) {
+    const ids = docs.map((doc) => doc.ui_id).join(", ") || "(none)";
+    return [`UI docs: ${docs.length}`, `ids: ${ids}`].join(" · ");
+}
+function snapshotText(docs, format) {
+    if (docs.length === 0) {
+        return "(no UI docs)";
+    }
+    if (format === "compact") {
+        return docs
+            .map((doc) => `${doc.ui_id}: ${short(doc.title, 32)} (${doc.revision.version})`)
+            .join(" | ");
+    }
+    const lines = [];
+    docs.slice(0, 8).forEach((doc, idx) => {
+        lines.push(`${idx + 1}. ${doc.title} [${doc.ui_id}]`);
+        if (doc.summary) {
+            lines.push(`   summary: ${short(doc.summary, 120)}`);
+        }
+        if (doc.actions.length > 0) {
+            lines.push(`   actions: ${doc.actions.map((action) => action.label).join(", ")}`);
+        }
+    });
+    if (docs.length > 8) {
+        lines.push(`... (+${docs.length - 8} more docs)`);
+    }
+    return lines.join("\n");
+}
+function parseDocInput(value) {
+    if (value === undefined) {
+        return { ok: false, error: "doc is required" };
+    }
+    const parsed = parseUiDoc(value);
+    if (!parsed) {
+        return { ok: false, error: "Invalid UiDoc." };
+    }
+    return { ok: true, doc: parsed };
+}
+function parseDocListInput(value) {
+    if (!Array.isArray(value)) {
+        return { ok: false, error: "docs must be an array" };
+    }
+    const docs = [];
+    for (let idx = 0; idx < value.length; idx += 1) {
+        const parsed = parseUiDoc(value[idx]);
+        if (!parsed) {
+            return { ok: false, error: `docs[${idx}]: invalid UiDoc` };
+        }
+        docs.push(parsed);
+    }
+    return { ok: true, docs: normalizeUiDocs(docs, { maxDocs: UI_DISPLAY_DOCS_MAX }) };
+}
+function parseSnapshotFormat(raw) {
+    const normalized = (raw ?? "compact").trim().toLowerCase();
+    return normalized === "multiline" ? "multiline" : "compact";
+}
+function applyUiAction(params, state) {
+    const docs = activeDocs(state);
+    switch (params.action) {
+        case "status":
+            return { ok: true, action: "status", message: statusSummary(docs) };
+        case "snapshot": {
+            const format = parseSnapshotFormat(params.snapshot_format);
+            return {
+                ok: true,
+                action: "snapshot",
+                message: snapshotText(docs, format),
+                extra: { snapshot_format: format },
+            };
+        }
+        case "set":
+        case "update": {
+            const parsed = parseDocInput(params.doc);
+            if (!parsed.ok) {
+                return { ok: false, action: params.action, message: parsed.error };
+            }
+            const preferred = preferredDocForState(state, parsed.doc);
+            state.docsById.set(parsed.doc.ui_id, preferred);
+            return {
+                ok: true,
+                action: params.action,
+                message: `UI doc set: ${parsed.doc.ui_id}`,
+                extra: { ui_id: parsed.doc.ui_id },
+            };
+        }
+        case "replace": {
+            const parsed = parseDocListInput(params.docs);
+            if (!parsed.ok) {
+                return { ok: false, action: "replace", message: parsed.error };
+            }
+            state.docsById.clear();
+            for (const doc of parsed.docs) {
+                state.docsById.set(doc.ui_id, doc);
+            }
+            return {
+                ok: true,
+                action: "replace",
+                message: `UI docs replaced (${parsed.docs.length}).`,
+                extra: { doc_count: parsed.docs.length },
+            };
+        }
+        case "remove": {
+            const uiId = (params.ui_id ?? "").trim();
+            if (!uiId) {
+                return { ok: false, action: "remove", message: "Missing ui_id." };
+            }
+            if (!state.docsById.delete(uiId)) {
+                return { ok: false, action: "remove", message: `UI doc not found: ${uiId}` };
+            }
+            return { ok: true, action: "remove", message: `UI doc removed: ${uiId}` };
+        }
+        case "clear":
+            state.docsById.clear();
+            return { ok: true, action: "clear", message: "UI docs cleared." };
+    }
+}
+function buildToolResult(opts) {
+    const docs = activeDocs(opts.state);
+    const result = {
+        content: [{ type: "text", text: opts.message }],
+        ui_docs: docs,
+        details: {
+            ok: opts.ok,
+            action: opts.action,
+            doc_count: docs.length,
+            ui_ids: docs.map((doc) => doc.ui_id),
+            ...(opts.extra ?? {}),
+        },
+    };
+    return result;
+}
+function renderDocPreview(theme, doc) {
+    const lines = [];
+    lines.push(`${theme.fg("accent", doc.title)} ${theme.fg("muted", `[${doc.ui_id}]`)}`);
+    if (doc.summary) {
+        lines.push(theme.fg("muted", short(doc.summary, 80)));
+    }
+    const components = doc.components.slice(0, UI_WIDGET_COMPONENTS_MAX);
+    if (components.length > 0) {
+        lines.push(theme.fg("dim", "Components:"));
+        for (const component of components) {
+            lines.push(`  ${componentPreview(component)}`);
+        }
+    }
+    if (doc.actions.length > 0) {
+        lines.push(theme.fg("muted", "Actions:"));
+        const visibleActions = doc.actions.slice(0, UI_WIDGET_ACTIONS_MAX);
+        for (let idx = 0; idx < visibleActions.length; idx += 1) {
+            const action = visibleActions[idx];
+            lines.push(`  ${idx + 1}. ${action.label}`);
+        }
+        if (doc.actions.length > visibleActions.length) {
+            lines.push(`  ... (+${doc.actions.length - visibleActions.length} more actions)`);
+        }
+        lines.push(theme.fg("dim", "Actions are handled through channel-native callbacks."));
+    }
+    else {
+        lines.push(theme.fg("dim", "No interactive actions."));
+    }
+    return lines;
+}
+function componentPreview(component) {
+    const { kind } = component;
+    switch (kind) {
+        case "text":
+            return `text · ${short(component.text, 80)}`;
+        case "list":
+            return `list · ${component.title ?? kind} · ${component.items.length} item(s)`;
+        case "key_value":
+            return `key_value · ${component.title ?? kind} · ${component.rows.length} row(s)`;
+        case "divider":
+            return "divider";
+    }
+    return kind;
+}
+function refreshUi(ctx) {
+    const key = sessionKey(ctx);
+    const state = ensureState(key);
+    if (!ctx.hasUI) {
+        return;
+    }
+    const docs = activeDocs(state);
+    if (docs.length === 0) {
+        ctx.ui.setStatus("mu-ui", undefined);
+        ctx.ui.setWidget("mu-ui", undefined);
+        return;
+    }
+    const labels = docs.map((doc) => doc.ui_id).join(", ");
+    ctx.ui.setStatus("mu-ui", [
+        ctx.ui.theme.fg("dim", "ui"),
+        ctx.ui.theme.fg("muted", "·"),
+        ctx.ui.theme.fg("accent", `${docs.length}`),
+        ctx.ui.theme.fg("muted", "·"),
+        ctx.ui.theme.fg("text", labels),
+    ].join(" "));
+    ctx.ui.setWidget("mu-ui", renderDocPreview(ctx.ui.theme, docs[0]), { placement: "belowEditor" });
+}
+export function uiExtension(pi) {
+    registerMuSubcommand(pi, {
+        subcommand: "ui",
+        summary: "Inspect interactive UI docs",
+        usage: "/mu ui status|snapshot [compact|multiline]",
+        handler: async (args, ctx) => {
+            const tokens = args
+                .trim()
+                .split(/\s+/)
+                .filter((token) => token.length > 0);
+            const subcommand = tokens[0] ?? "status";
+            const key = sessionKey(ctx);
+            const state = ensureState(key);
+            if (subcommand === "status" || subcommand === "snapshot") {
+                const snapshotFormat = subcommand === "snapshot" ? tokens[1] : undefined;
+                const actionParams = {
+                    action: subcommand,
+                    snapshot_format: snapshotFormat,
+                };
+                const result = applyUiAction(actionParams, state);
+                refreshUi(ctx);
+                ctx.ui.notify(result.message, result.ok ? "info" : "error");
+                return;
+            }
+            ctx.ui.notify("Usage: /mu ui status|snapshot [compact|multiline]", "info");
+        },
+    });
+    pi.registerTool({
+        name: "mu_ui",
+        label: "mu UI",
+        description: "Publish, inspect, and manage interactive UI documents.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["status", "snapshot", "set", "update", "replace", "remove", "clear"],
+                },
+                doc: { type: "object", additionalProperties: true },
+                docs: { type: "array", items: { type: "object", additionalProperties: true } },
+                ui_id: { type: "string" },
+                snapshot_format: { type: "string", enum: ["compact", "multiline"] },
+            },
+            required: ["action"],
+        },
+        execute: async (_toolCallId, paramsRaw, _signal, _onUpdate, ctx) => {
+            const key = sessionKey(ctx);
+            const state = ensureState(key);
+            const params = paramsRaw;
+            const result = applyUiAction(params, state);
+            refreshUi(ctx);
+            return buildToolResult({ state, ...result });
+        },
+    });
+    pi.on("session_start", (_event, ctx) => {
+        refreshUi(ctx);
+    });
+    pi.on("session_switch", (_event, ctx) => {
+        refreshUi(ctx);
+    });
+    pi.on("session_shutdown", (_event, ctx) => {
+        const key = sessionKey(ctx);
+        touchState(key);
+        if (!ctx.hasUI) {
+            return;
+        }
+        ctx.ui.setStatus("mu-ui", undefined);
+        ctx.ui.setWidget("mu-ui", undefined);
+    });
+}
+export default uiExtension;