@femtomc/mu-agent 26.2.107 → 26.2.109

package/dist/extensions/ui.js

@@ -1,13 +1,34 @@
-import { normalizeUiDocs, parseUiDoc, } from "@femtomc/mu-core";
+import { normalizeUiDocs, parseUiDoc, resolveUiStatusProfileName, uiStatusProfileWarnings, } from "@femtomc/mu-core";
+import { matchesKey } from "@mariozechner/pi-tui";
 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_WIDGET_COMPONENT_DETAILS_MAX = 3;
+const UI_PICKER_COMPONENTS_MAX = 8;
+const UI_PICKER_LIST_ITEMS_MAX = 4;
+const UI_PICKER_KEYVALUE_ROWS_MAX = 4;
 const UI_SESSION_KEY_FALLBACK = "__mu_ui_active_session__";
+const UI_PROMPT_PREVIEW_MAX = 160;
+const UI_INTERACT_SHORTCUT = "ctrl+shift+u";
+const UI_INTERACT_OVERLAY_OPTIONS = {
+    anchor: "top-left",
+    row: 0,
+    col: 0,
+    width: "100%",
+    maxHeight: "100%",
+    margin: 0,
+};
 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() };
+    return {
+        docsById: new Map(),
+        pendingPrompt: null,
+        promptedRevisionKeys: new Set(),
+        awaitingUiIds: new Set(),
+        interactionDepth: 0,
+    };
 }
 function pruneStaleStates(nowMs) {
     for (const [key, entry] of STATE_BY_SESSION.entries()) {
@@ -45,6 +66,60 @@ function touchState(key) {
 function activeDocs(state, maxDocs = UI_DISPLAY_DOCS_MAX) {
     return normalizeUiDocs([...state.docsById.values()], { maxDocs });
 }
+function docRevisionKey(doc) {
+    return `${doc.ui_id}:${doc.revision.id}:${doc.revision.version}`;
+}
+function retainPromptedRevisionKeysForActiveDocs(state) {
+    const activeRevisionKeys = new Set();
+    for (const doc of state.docsById.values()) {
+        activeRevisionKeys.add(docRevisionKey(doc));
+    }
+    for (const key of [...state.promptedRevisionKeys]) {
+        if (!activeRevisionKeys.has(key)) {
+            state.promptedRevisionKeys.delete(key);
+        }
+    }
+}
+function retainAwaitingUiIdsForActiveDocs(state) {
+    for (const uiId of [...state.awaitingUiIds]) {
+        const doc = state.docsById.get(uiId);
+        if (!doc || runnableActions(doc).length === 0) {
+            state.awaitingUiIds.delete(uiId);
+        }
+    }
+}
+function armAutoPromptForUiDocs(state, changedUiIds) {
+    if (changedUiIds.length === 0) {
+        return;
+    }
+    const changedDocs = [];
+    for (const uiId of changedUiIds) {
+        const doc = state.docsById.get(uiId);
+        if (doc) {
+            changedDocs.push(doc);
+        }
+    }
+    const candidates = changedDocs.filter((doc) => {
+        if (runnableActions(doc).length === 0) {
+            return false;
+        }
+        return !state.promptedRevisionKeys.has(docRevisionKey(doc));
+    });
+    if (candidates.length === 0) {
+        return;
+    }
+    candidates.sort((left, right) => {
+        if (left.updated_at_ms !== right.updated_at_ms) {
+            return right.updated_at_ms - left.updated_at_ms;
+        }
+        return left.ui_id.localeCompare(right.ui_id);
+    });
+    const doc = candidates[0];
+    const actions = runnableActions(doc);
+    const actionId = actions.length === 1 ? actions[0].id : undefined;
+    state.pendingPrompt = { uiId: doc.ui_id, actionId };
+    state.promptedRevisionKeys.add(docRevisionKey(doc));
+}
 function preferredDocForState(state, candidate) {
     const existing = state.docsById.get(candidate.ui_id);
     if (!existing) {
@@ -54,6 +129,26 @@ function preferredDocForState(state, candidate) {
     const chosen = merged.find((doc) => doc.ui_id === candidate.ui_id);
     return chosen ?? candidate;
 }
+function awaitingDocs(state, docs) {
+    return docs.filter((doc) => state.awaitingUiIds.has(doc.ui_id) && runnableActions(doc).length > 0);
+}
+function beginUiInteraction(ctx, state) {
+    state.interactionDepth += 1;
+    refreshUi(ctx);
+}
+function endUiInteraction(ctx, state) {
+    state.interactionDepth = Math.max(0, state.interactionDepth - 1);
+    refreshUi(ctx);
+}
+async function withUiInteraction(ctx, state, run) {
+    beginUiInteraction(ctx, state);
+    try {
+        return await run();
+    }
+    finally {
+        endUiInteraction(ctx, state);
+    }
+}
 function short(text, max = 64) {
     const normalized = text.replace(/\s+/g, " ").trim();
     if (normalized.length <= max) {
@@ -64,27 +159,119 @@ function short(text, max = 64) {
     }
     return `${normalized.slice(0, max - 1)}…`;
 }
-function statusSummary(docs) {
+function statusProfileId(doc) {
+    return resolveUiStatusProfileName(doc);
+}
+function statusProfileMetadata(doc) {
+    const profile = doc.metadata.profile;
+    if (!isPlainObject(profile)) {
+        return null;
+    }
+    return profile;
+}
+function statusProfileVariant(doc) {
+    const profile = statusProfileMetadata(doc);
+    const rawVariant = typeof profile?.variant === "string" ? profile.variant.trim().toLowerCase() : "";
+    return rawVariant.length > 0 ? rawVariant : "status";
+}
+function isStatusProfileStatusVariant(doc) {
+    return statusProfileId(doc) !== null && statusProfileVariant(doc) === "status";
+}
+function statusProfileSnapshot(doc, format) {
+    if (!isStatusProfileStatusVariant(doc)) {
+        return null;
+    }
+    const profile = statusProfileMetadata(doc);
+    if (!profile) {
+        return null;
+    }
+    const snapshot = profile.snapshot;
+    if (!isPlainObject(snapshot)) {
+        return null;
+    }
+    const raw = snapshot[format];
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const normalized = raw.trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function compactSnapshotValue(doc) {
+    const profileCompact = statusProfileSnapshot(doc, "compact");
+    if (profileCompact) {
+        return short(profileCompact, 96);
+    }
+    if (doc.summary) {
+        return short(doc.summary, 64);
+    }
+    return `${short(doc.title, 32)} (${doc.revision.version})`;
+}
+function statusProfileDocCount(docs) {
+    return docs.reduce((count, doc) => count + (isStatusProfileStatusVariant(doc) ? 1 : 0), 0);
+}
+function statusProfileWarningCount(docs) {
+    return docs.reduce((count, doc) => count + uiStatusProfileWarnings(doc).length, 0);
+}
+function statusSummary(docs, awaitingCount = 0) {
     const ids = docs.map((doc) => doc.ui_id).join(", ") || "(none)";
-    return [`UI docs: ${docs.length}`, `ids: ${ids}`].join(" · ");
+    const parts = [`UI docs: ${docs.length}`, `ids: ${ids}`];
+    const statusProfiles = statusProfileDocCount(docs);
+    if (statusProfiles > 0) {
+        parts.push(`status_profiles: ${statusProfiles}`);
+    }
+    const warningCount = statusProfileWarningCount(docs);
+    if (warningCount > 0) {
+        parts.push(`profile_warnings: ${warningCount}`);
+    }
+    if (awaitingCount > 0) {
+        parts.push(`awaiting: ${awaitingCount}`);
+    }
+    return parts.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(" | ");
+        return docs.map((doc) => `${doc.ui_id}: ${compactSnapshotValue(doc)}`).join(" | ");
     }
     const lines = [];
     docs.slice(0, 8).forEach((doc, idx) => {
-        lines.push(`${idx + 1}. ${doc.title} [${doc.ui_id}]`);
-        if (doc.summary) {
+        const profileId = statusProfileId(doc);
+        lines.push(`${idx + 1}. ${doc.title} [${doc.ui_id}]${profileId ? ` profile=${profileId}` : ""}`);
+        const profileMultiline = statusProfileSnapshot(doc, "multiline");
+        if (profileMultiline) {
+            const snapshotLines = profileMultiline
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            if (snapshotLines.length > 0) {
+                for (const line of snapshotLines) {
+                    lines.push(`   ${short(line, 120)}`);
+                }
+            }
+            else {
+                lines.push(`   snapshot: ${compactSnapshotValue(doc)}`);
+            }
+        }
+        else if (isStatusProfileStatusVariant(doc)) {
+            lines.push(`   snapshot: ${compactSnapshotValue(doc)}`);
+        }
+        else if (doc.summary) {
             lines.push(`   summary: ${short(doc.summary, 120)}`);
         }
+        if (isStatusProfileStatusVariant(doc)) {
+            if (doc.actions.length > 0) {
+                lines.push(`   actions omitted for status profile (${doc.actions.length})`);
+            }
+            return;
+        }
         if (doc.actions.length > 0) {
-            lines.push(`   actions: ${doc.actions.map((action) => action.label).join(", ")}`);
+            const labels = [...doc.actions]
+                .sort((left, right) => left.id.localeCompare(right.id))
+                .map((action) => action.label)
+                .join(", ");
+            lines.push(`   actions: ${labels}`);
         }
     });
     if (docs.length > 8) {
@@ -116,22 +303,397 @@ function parseDocListInput(value) {
     }
     return { ok: true, docs: normalizeUiDocs(docs, { maxDocs: UI_DISPLAY_DOCS_MAX }) };
 }
+function statusProfileWarningsExtraForDoc(doc) {
+    const warnings = uiStatusProfileWarnings(doc);
+    if (warnings.length === 0) {
+        return {};
+    }
+    return { profile_warnings: warnings };
+}
+function statusProfileWarningsExtraForDocs(docs) {
+    const byUiId = {};
+    for (const doc of docs) {
+        const warnings = uiStatusProfileWarnings(doc);
+        if (warnings.length > 0) {
+            byUiId[doc.ui_id] = warnings;
+        }
+    }
+    return Object.keys(byUiId).length > 0 ? { profile_warnings: byUiId } : {};
+}
 function parseSnapshotFormat(raw) {
     const normalized = (raw ?? "compact").trim().toLowerCase();
     return normalized === "multiline" ? "multiline" : "compact";
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function actionCommandText(action) {
+    const raw = typeof action.metadata.command_text === "string" ? action.metadata.command_text.trim() : "";
+    return raw.length > 0 ? raw : null;
+}
+function extractTemplateKeys(text) {
+    const keys = [];
+    const seen = new Set();
+    const re = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+        const key = (match[1] ?? "").trim();
+        if (!key || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function replaceTemplateValues(template, values) {
+    let out = template;
+    for (const [key, value] of Object.entries(values)) {
+        const keyRe = new RegExp(`\\{\\{\\s*${escapeRegExp(key)}\\s*\\}\\}`, "g");
+        out = out.replace(keyRe, value);
+    }
+    return out;
+}
+function primitiveTemplateDefault(value) {
+    switch (typeof value) {
+        case "string":
+            return value;
+        case "number":
+        case "boolean":
+            return String(value);
+        default:
+            return value === null ? "" : null;
+    }
+}
+function valueAtTemplatePath(root, key) {
+    if (!key) {
+        return undefined;
+    }
+    const segments = key.split(".").filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return undefined;
+    }
+    let current = root;
+    for (const segment of segments) {
+        if (Array.isArray(current)) {
+            const index = Number.parseInt(segment, 10);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return undefined;
+            }
+            current = current[index];
+            continue;
+        }
+        if (!isPlainObject(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function templateDefaultsForAction(action, keys) {
+    if (!isPlainObject(action.payload) || keys.length === 0) {
+        return {};
+    }
+    const payload = action.payload;
+    const out = {};
+    for (const key of keys) {
+        const fallback = primitiveTemplateDefault(valueAtTemplatePath(payload, key));
+        if (fallback !== null) {
+            out[key] = fallback;
+        }
+    }
+    return out;
+}
+async function collectTemplateValues(opts) {
+    if (opts.templateKeys.length === 0) {
+        return {};
+    }
+    const defaults = templateDefaultsForAction(opts.action, opts.templateKeys);
+    const out = { ...defaults };
+    for (const key of opts.templateKeys) {
+        const defaultValue = defaults[key];
+        if (typeof defaultValue === "string" && defaultValue.trim().length > 0) {
+            continue;
+        }
+        const placeholder = typeof defaultValue === "string" ? defaultValue : `value for ${key}`;
+        const entered = await opts.ctx.ui.input(`UI field: ${key}`, placeholder);
+        if (entered === undefined) {
+            return null;
+        }
+        out[key] = entered;
+    }
+    return out;
+}
+function composePromptFromAction(opts) {
+    const rendered = replaceTemplateValues(opts.commandText, opts.templateValues).trim();
+    const unresolvedKeys = extractTemplateKeys(rendered);
+    if (unresolvedKeys.length === 0) {
+        return rendered;
+    }
+    const unresolvedLines = unresolvedKeys.map((key) => `- ${key}: (missing)`);
+    return [rendered, "", "Missing template values:", ...unresolvedLines].join("\n");
+}
+function runnableActions(doc) {
+    if (isStatusProfileStatusVariant(doc)) {
+        return [];
+    }
+    return doc.actions.filter((action) => actionCommandText(action) !== null);
+}
+function boundedIndex(index, length) {
+    if (length <= 0) {
+        return 0;
+    }
+    if (index < 0) {
+        return 0;
+    }
+    if (index >= length) {
+        return length - 1;
+    }
+    return index;
+}
+function pickerComponentLines(component) {
+    switch (component.kind) {
+        case "text":
+            return [`text · ${component.text}`];
+        case "list": {
+            const lines = [`list${component.title ? ` · ${component.title}` : ""}`];
+            const visible = component.items.slice(0, UI_PICKER_LIST_ITEMS_MAX);
+            for (const item of visible) {
+                const detail = item.detail ? ` — ${item.detail}` : "";
+                lines.push(`• ${item.label}${detail}`);
+            }
+            if (component.items.length > visible.length) {
+                lines.push(`... (+${component.items.length - visible.length} more items)`);
+            }
+            return lines;
+        }
+        case "key_value": {
+            const lines = [`key_value${component.title ? ` · ${component.title}` : ""}`];
+            const visible = component.rows.slice(0, UI_PICKER_KEYVALUE_ROWS_MAX);
+            for (const row of visible) {
+                lines.push(`${row.key}: ${row.value}`);
+            }
+            if (component.rows.length > visible.length) {
+                lines.push(`... (+${component.rows.length - visible.length} more rows)`);
+            }
+            return lines;
+        }
+        case "divider":
+            return ["divider"];
+        default:
+            return ["component"];
+    }
+}
+class UiActionPickerComponent {
+    #entries;
+    #theme;
+    #done;
+    #mode = "doc";
+    #docIndex = 0;
+    #actionIndex = 0;
+    constructor(opts) {
+        this.#entries = opts.entries;
+        this.#theme = opts.theme;
+        this.#done = opts.done;
+        if (opts.initialUiId && opts.initialUiId.trim().length > 0) {
+            const initialDocIndex = this.#entries.findIndex((entry) => entry.doc.ui_id === opts.initialUiId);
+            if (initialDocIndex >= 0) {
+                this.#docIndex = initialDocIndex;
+            }
+        }
+        const actions = this.#currentActions();
+        if (opts.initialActionId && opts.initialActionId.trim().length > 0) {
+            const initialActionIndex = actions.findIndex((action) => action.id === opts.initialActionId);
+            if (initialActionIndex >= 0) {
+                this.#actionIndex = initialActionIndex;
+                this.#mode = "action";
+            }
+        }
+    }
+    #currentEntry() {
+        return this.#entries[this.#docIndex];
+    }
+    #currentActions() {
+        return this.#currentEntry().actions;
+    }
+    #currentAction() {
+        const actions = this.#currentActions();
+        return actions.length > 0 ? actions[boundedIndex(this.#actionIndex, actions.length)] : null;
+    }
+    #moveDoc(delta) {
+        this.#docIndex = boundedIndex(this.#docIndex + delta, this.#entries.length);
+        this.#actionIndex = boundedIndex(this.#actionIndex, this.#currentActions().length);
+    }
+    #moveAction(delta) {
+        const actions = this.#currentActions();
+        if (actions.length === 0) {
+            this.#actionIndex = 0;
+            return;
+        }
+        this.#actionIndex = boundedIndex(this.#actionIndex + delta, actions.length);
+    }
+    #submit() {
+        const action = this.#currentAction();
+        if (!action) {
+            this.#done(null);
+            return;
+        }
+        this.#done({
+            doc: this.#currentEntry().doc,
+            action,
+        });
+    }
+    handleInput(data) {
+        if (matchesKey(data, "escape")) {
+            this.#done(null);
+            return;
+        }
+        if (matchesKey(data, "tab") || matchesKey(data, "right")) {
+            this.#mode = "action";
+            this.#actionIndex = boundedIndex(this.#actionIndex, this.#currentActions().length);
+            return;
+        }
+        if (matchesKey(data, "shift+tab") || matchesKey(data, "left")) {
+            this.#mode = "doc";
+            return;
+        }
+        if (matchesKey(data, "up")) {
+            if (this.#mode === "doc") {
+                this.#moveDoc(-1);
+            }
+            else {
+                this.#moveAction(-1);
+            }
+            return;
+        }
+        if (matchesKey(data, "down")) {
+            if (this.#mode === "doc") {
+                this.#moveDoc(1);
+            }
+            else {
+                this.#moveAction(1);
+            }
+            return;
+        }
+        if (matchesKey(data, "enter") || matchesKey(data, "return")) {
+            if (this.#mode === "doc") {
+                const actions = this.#currentActions();
+                if (actions.length <= 1) {
+                    this.#submit();
+                }
+                else {
+                    this.#mode = "action";
+                }
+                return;
+            }
+            this.#submit();
+        }
+    }
+    invalidate() {
+        // No cached state.
+    }
+    render(width) {
+        const maxWidth = Math.max(24, width - 2);
+        const lines = [];
+        lines.push(this.#theme.fg("accent", short("Programmable UI", maxWidth)));
+        lines.push(this.#theme.fg("dim", short("↑/↓ move · tab switch · enter select/submit · esc cancel", maxWidth)));
+        lines.push("");
+        lines.push(this.#theme.fg(this.#mode === "doc" ? "accent" : "dim", short(`Documents (${this.#entries.length})`, maxWidth)));
+        for (let idx = 0; idx < this.#entries.length; idx += 1) {
+            const entry = this.#entries[idx];
+            const active = idx === this.#docIndex;
+            const marker = active ? (this.#mode === "doc" ? "▶" : "▸") : " ";
+            const label = `${marker} ${entry.doc.ui_id} · ${entry.doc.title}`;
+            lines.push(this.#theme.fg(active ? "accent" : "muted", short(label, maxWidth)));
+        }
+        const selectedDoc = this.#currentEntry().doc;
+        if (selectedDoc.summary) {
+            lines.push("");
+            lines.push(this.#theme.fg("dim", short(`Summary: ${selectedDoc.summary}`, maxWidth)));
+        }
+        lines.push("");
+        lines.push(this.#theme.fg("dim", short(`Components (${selectedDoc.components.length})`, maxWidth)));
+        const visibleComponents = selectedDoc.components.slice(0, UI_PICKER_COMPONENTS_MAX);
+        for (const component of visibleComponents) {
+            const componentLines = pickerComponentLines(component);
+            for (let idx = 0; idx < componentLines.length; idx += 1) {
+                const line = componentLines[idx];
+                const prefix = idx === 0 ? "  " : "    ";
+                lines.push(this.#theme.fg("text", short(`${prefix}${line}`, maxWidth)));
+            }
+        }
+        if (selectedDoc.components.length > visibleComponents.length) {
+            lines.push(this.#theme.fg("muted", short(`  ... (+${selectedDoc.components.length - visibleComponents.length} more components)`, maxWidth)));
+        }
+        const actions = this.#currentActions();
+        lines.push("");
+        lines.push(this.#theme.fg(this.#mode === "action" ? "accent" : "dim", short(`Actions (${actions.length})`, maxWidth)));
+        for (let idx = 0; idx < actions.length; idx += 1) {
+            const action = actions[idx];
+            const active = idx === this.#actionIndex;
+            const marker = active ? (this.#mode === "action" ? "▶" : "▸") : " ";
+            const label = `${marker} ${action.id} · ${action.label}`;
+            lines.push(this.#theme.fg(active ? "accent" : "text", short(label, maxWidth)));
+        }
+        const action = this.#currentAction();
+        if (action?.description) {
+            lines.push("");
+            lines.push(this.#theme.fg("dim", short(`Ask: ${action.description}`, maxWidth)));
+        }
+        if (action?.component_id) {
+            lines.push(this.#theme.fg("dim", short(`Targets component: ${action.component_id}`, maxWidth)));
+        }
+        const commandText = action ? actionCommandText(action) : null;
+        if (commandText) {
+            lines.push("");
+            lines.push(this.#theme.fg("dim", short(`Prompt template: ${commandText}`, maxWidth)));
+        }
+        return lines;
+    }
+}
+async function pickUiActionInteractively(opts) {
+    const selected = await opts.ctx.ui.custom((_tui, theme, _keybindings, done) => new UiActionPickerComponent({
+        entries: opts.entries,
+        theme: theme,
+        done,
+        initialUiId: opts.uiId,
+        initialActionId: opts.actionId,
+    }), {
+        overlay: true,
+        overlayOptions: UI_INTERACT_OVERLAY_OPTIONS,
+    });
+    return selected ?? null;
+}
 function applyUiAction(params, state) {
+    retainPromptedRevisionKeysForActiveDocs(state);
+    retainAwaitingUiIdsForActiveDocs(state);
     const docs = activeDocs(state);
+    const awaitingCount = awaitingDocs(state, docs).length;
     switch (params.action) {
         case "status":
-            return { ok: true, action: "status", message: statusSummary(docs) };
+            return {
+                ok: true,
+                action: "status",
+                message: statusSummary(docs, awaitingCount),
+                extra: {
+                    status_profile_count: statusProfileDocCount(docs),
+                    ...statusProfileWarningsExtraForDocs(docs),
+                },
+            };
         case "snapshot": {
             const format = parseSnapshotFormat(params.snapshot_format);
             return {
                 ok: true,
                 action: "snapshot",
                 message: snapshotText(docs, format),
-                extra: { snapshot_format: format },
+                extra: {
+                    snapshot_format: format,
+                    status_profile_count: statusProfileDocCount(docs),
+                    ...statusProfileWarningsExtraForDocs(docs),
+                },
             };
         }
         case "set":
@@ -142,11 +704,20 @@ function applyUiAction(params, state) {
             }
             const preferred = preferredDocForState(state, parsed.doc);
             state.docsById.set(parsed.doc.ui_id, preferred);
+            if (runnableActions(preferred).length > 0) {
+                state.awaitingUiIds.add(parsed.doc.ui_id);
+            }
+            else {
+                state.awaitingUiIds.delete(parsed.doc.ui_id);
+            }
+            retainPromptedRevisionKeysForActiveDocs(state);
+            retainAwaitingUiIdsForActiveDocs(state);
             return {
                 ok: true,
                 action: params.action,
                 message: `UI doc set: ${parsed.doc.ui_id}`,
-                extra: { ui_id: parsed.doc.ui_id },
+                extra: { ui_id: parsed.doc.ui_id, ...statusProfileWarningsExtraForDoc(preferred) },
+                changedUiIds: [parsed.doc.ui_id],
             };
         }
         case "replace": {
@@ -155,14 +726,24 @@ function applyUiAction(params, state) {
                 return { ok: false, action: "replace", message: parsed.error };
             }
             state.docsById.clear();
+            state.awaitingUiIds.clear();
             for (const doc of parsed.docs) {
                 state.docsById.set(doc.ui_id, doc);
+                if (runnableActions(doc).length > 0) {
+                    state.awaitingUiIds.add(doc.ui_id);
+                }
             }
+            retainPromptedRevisionKeysForActiveDocs(state);
+            retainAwaitingUiIdsForActiveDocs(state);
             return {
                 ok: true,
                 action: "replace",
                 message: `UI docs replaced (${parsed.docs.length}).`,
-                extra: { doc_count: parsed.docs.length },
+                extra: {
+                    doc_count: parsed.docs.length,
+                    ...statusProfileWarningsExtraForDocs(parsed.docs),
+                },
+                changedUiIds: parsed.docs.map((doc) => doc.ui_id),
             };
         }
         case "remove": {
@@ -173,10 +754,19 @@ function applyUiAction(params, state) {
             if (!state.docsById.delete(uiId)) {
                 return { ok: false, action: "remove", message: `UI doc not found: ${uiId}` };
             }
+            if (state.pendingPrompt?.uiId === uiId) {
+                state.pendingPrompt = null;
+            }
+            state.awaitingUiIds.delete(uiId);
+            retainPromptedRevisionKeysForActiveDocs(state);
+            retainAwaitingUiIdsForActiveDocs(state);
             return { ok: true, action: "remove", message: `UI doc removed: ${uiId}` };
         }
         case "clear":
             state.docsById.clear();
+            state.pendingPrompt = null;
+            state.promptedRevisionKeys.clear();
+            state.awaitingUiIds.clear();
             return { ok: true, action: "clear", message: "UI docs cleared." };
     }
 }
@@ -195,49 +785,83 @@ function buildToolResult(opts) {
     };
     return result;
 }
-function renderDocPreview(theme, doc) {
+function renderDocPreview(theme, doc, opts) {
     const lines = [];
-    lines.push(`${theme.fg("accent", doc.title)} ${theme.fg("muted", `[${doc.ui_id}]`)}`);
+    const headerParts = [theme.fg("accent", doc.title), theme.fg("muted", `[${doc.ui_id}]`)];
+    if (opts.awaitingResponse) {
+        headerParts.push(theme.fg("accent", "awaiting-response"));
+    }
+    lines.push(headerParts.join(" "));
     if (doc.summary) {
         lines.push(theme.fg("muted", short(doc.summary, 80)));
     }
+    if (opts.awaitingCount > 0) {
+        lines.push(theme.fg("accent", `Awaiting user response for ${opts.awaitingCount} UI doc(s).`));
+    }
     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)}`);
+            const previewLines = componentPreviewLines(component);
+            for (let idx = 0; idx < previewLines.length; idx += 1) {
+                const line = previewLines[idx];
+                lines.push(`${idx === 0 ? "  " : "    "}${line}`);
+            }
         }
     }
-    if (doc.actions.length > 0) {
+    const interactiveActions = runnableActions(doc);
+    if (interactiveActions.length > 0) {
         lines.push(theme.fg("muted", "Actions:"));
-        const visibleActions = doc.actions.slice(0, UI_WIDGET_ACTIONS_MAX);
+        const visibleActions = interactiveActions.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)`);
+        if (interactiveActions.length > visibleActions.length) {
+            lines.push(`  ... (+${interactiveActions.length - visibleActions.length} more actions)`);
+        }
+        if (opts.awaitingResponse) {
+            lines.push(theme.fg("accent", "Awaiting your response. Select an action to continue."));
         }
-        lines.push(theme.fg("dim", "Actions are handled through channel-native callbacks."));
+        lines.push(theme.fg("dim", `Press ${UI_INTERACT_SHORTCUT} to compose and submit a prompt from actions.`));
     }
     else {
         lines.push(theme.fg("dim", "No interactive actions."));
     }
     return lines;
 }
-function componentPreview(component) {
+function componentPreviewLines(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)`;
+            return [`text · ${short(component.text, 80)}`];
+        case "list": {
+            const lines = [`list · ${component.title ?? kind} · ${component.items.length} item(s)`];
+            const visible = component.items.slice(0, UI_WIDGET_COMPONENT_DETAILS_MAX);
+            for (const item of visible) {
+                const detail = item.detail ? ` — ${short(item.detail, 28)}` : "";
+                lines.push(`• ${short(item.label, 72)}${detail}`);
+            }
+            if (component.items.length > visible.length) {
+                lines.push(`... (+${component.items.length - visible.length} more items)`);
+            }
+            return lines;
+        }
+        case "key_value": {
+            const lines = [`key_value · ${component.title ?? kind} · ${component.rows.length} row(s)`];
+            const visible = component.rows.slice(0, UI_WIDGET_COMPONENT_DETAILS_MAX);
+            for (const row of visible) {
+                lines.push(`${short(row.key, 20)}: ${short(row.value, 52)}`);
+            }
+            if (component.rows.length > visible.length) {
+                lines.push(`... (+${component.rows.length - visible.length} more rows)`);
+            }
+            return lines;
+        }
         case "divider":
-            return "divider";
+            return ["divider"];
     }
-    return kind;
+    return [kind];
 }
 function refreshUi(ctx) {
     const key = sessionKey(ctx);
@@ -245,27 +869,137 @@ function refreshUi(ctx) {
     if (!ctx.hasUI) {
         return;
     }
+    retainAwaitingUiIdsForActiveDocs(state);
     const docs = activeDocs(state);
     if (docs.length === 0) {
         ctx.ui.setStatus("mu-ui", undefined);
         ctx.ui.setWidget("mu-ui", undefined);
         return;
     }
+    const awaiting = awaitingDocs(state, docs);
     const labels = docs.map((doc) => doc.ui_id).join(", ");
+    const readiness = state.interactionDepth > 0
+        ? ctx.ui.theme.fg("accent", "prompting")
+        : awaiting.length > 0
+            ? ctx.ui.theme.fg("accent", `awaiting ${awaiting.length}`)
+            : ctx.ui.theme.fg("dim", "ready");
     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", "·"),
+        readiness,
+        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" });
+    if (state.interactionDepth > 0) {
+        ctx.ui.setWidget("mu-ui", undefined);
+        return;
+    }
+    const primaryDoc = awaiting[0] ?? docs[0];
+    ctx.ui.setWidget("mu-ui", renderDocPreview(ctx.ui.theme, primaryDoc, {
+        awaitingResponse: state.awaitingUiIds.has(primaryDoc.ui_id),
+        awaitingCount: awaiting.length,
+    }), { placement: "belowEditor" });
 }
 export function uiExtension(pi) {
+    const commandUsage = "/mu ui status|snapshot [compact|multiline]|interact [ui_id [action_id]]";
+    const usage = `Usage: ${commandUsage}`;
+    const runUiActionFromDoc = async (ctx, state, uiId, actionId) => withUiInteraction(ctx, state, async () => {
+        const docs = activeDocs(state, UI_DISPLAY_DOCS_MAX);
+        if (docs.length === 0) {
+            ctx.ui.notify("No UI docs are currently available.", "info");
+            return;
+        }
+        const entries = docs
+            .map((doc) => ({ doc, actions: runnableActions(doc) }))
+            .filter((entry) => entry.actions.length > 0);
+        if (entries.length === 0) {
+            ctx.ui.notify("No runnable UI actions are currently available.", "error");
+            return;
+        }
+        let selectedDoc = null;
+        let selectedAction = null;
+        const normalizedUiId = uiId?.trim() ?? "";
+        const normalizedActionId = actionId?.trim() ?? "";
+        if (normalizedUiId.length > 0 && normalizedActionId.length > 0) {
+            const entry = entries.find((candidate) => candidate.doc.ui_id === normalizedUiId) ?? null;
+            if (!entry) {
+                ctx.ui.notify(`UI doc not found: ${normalizedUiId}`, "error");
+                return;
+            }
+            const action = entry.actions.find((candidate) => candidate.id === normalizedActionId) ?? null;
+            if (!action) {
+                ctx.ui.notify(`Action not found: ${normalizedActionId} in ${normalizedUiId}`, "error");
+                return;
+            }
+            selectedDoc = entry.doc;
+            selectedAction = action;
+        }
+        else {
+            const picked = await pickUiActionInteractively({
+                ctx,
+                entries,
+                uiId: normalizedUiId.length > 0 ? normalizedUiId : undefined,
+                actionId: normalizedActionId.length > 0 ? normalizedActionId : undefined,
+            });
+            if (!picked) {
+                ctx.ui.notify("UI interaction cancelled.", "info");
+                return;
+            }
+            selectedDoc = picked.doc;
+            selectedAction = picked.action;
+        }
+        if (!selectedDoc || !selectedAction) {
+            ctx.ui.notify("No UI action was selected.", "error");
+            return;
+        }
+        const commandText = actionCommandText(selectedAction);
+        if (!commandText) {
+            ctx.ui.notify(`Action ${selectedAction.id} is missing metadata.command_text.`, "error");
+            return;
+        }
+        const templateKeys = extractTemplateKeys(commandText);
+        const templateValues = await collectTemplateValues({
+            ctx,
+            action: selectedAction,
+            templateKeys,
+        });
+        if (!templateValues) {
+            ctx.ui.notify("UI interaction cancelled.", "info");
+            return;
+        }
+        const composed = composePromptFromAction({
+            commandText,
+            templateValues,
+        });
+        const edited = await ctx.ui.editor(`Review prompt (${selectedDoc.ui_id}/${selectedAction.id})`, composed);
+        if (edited === undefined) {
+            ctx.ui.notify("UI submit cancelled.", "info");
+            return;
+        }
+        const finalPrompt = edited.trim();
+        if (finalPrompt.length === 0) {
+            ctx.ui.notify("Cannot submit an empty prompt.", "error");
+            return;
+        }
+        const confirmed = await ctx.ui.confirm("Submit UI prompt", short(finalPrompt, UI_PROMPT_PREVIEW_MAX));
+        if (!confirmed) {
+            ctx.ui.notify("UI submit cancelled.", "info");
+            return;
+        }
+        pi.sendUserMessage(finalPrompt);
+        state.awaitingUiIds.delete(selectedDoc.ui_id);
+        if (state.pendingPrompt?.uiId === selectedDoc.ui_id) {
+            state.pendingPrompt = null;
+        }
+        retainAwaitingUiIdsForActiveDocs(state);
+        ctx.ui.notify(`Submitted prompt from ${selectedDoc.ui_id}/${selectedAction.id}.`, "info");
+    });
     registerMuSubcommand(pi, {
         subcommand: "ui",
-        summary: "Inspect interactive UI docs",
-        usage: "/mu ui status|snapshot [compact|multiline]",
+        summary: "Inspect and manage interactive UI docs",
+        usage: commandUsage,
         handler: async (args, ctx) => {
             const tokens = args
                 .trim()
@@ -285,7 +1019,27 @@ export function uiExtension(pi) {
                 ctx.ui.notify(result.message, result.ok ? "info" : "error");
                 return;
             }
-            ctx.ui.notify("Usage: /mu ui status|snapshot [compact|multiline]", "info");
+            if (subcommand === "interact") {
+                if (tokens.length > 3) {
+                    ctx.ui.notify(usage, "info");
+                    return;
+                }
+                const uiId = tokens[1];
+                const actionId = tokens[2];
+                await runUiActionFromDoc(ctx, state, uiId, actionId);
+                refreshUi(ctx);
+                return;
+            }
+            ctx.ui.notify(usage, "info");
+        },
+    });
+    pi.registerShortcut(UI_INTERACT_SHORTCUT, {
+        description: "Interact with programmable UI docs and submit prompt",
+        handler: async (ctx) => {
+            const key = sessionKey(ctx);
+            const state = ensureState(key);
+            await runUiActionFromDoc(ctx, state);
+            refreshUi(ctx);
         },
     });
     pi.registerTool({
@@ -312,6 +1066,9 @@ export function uiExtension(pi) {
             const state = ensureState(key);
             const params = paramsRaw;
             const result = applyUiAction(params, state);
+            if (ctx.hasUI && result.ok && result.changedUiIds && result.changedUiIds.length > 0) {
+                armAutoPromptForUiDocs(state, result.changedUiIds);
+            }
             refreshUi(ctx);
             return buildToolResult({ state, ...result });
         },
@@ -322,6 +1079,21 @@ export function uiExtension(pi) {
     pi.on("session_switch", (_event, ctx) => {
         refreshUi(ctx);
     });
+    pi.on("agent_end", async (_event, ctx) => {
+        if (!ctx.hasUI) {
+            return;
+        }
+        const key = sessionKey(ctx);
+        const state = ensureState(key);
+        const pending = state.pendingPrompt;
+        if (!pending) {
+            return;
+        }
+        state.pendingPrompt = null;
+        ctx.ui.notify(`Agent requested input via ${pending.uiId}. Submit now or press ${UI_INTERACT_SHORTCUT} later.`, "info");
+        await runUiActionFromDoc(ctx, state, pending.uiId, pending.actionId);
+        refreshUi(ctx);
+    });
     pi.on("session_shutdown", (_event, ctx) => {
         const key = sessionKey(ctx);
         touchState(key);