@femtomc/mu-server 26.2.106 → 26.2.108

package/README.md

@@ -4,9 +4,9 @@ HTTP API server for mu control-plane infrastructure.
 Powers `mu serve`, messaging frontend transport routes, and
 control-plane/session coordination endpoints.
 
-> Scope note: server-routed business query/mutation gateway endpoints have
-> been removed. Business reads/writes are CLI-first, while long-lived runtime
-> coordination (runs/heartbeats/cron) stays server-owned.
+> Scope note: server-routed endpoints focus on runtime coordination only.
+> Business reads/writes are CLI-first, while long-lived runtime coordination
+> (runs/heartbeats/cron) stays server-owned.
 
 ## Installation
 
@@ -44,7 +44,7 @@ Use `mu store paths --pretty` to resolve `<store>` for the active repo/workspace
 
 ### Health Check
 
-- `GET /healthz` or `GET /health` - Returns 200 OK
+- `GET /healthz` - Returns 200 OK
 
 ### Status
 
@@ -194,11 +194,7 @@ Operational fallbacks:
 - `telegram_reply_to_message_id` metadata anchors replies when parseable.
 - Missing Slack/Telegram bot tokens surface capability reason codes (`*_bot_token_missing`) and retry behavior.
 
-Server channel renderers consume canonical `hud_docs` metadata (`HudDoc`) for Slack/Telegram HUD
-rendering + actions. Optional HUD presentation hints (`title_style`, `snapshot_style`, chip/item styles)
-and metadata presets (`metadata.style_preset`) may be used by richer renderers and safely ignored by
-plain-text channels. New features should extend the shared HUD contract path instead of bespoke
-channel-specific HUD payload formats.
+Server channel renderers consume canonical `ui_docs` metadata (`UiDoc`) for Slack/Telegram/Discord/Neovim delivery. Interactive actions use callback tokens (`mu-ui:*`) with deterministic text fallbacks when tokens cannot be issued or rendered.
 
 ## Running the Server
 
@@ -256,6 +252,6 @@ The server uses:
 - Filesystem-backed JSONL event storage (FsJsonlStore)
 - Bun's built-in HTTP server
 - Control-plane adapter/webhook transport + session coordination routes
-- Generation-supervised control-plane hot reload lifecycle (see `docs/adr-0001-control-plane-hot-reload.md`)
+- Generation-supervised control-plane hot reload lifecycle
 
 Control-plane/coordination data is persisted under `<store>/` (for example `<store>/events.jsonl` and `<store>/control-plane/*`). Use `mu store paths` to resolve `<store>` for your repo.

package/dist/api/control_plane.js

@@ -1,4 +1,5 @@
 import { CONTROL_PLANE_CHANNEL_ADAPTER_SPECS, ingressModeForValue, summarizeInboundAttachmentPolicy, } from "@femtomc/mu-control-plane";
+import { UI_ACTIONS_UNSUPPORTED_REASON, UI_COMPONENT_SUPPORT } from "../control_plane.js";
 import { configRoutes } from "./config.js";
 import { eventRoutes } from "./events.js";
 import { identityRoutes } from "./identities.js";
@@ -92,9 +93,71 @@ function mediaInboundAttachmentCapability(config, channel) {
         reason: hasToken ? null : "telegram_bot_token_missing",
     };
 }
+const TEXT_ONLY_UI_COMPONENT_SUPPORT = {
+    text: true,
+    list: false,
+    key_value: false,
+    divider: false,
+};
+const STATUS_PROFILE_ACTIONS_FALLBACK_REASON = "status_profile_actions_degrade_to_text";
+const CHANNEL_UI_CAPABILITIES = {
+    slack: {
+        supported: true,
+        reason: null,
+        components: UI_COMPONENT_SUPPORT,
+        actions: {
+            supported: true,
+            reason: STATUS_PROFILE_ACTIONS_FALLBACK_REASON,
+        },
+    },
+    discord: {
+        supported: true,
+        reason: null,
+        components: TEXT_ONLY_UI_COMPONENT_SUPPORT,
+        actions: {
+            supported: true,
+            reason: STATUS_PROFILE_ACTIONS_FALLBACK_REASON,
+        },
+    },
+    telegram: {
+        supported: true,
+        reason: null,
+        components: TEXT_ONLY_UI_COMPONENT_SUPPORT,
+        actions: {
+            supported: true,
+            reason: STATUS_PROFILE_ACTIONS_FALLBACK_REASON,
+        },
+    },
+    neovim: {
+        supported: true,
+        reason: null,
+        components: TEXT_ONLY_UI_COMPONENT_SUPPORT,
+        actions: {
+            supported: true,
+            reason: STATUS_PROFILE_ACTIONS_FALLBACK_REASON,
+        },
+    },
+    terminal: {
+        supported: true,
+        reason: null,
+        components: TEXT_ONLY_UI_COMPONENT_SUPPORT,
+        actions: {
+            supported: false,
+            reason: UI_ACTIONS_UNSUPPORTED_REASON,
+        },
+    },
+};
+function uiCapabilityForChannel(channel) {
+    return CHANNEL_UI_CAPABILITIES[channel] ?? {
+        supported: true,
+        reason: null,
+        components: TEXT_ONLY_UI_COMPONENT_SUPPORT,
+        actions: { supported: false, reason: UI_ACTIONS_UNSUPPORTED_REASON },
+    };
+}
 export async function controlPlaneRoutes(request, url, deps, headers) {
     const path = url.pathname;
-    if (path === "/api/control-plane" || path === "/api/control-plane/status") {
+    if (path === "/api/control-plane/status") {
         if (request.method !== "GET") {
             return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
         }
@@ -164,6 +227,7 @@ export async function controlPlaneRoutes(request, url, deps, headers) {
                 outbound_delivery: mediaOutboundCapability(config, spec.channel),
                 inbound_attachment_download: mediaInboundAttachmentCapability(config, spec.channel),
             },
+            ui: uiCapabilityForChannel(spec.channel),
         }));
         return Response.json({
             ok: true,

package/dist/control_plane.d.ts

@@ -1,5 +1,6 @@
 import type { MessagingOperatorBackend, MessagingOperatorRuntime } from "@femtomc/mu-agent";
-import { type GenerationTelemetryRecorder, type OutboxDeliveryHandlerResult, type OutboxRecord } from "@femtomc/mu-control-plane";
+import { type UiDoc, type UiEvent } from "@femtomc/mu-core";
+import { type GenerationTelemetryRecorder, type OutboxDeliveryHandlerResult, type OutboxRecord, UiCallbackTokenStore } from "@femtomc/mu-control-plane";
 import { type ControlPlaneConfig, type ControlPlaneGenerationContext, type ControlPlaneHandle, type ControlPlaneSessionLifecycle, type TelegramGenerationSwapHooks, type WakeDeliveryObserver } from "./control_plane_contract.js";
 import { detectAdapters } from "./control_plane_adapter_registry.js";
 export type { ActiveAdapter, ControlPlaneConfig, ControlPlaneGenerationContext, ControlPlaneHandle, ControlPlaneSessionLifecycle, ControlPlaneSessionMutationAction, ControlPlaneSessionMutationResult, NotifyOperatorsOpts, NotifyOperatorsResult, TelegramGenerationReloadResult, TelegramGenerationRollbackTrigger, TelegramGenerationSwapHooks, WakeDeliveryEvent, WakeDeliveryObserver, WakeNotifyContext, WakeNotifyDecision, } from "./control_plane_contract.js";
@@ -52,8 +53,22 @@ export declare function buildTelegramSendMessagePayload(opts: {
     richFormatting: boolean;
 }): TelegramSendMessagePayload;
 export declare function splitTelegramMessageText(text: string, maxLen?: number): string[];
+export declare const UI_COMPONENT_SUPPORT: {
+    readonly text: true;
+    readonly list: true;
+    readonly key_value: true;
+    readonly divider: true;
+};
+export declare const UI_ACTIONS_UNSUPPORTED_REASON = "ui_actions_not_implemented";
+export declare function uiDocTextLines(doc: UiDoc, opts?: {
+    includeActions?: boolean;
+}): string[];
+export declare function uiDocsTextFallback(uiDocs: readonly UiDoc[]): string;
 export declare function splitSlackMessageText(text: string, maxLen?: number): string[];
-type TelegramCallbackDataEncoder = (commandText: string) => Promise<string>;
+type TelegramCallbackDataEncoder = (commandText: string, opts: {
+    record: OutboxRecord;
+    uiEvent?: UiEvent;
+}) => Promise<string>;
 export declare function deliverTelegramOutboxRecord(opts: {
     botToken: string;
     record: OutboxRecord;
@@ -62,6 +77,9 @@ export declare function deliverTelegramOutboxRecord(opts: {
 export declare function deliverSlackOutboxRecord(opts: {
     botToken: string;
     record: OutboxRecord;
+    uiCallbackTokenStore?: UiCallbackTokenStore;
+    nowMs?: () => number;
+    fetchImpl?: typeof fetch;
 }): Promise<OutboxDeliveryHandlerResult>;
 export type BootstrapControlPlaneOpts = {
     repoRoot: string;

package/dist/control_plane.js

@@ -1,5 +1,5 @@
-import { applyHudStylePreset, normalizeHudDocs } from "@femtomc/mu-core";
-import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneRuntime, buildSlackHudActionId, getControlPlanePaths, TelegramControlPlaneAdapterSpec, } from "@femtomc/mu-control-plane";
+import { normalizeUiDocs, resolveUiStatusProfileName, } from "@femtomc/mu-core";
+import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneRuntime, buildSanitizedUiEventForAction, buildSlackUiActionId, getControlPlanePaths, issueUiDocActionPayloads, TelegramControlPlaneAdapterSpec, uiActionPayloadContextFromOutboxRecord, uiDocActionPayloadKey, UiCallbackTokenStore, } from "@femtomc/mu-control-plane";
 import { DEFAULT_MU_CONFIG } from "./config.js";
 import { buildMessagingOperatorRuntime, createOutboxDrainLoop } from "./control_plane_bootstrap_helpers.js";
 import { buildWakeOutboundEnvelope, resolveWakeFanoutCapability, wakeDeliveryMetadataFromOutboxRecord, wakeDispatchReasonCode, wakeFanoutDedupeKey, } from "./control_plane_wake_delivery.js";
@@ -146,11 +146,17 @@ const SLACK_BLOCK_TEXT_MAX_LEN = 3_000;
 const SLACK_BLOCKS_MAX = 50;
 const SLACK_ACTIONS_MAX_PER_BLOCK = 5;
 const SLACK_ACTIONS_MAX_TOTAL = 20;
-const SLACK_DOCS_MAX = 3;
-const SLACK_SECTION_LINE_MAX = 8;
-function hudDocsForPresentation(input, maxDocs) {
-    return normalizeHudDocs(input, { maxDocs }).map((doc) => applyHudStylePreset(doc) ?? doc);
-}
+const SLACK_ACTION_VALUE_MAX_CHARS = 2_000;
+const SLACK_UI_EVENT_ACTION_ID = buildSlackUiActionId("ui_event");
+const UI_DOCS_MAX = 3;
+const UI_CALLBACK_TOKEN_TTL_MS = 15 * 60_000;
+export const UI_COMPONENT_SUPPORT = {
+    text: true,
+    list: true,
+    key_value: true,
+    divider: true,
+};
+export const UI_ACTIONS_UNSUPPORTED_REASON = "ui_actions_not_implemented";
 function truncateSlackText(text, maxLen = SLACK_BLOCK_TEXT_MAX_LEN) {
     if (text.length <= maxLen) {
         return text;
@@ -160,113 +166,146 @@ function truncateSlackText(text, maxLen = SLACK_BLOCK_TEXT_MAX_LEN) {
     }
     return `${text.slice(0, maxLen - 1)}…`;
 }
-function hudTonePrefix(tone) {
-    switch (tone) {
-        case "success":
-            return "✅";
-        case "warning":
-            return "⚠️";
-        case "error":
-            return "⛔";
-        case "accent":
-            return "🔹";
-        case "muted":
-            return "▫️";
-        case "dim":
-            return "·";
-        case "info":
-        default:
-            return "ℹ️";
-    }
-}
-function applySlackHudTextStyle(text, style, opts = {}) {
-    const weight = style?.weight ?? opts.defaultWeight;
-    const italic = style?.italic ?? opts.defaultItalic ?? false;
-    const code = style?.code ?? opts.defaultCode ?? false;
-    let out = text;
-    if (code) {
-        out = `\`${out}\``;
-    }
-    if (italic) {
-        out = `_${out}_`;
-    }
-    if (weight === "strong") {
-        out = `*${out}*`;
-    }
-    return out;
-}
-function stripSlackMrkdwn(text) {
-    return text.replace(/[*_`~]/g, "");
-}
-function hudDocSectionLines(doc) {
+function uiDocComponentLines(doc) {
     const lines = [];
-    const chipsLine = doc.chips
-        .slice(0, 8)
-        .map((chip) => {
-        const label = applySlackHudTextStyle(chip.label, chip.style, { defaultWeight: "strong" });
-        return `${hudTonePrefix(chip.tone)} ${label}`;
-    })
-        .join(" · ");
-    if (chipsLine.length > 0) {
-        lines.push(chipsLine);
-    }
-    for (const section of doc.sections) {
-        switch (section.kind) {
-            case "kv": {
-                const title = applySlackHudTextStyle(section.title ?? "Details", section.title_style, { defaultWeight: "strong" });
-                const items = section.items.slice(0, SLACK_SECTION_LINE_MAX).map((item) => {
-                    const value = applySlackHudTextStyle(item.value, item.value_style);
-                    return `• *${item.label}:* ${value}`;
-                });
-                if (items.length > 0) {
-                    lines.push([title, ...items].join("\n"));
-                }
+    const components = [...doc.components].sort((a, b) => a.id.localeCompare(b.id));
+    for (const component of components) {
+        switch (component.kind) {
+            case "text": {
+                lines.push(component.text);
                 break;
             }
-            case "checklist": {
-                const title = applySlackHudTextStyle(section.title ?? "Checklist", section.title_style, { defaultWeight: "strong" });
-                const items = section.items
-                    .slice(0, SLACK_SECTION_LINE_MAX)
-                    .map((item) => `${item.done ? "✅" : "⬜"} ${applySlackHudTextStyle(item.label, item.style)}`);
-                if (items.length > 0) {
-                    lines.push([title, ...items].join("\n"));
+            case "list": {
+                if (component.title) {
+                    lines.push(component.title);
+                }
+                for (const item of component.items) {
+                    lines.push(`• ${item.label}${item.detail ? ` · ${item.detail}` : ""}`);
                 }
                 break;
             }
-            case "activity": {
-                const title = applySlackHudTextStyle(section.title ?? "Activity", section.title_style, { defaultWeight: "strong" });
-                const items = section.lines.slice(0, SLACK_SECTION_LINE_MAX).map((line) => `• ${line}`);
-                if (items.length > 0) {
-                    lines.push([title, ...items].join("\n"));
+            case "key_value": {
+                if (component.title) {
+                    lines.push(component.title);
+                }
+                for (const row of component.rows) {
+                    lines.push(`• ${row.key}: ${row.value}`);
                 }
                 break;
             }
-            case "text": {
-                const title = section.title
-                    ? `${applySlackHudTextStyle(section.title, section.title_style, { defaultWeight: "strong" })}\n`
-                    : "";
-                const text = applySlackHudTextStyle(section.text, section.style);
-                lines.push(`${title}${text}`);
+            case "divider": {
+                lines.push("────────");
                 break;
             }
         }
     }
-    if (lines.length === 0) {
-        const snapshot = applySlackHudTextStyle(doc.snapshot_compact, doc.snapshot_style);
-        lines.push(`${applySlackHudTextStyle("Snapshot", undefined, { defaultWeight: "strong" })}\n${snapshot}`);
+    return lines;
+}
+function uiDocActionLines(doc) {
+    const actions = [...doc.actions].sort((a, b) => a.id.localeCompare(b.id));
+    return actions.map((action) => {
+        const parts = [`• ${action.label}`];
+        if (action.description) {
+            parts.push(action.description);
+        }
+        parts.push(`(id=${action.id})`);
+        return parts.join(" ");
+    });
+}
+export function uiDocTextLines(doc, opts = {}) {
+    const lines = [`UI · ${doc.title}`];
+    if (doc.summary) {
+        lines.push(doc.summary);
+    }
+    const componentLines = uiDocComponentLines(doc);
+    if (componentLines.length > 0) {
+        lines.push(...componentLines);
+    }
+    if (opts.includeActions !== false) {
+        const actionLines = uiDocActionLines(doc);
+        if (actionLines.length > 0) {
+            lines.push("Actions:");
+            lines.push(...actionLines);
+        }
     }
     return lines;
 }
-function hudActionButtons(doc) {
-    return doc.actions.slice(0, SLACK_ACTIONS_MAX_TOTAL).map((action) => ({
-        type: "button",
-        text: {
-            type: "plain_text",
-            text: truncateSlackText(action.label, 75),
-        },
-        value: truncateSlackText(action.command_text, 2_000),
-        action_id: buildSlackHudActionId(action.id),
-    }));
+export function uiDocsTextFallback(uiDocs) {
+    if (uiDocs.length === 0) {
+        return "";
+    }
+    const sections = uiDocs.map((doc) => uiDocTextLines(doc).join("\n"));
+    return sections.join("\n\n");
+}
+function appendUiDocText(body, uiDocs) {
+    const fallback = uiDocsTextFallback(uiDocs);
+    if (!fallback) {
+        return body;
+    }
+    const trimmed = body.trim();
+    if (trimmed.length === 0) {
+        return fallback;
+    }
+    return `${trimmed}\n\n${fallback}`;
+}
+function uiDocActionTextLine(action, opts = {}) {
+    const parts = [`• ${action.label}`];
+    if (action.description) {
+        parts.push(action.description);
+    }
+    parts.push(`(id=${action.id}${opts.suffix ? `; ${opts.suffix}` : ""})`);
+    return parts.join(" ");
+}
+function statusProfileVariant(doc) {
+    const profile = doc.metadata.profile;
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+        return "status";
+    }
+    const rawVariant = typeof profile.variant === "string"
+        ? profile.variant.trim().toLowerCase()
+        : "";
+    return rawVariant.length > 0 ? rawVariant : "status";
+}
+function isStatusProfileStatusVariant(doc) {
+    return resolveUiStatusProfileName(doc) !== null && statusProfileVariant(doc) === "status";
+}
+function uiDocDeterministicActionFallbackLine(action) {
+    const commandText = commandTextForUiDocAction(action);
+    if (commandText) {
+        return `• ${action.label}: ${commandText}`;
+    }
+    return `• ${action.label}: interactive unavailable (missing command_text)`;
+}
+function uiDocActionButtons(doc, actionPayloadsByKey) {
+    const buttons = [];
+    const fallbackLines = [];
+    const statusProfile = isStatusProfileStatusVariant(doc);
+    const actions = [...doc.actions].sort((a, b) => a.id.localeCompare(b.id)).slice(0, SLACK_ACTIONS_MAX_TOTAL);
+    for (const action of actions) {
+        if (statusProfile) {
+            fallbackLines.push(uiDocDeterministicActionFallbackLine(action));
+            continue;
+        }
+        const payload = actionPayloadsByKey.get(uiDocActionPayloadKey(doc.ui_id, action.id));
+        if (!payload) {
+            fallbackLines.push(uiDocActionTextLine(action, { suffix: "interactive unavailable" }));
+            continue;
+        }
+        if (payload.length > SLACK_ACTION_VALUE_MAX_CHARS) {
+            fallbackLines.push(uiDocActionTextLine(action, { suffix: "interactive payload too large" }));
+            continue;
+        }
+        buttons.push({
+            type: "button",
+            text: {
+                type: "plain_text",
+                text: truncateSlackText(action.label, 75),
+            },
+            value: payload,
+            action_id: SLACK_UI_EVENT_ACTION_ID,
+        });
+    }
+    return { buttons, fallbackLines };
 }
 export function splitSlackMessageText(text, maxLen = SLACK_MESSAGE_MAX_LEN) {
     if (text.length <= maxLen) {
@@ -288,26 +327,27 @@ export function splitSlackMessageText(text, maxLen = SLACK_MESSAGE_MAX_LEN) {
     }
     return chunks;
 }
-function slackBlocksForOutboxRecord(record, body) {
-    const hudDocs = hudDocsForPresentation(record.envelope.metadata?.hud_docs, SLACK_DOCS_MAX);
-    if (hudDocs.length === 0) {
+function slackBlocksForOutboxRecord(body, uiDocs, opts = {}) {
+    if (uiDocs.length === 0) {
         return undefined;
     }
+    const uiDocActionPayloadsByKey = opts.uiDocActionPayloadsByKey ?? new Map();
     const blocks = [];
+    const headerText = body.trim().length > 0 ? body : "Update";
     blocks.push({
         type: "section",
-        text: { type: "mrkdwn", text: truncateSlackText(body) },
+        text: { type: "mrkdwn", text: truncateSlackText(headerText) },
     });
-    for (const doc of hudDocs) {
+    for (const doc of uiDocs) {
         if (blocks.length >= SLACK_BLOCKS_MAX) {
             break;
         }
-        const styledTitle = applySlackHudTextStyle(doc.title, doc.title_style, { defaultWeight: "strong" });
+        const lines = uiDocTextLines(doc, { includeActions: false });
         blocks.push({
             type: "context",
-            elements: [{ type: "mrkdwn", text: truncateSlackText(`*HUD* · ${styledTitle}`) }],
+            elements: [{ type: "mrkdwn", text: truncateSlackText(lines[0]) }],
         });
-        for (const line of hudDocSectionLines(doc)) {
+        for (const line of lines.slice(1)) {
             if (blocks.length >= SLACK_BLOCKS_MAX) {
                 break;
             }
@@ -316,27 +356,35 @@ function slackBlocksForOutboxRecord(record, body) {
                 text: { type: "mrkdwn", text: truncateSlackText(line) },
             });
         }
-        const buttons = hudActionButtons(doc);
-        for (let idx = 0; idx < buttons.length; idx += SLACK_ACTIONS_MAX_PER_BLOCK) {
+        const actionRender = uiDocActionButtons(doc, uiDocActionPayloadsByKey);
+        for (let idx = 0; idx < actionRender.buttons.length; idx += SLACK_ACTIONS_MAX_PER_BLOCK) {
             if (blocks.length >= SLACK_BLOCKS_MAX) {
                 break;
             }
             blocks.push({
                 type: "actions",
-                elements: buttons.slice(idx, idx + SLACK_ACTIONS_MAX_PER_BLOCK),
+                elements: actionRender.buttons.slice(idx, idx + SLACK_ACTIONS_MAX_PER_BLOCK),
+            });
+        }
+        if (actionRender.fallbackLines.length > 0 && blocks.length < SLACK_BLOCKS_MAX) {
+            blocks.push({
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: truncateSlackText(`Actions:\n${actionRender.fallbackLines.join("\n")}`),
+                },
             });
         }
     }
     return blocks.slice(0, SLACK_BLOCKS_MAX);
 }
 function slackThreadTsFromMetadata(metadata) {
-    const candidates = [metadata?.slack_thread_ts, metadata?.slack_message_ts, metadata?.thread_ts];
-    for (const value of candidates) {
-        if (typeof value === "string" && value.trim().length > 0) {
-            return value.trim();
-        }
+    const value = metadata?.slack_thread_ts;
+    if (typeof value !== "string") {
+        return undefined;
     }
-    return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
 }
 function slackStatusMessageTsFromMetadata(metadata) {
     const value = metadata?.slack_status_message_ts;
@@ -349,60 +397,96 @@ function slackStatusMessageTsFromMetadata(metadata) {
 const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
 const TELEGRAM_ACTIONS_MAX_TOTAL = 20;
 const TELEGRAM_ACTIONS_PER_ROW = 3;
-const TELEGRAM_DOCS_MAX = 2;
 function utf8ByteLength(value) {
     return new TextEncoder().encode(value).length;
 }
-function telegramTextForOutboxRecord(record, body) {
-    const hudDocs = hudDocsForPresentation(record.envelope.metadata?.hud_docs, TELEGRAM_DOCS_MAX);
-    if (hudDocs.length === 0) {
-        return body;
-    }
+function telegramTextForOutboxRecord(body, uiDocs) {
     const lines = [body.trim()];
-    for (const doc of hudDocs) {
-        lines.push("", `HUD · ${doc.title}`);
-        for (const sectionLine of hudDocSectionLines(doc)) {
-            lines.push(stripSlackMrkdwn(sectionLine));
-        }
+    const uiFallback = uiDocsTextFallback(uiDocs);
+    if (uiFallback) {
+        lines.push("", uiFallback);
     }
     return lines.join("\n").trim();
 }
-async function compileTelegramHudActions(opts) {
-    const hudDocs = hudDocsForPresentation(opts.record.envelope.metadata?.hud_docs, TELEGRAM_DOCS_MAX);
-    if (hudDocs.length === 0) {
-        return { overflowText: "" };
+function telegramReplyMarkupFromButtons(buttons) {
+    if (buttons.length === 0) {
+        return undefined;
     }
-    const buttons = [];
+    const inline_keyboard = [];
+    for (let idx = 0; idx < buttons.length; idx += TELEGRAM_ACTIONS_PER_ROW) {
+        inline_keyboard.push(buttons.slice(idx, idx + TELEGRAM_ACTIONS_PER_ROW));
+    }
+    return { inline_keyboard };
+}
+function telegramOverflowText(lines) {
+    if (lines.length === 0) {
+        return "";
+    }
+    return `\n\nActions:\n${lines.join("\n")}`;
+}
+function commandTextForUiDocAction(action) {
+    const fromMetadata = typeof action.metadata.command_text === "string" ? action.metadata.command_text.trim() : "";
+    if (fromMetadata.length === 0) {
+        return null;
+    }
+    return fromMetadata;
+}
+async function compileTelegramUiDocActions(opts) {
+    if (opts.uiDocs.length === 0) {
+        return { buttonEntries: [], overflowLines: [] };
+    }
+    const buttonEntries = [];
     const overflowLines = [];
-    const actions = hudDocs.flatMap((doc) => doc.actions).slice(0, TELEGRAM_ACTIONS_MAX_TOTAL);
-    for (const action of actions) {
-        let callbackData = action.command_text;
-        if (opts.encodeCallbackData) {
+    for (const doc of opts.uiDocs) {
+        const statusProfile = isStatusProfileStatusVariant(doc);
+        const actions = [...doc.actions].sort((a, b) => a.id.localeCompare(b.id));
+        for (const action of actions) {
+            const commandText = commandTextForUiDocAction(action);
+            const fallbackLine = commandText
+                ? `• ${action.label}: ${commandText}`
+                : `• ${action.label}: interactive unavailable (missing command_text)`;
+            if (statusProfile) {
+                overflowLines.push(fallbackLine);
+                continue;
+            }
+            const uiEvent = buildSanitizedUiEventForAction({
+                doc,
+                action,
+                createdAtMs: opts.nowMs,
+            });
+            if (!commandText || !uiEvent) {
+                overflowLines.push(fallbackLine);
+                continue;
+            }
+            if (!opts.encodeCallbackData) {
+                overflowLines.push(fallbackLine);
+                continue;
+            }
+            let callbackData;
             try {
-                callbackData = await opts.encodeCallbackData(action.command_text);
+                callbackData = await opts.encodeCallbackData(commandText, {
+                    record: opts.record,
+                    uiEvent,
+                });
             }
             catch {
-                overflowLines.push(`• ${action.label}: ${action.command_text}`);
+                overflowLines.push(fallbackLine);
                 continue;
             }
+            if (utf8ByteLength(callbackData) > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
+                overflowLines.push(fallbackLine);
+                continue;
+            }
+            buttonEntries.push({
+                button: {
+                    text: action.label.slice(0, 64),
+                    callback_data: callbackData,
+                },
+                fallbackLine,
+            });
         }
-        if (utf8ByteLength(callbackData) > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
-            overflowLines.push(`• ${action.label}: ${action.command_text}`);
-            continue;
-        }
-        buttons.push({
-            text: action.label.slice(0, 64),
-            callback_data: callbackData,
-        });
-    }
-    const inline_keyboard = [];
-    for (let idx = 0; idx < buttons.length; idx += TELEGRAM_ACTIONS_PER_ROW) {
-        inline_keyboard.push(buttons.slice(idx, idx + TELEGRAM_ACTIONS_PER_ROW));
     }
-    return {
-        replyMarkup: inline_keyboard.length > 0 ? { inline_keyboard } : undefined,
-        overflowText: overflowLines.length > 0 ? `\n\nActions:\n${overflowLines.join("\n")}` : "",
-    };
+    return { buttonEntries, overflowLines };
 }
 async function postTelegramMessage(botToken, payload) {
     return await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
@@ -492,13 +576,22 @@ async function sendTelegramTextChunks(opts) {
 }
 export async function deliverTelegramOutboxRecord(opts) {
     const { botToken, record } = opts;
-    const hudActions = await compileTelegramHudActions({
+    const uiDocs = normalizeUiDocs(record.envelope.metadata?.ui_docs, { maxDocs: UI_DOCS_MAX });
+    const nowMs = Math.trunc(Date.now());
+    const uiActions = await compileTelegramUiDocActions({
         record,
+        uiDocs,
+        nowMs,
         encodeCallbackData: opts.encodeCallbackData,
     });
-    const replyMarkup = hudActions.replyMarkup;
+    const visibleEntries = uiActions.buttonEntries.slice(0, TELEGRAM_ACTIONS_MAX_TOTAL);
+    const overflowLines = [
+        ...uiActions.overflowLines,
+        ...uiActions.buttonEntries.slice(TELEGRAM_ACTIONS_MAX_TOTAL).map((entry) => entry.fallbackLine),
+    ];
+    const replyMarkup = telegramReplyMarkupFromButtons(visibleEntries.map((entry) => entry.button));
     const replyToMessageId = maybeParseTelegramMessageId(record.envelope.metadata?.telegram_reply_to_message_id);
-    const telegramText = `${telegramTextForOutboxRecord(record, record.envelope.body)}${hudActions.overflowText}`.trim();
+    const telegramText = `${telegramTextForOutboxRecord(record.envelope.body, uiDocs)}${telegramOverflowText(overflowLines)}`.trim();
     const fallbackMessagePayload = {
         ...buildTelegramSendMessagePayload({
             chatId: record.envelope.channel_conversation_id,
@@ -640,7 +733,8 @@ export async function deliverTelegramOutboxRecord(opts) {
     };
 }
 async function postSlackJson(opts) {
-    const response = await fetch(`https://slack.com/api/${opts.method}`, {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(`https://slack.com/api/${opts.method}`, {
         method: "POST",
         headers: {
             Authorization: `Bearer ${opts.botToken}`,
@@ -653,10 +747,32 @@ async function postSlackJson(opts) {
 }
 export async function deliverSlackOutboxRecord(opts) {
     const { botToken, record } = opts;
+    const fetchImpl = opts.fetchImpl ?? fetch;
     const attachments = record.envelope.attachments ?? [];
-    const renderedBody = renderSlackMarkdown(record.envelope.body);
+    const uiDocs = normalizeUiDocs(record.envelope.metadata?.ui_docs, { maxDocs: UI_DOCS_MAX });
+    const interactiveUiDocs = uiDocs.filter((doc) => !isStatusProfileStatusVariant(doc));
+    let uiDocActionPayloadsByKey = new Map();
+    if (opts.uiCallbackTokenStore && interactiveUiDocs.some((doc) => doc.actions.length > 0)) {
+        const issued = await issueUiDocActionPayloads({
+            uiDocs: interactiveUiDocs,
+            tokenStore: opts.uiCallbackTokenStore,
+            context: uiActionPayloadContextFromOutboxRecord(record),
+            ttlMs: UI_CALLBACK_TOKEN_TTL_MS,
+            nowMs: Math.trunc((opts.nowMs ?? Date.now)()),
+        });
+        uiDocActionPayloadsByKey = new Map(issued.map((entry) => [entry.key, entry.payload_json]));
+    }
+    const renderedBodyForBlocks = renderSlackMarkdown(record.envelope.body);
+    const blocks = slackBlocksForOutboxRecord(renderedBodyForBlocks, uiDocs, {
+        uiDocActionPayloadsByKey,
+    });
+    const bodyForText = blocks
+        ? record.envelope.body.trim().length > 0
+            ? record.envelope.body
+            : "Update"
+        : appendUiDocText(record.envelope.body, uiDocs);
+    const renderedBody = renderSlackMarkdown(bodyForText);
     const textChunks = splitSlackMessageText(renderedBody);
-    const blocks = slackBlocksForOutboxRecord(record, renderedBody);
     const threadTs = slackThreadTsFromMetadata(record.envelope.metadata);
     const statusMessageTs = slackStatusMessageTsFromMetadata(record.envelope.metadata);
     if (attachments.length === 0) {
@@ -673,6 +789,7 @@ export async function deliverSlackOutboxRecord(opts) {
                     unfurl_media: false,
                     ...(blocks ? { blocks } : {}),
                 },
+                fetchImpl,
             });
             if (updated.response.ok && updated.payload?.ok) {
                 chunkStartIndex = 1;
@@ -707,6 +824,7 @@ export async function deliverSlackOutboxRecord(opts) {
                     ...(index === 0 && blocks ? { blocks } : {}),
                     ...(threadTs ? { thread_ts: threadTs } : {}),
                 },
+                fetchImpl,
             });
             if (delivered.response.ok && delivered.payload?.ok) {
                 continue;
@@ -733,7 +851,7 @@ export async function deliverSlackOutboxRecord(opts) {
                 error: `slack attachment ${index + 1} missing reference.url`,
             };
         }
-        const source = await fetch(referenceUrl);
+        const source = await fetchImpl(referenceUrl);
         if (!source.ok) {
             const sourceErr = await source.text().catch(() => "");
             if (source.status === 429 || source.status >= 500) {
@@ -759,7 +877,7 @@ export async function deliverSlackOutboxRecord(opts) {
             form.set("thread_ts", threadTs);
         }
         form.set("file", new Blob([bytes], { type: contentType }), filename);
-        const uploaded = await fetch("https://slack.com/api/files.upload", {
+        const uploaded = await fetchImpl("https://slack.com/api/files.upload", {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${botToken}`,
@@ -797,6 +915,7 @@ export async function deliverSlackOutboxRecord(opts) {
                     unfurl_media: false,
                     ...(threadTs ? { thread_ts: threadTs } : {}),
                 },
+                fetchImpl,
             });
             if (fallback.response.ok && fallback.payload?.ok) {
                 continue;
@@ -840,6 +959,7 @@ export async function bootstrapControlPlane(opts) {
         return null;
     }
     const paths = getControlPlanePaths(opts.repoRoot);
+    const uiCallbackTokenStore = new UiCallbackTokenStore(paths.uiCallbackTokenPath);
     const runtime = new ControlPlaneRuntime({ repoRoot: opts.repoRoot });
     let pipeline = null;
     let outboxDrainLoop = null;
@@ -847,6 +967,7 @@ export async function bootstrapControlPlane(opts) {
     const outboundDeliveryChannels = new Set();
     const adapterMap = new Map();
     try {
+        await uiCallbackTokenStore.load();
         await runtime.start();
         const operator = opts.operatorRuntime !== undefined
             ? opts.operatorRuntime
@@ -868,6 +989,7 @@ export async function bootstrapControlPlane(opts) {
         const telegramManager = new TelegramAdapterGenerationManager({
             pipeline,
             outbox,
+            uiCallbackTokenStore,
             initialConfig: controlPlaneConfig,
             onOutboxEnqueued: () => {
                 scheduleOutboxDrainRef?.();
@@ -881,6 +1003,7 @@ export async function bootstrapControlPlane(opts) {
             config: controlPlaneConfig,
             pipeline,
             outbox,
+            uiCallbackTokenStore,
         })) {
             const route = adapter.spec.route;
             if (adapterMap.has(route)) {
@@ -939,6 +1062,7 @@ export async function bootstrapControlPlane(opts) {
                     return await deliverSlackOutboxRecord({
                         botToken: slackBotToken,
                         record,
+                        uiCallbackTokenStore,
                     });
                 },
             },
@@ -952,12 +1076,18 @@ export async function bootstrapControlPlane(opts) {
                     return await deliverTelegramOutboxRecord({
                         botToken: telegramBotToken,
                         record,
-                        encodeCallbackData: async (commandText) => {
+                        encodeCallbackData: async (commandText, encodeOpts) => {
                             const active = telegramManager.activeAdapter();
                             if (!active) {
                                 return commandText;
                             }
-                            return await active.issueCallbackToken({ commandText });
+                            return await active.issueCallbackToken({
+                                commandText,
+                                actorId: encodeOpts.record.envelope.correlation.actor_id,
+                                actorBindingId: encodeOpts.record.envelope.correlation.actor_binding_id,
+                                conversationId: encodeOpts.record.envelope.channel_conversation_id,
+                                uiEvent: encodeOpts.uiEvent,
+                            });
                         },
                     });
                 },

package/dist/control_plane_adapter_registry.d.ts

@@ -1,4 +1,4 @@
-import { type ControlPlaneAdapter, type ControlPlaneCommandPipeline, type ControlPlaneOutbox } from "@femtomc/mu-control-plane";
+import { type ControlPlaneAdapter, type ControlPlaneCommandPipeline, type ControlPlaneOutbox, UiCallbackTokenStore } from "@femtomc/mu-control-plane";
 import type { ControlPlaneConfig } from "./control_plane_contract.js";
 export type DetectedStaticAdapter = {
     name: "slack" | "discord" | "neovim";
@@ -16,4 +16,5 @@ export declare function createStaticAdaptersFromDetected(opts: {
     config: ControlPlaneConfig;
     pipeline: ControlPlaneCommandPipeline;
     outbox: ControlPlaneOutbox;
+    uiCallbackTokenStore: UiCallbackTokenStore;
 }): ControlPlaneAdapter[];

package/dist/control_plane_adapter_registry.js

@@ -8,6 +8,7 @@ const STATIC_ADAPTER_MODULES = [
             outbox: opts.outbox,
             signingSecret: opts.secret,
             botToken: opts.config.adapters.slack.bot_token,
+            uiCallbackTokenStore: opts.uiCallbackTokenStore,
         }),
     },
     {
@@ -17,6 +18,7 @@ const STATIC_ADAPTER_MODULES = [
             pipeline: opts.pipeline,
             outbox: opts.outbox,
             signingSecret: opts.secret,
+            uiCallbackTokenStore: opts.uiCallbackTokenStore,
         }),
     },
     {
@@ -25,6 +27,7 @@ const STATIC_ADAPTER_MODULES = [
         create: (opts) => new NeovimControlPlaneAdapter({
             pipeline: opts.pipeline,
             sharedSecret: opts.secret,
+            uiCallbackTokenStore: opts.uiCallbackTokenStore,
         }),
     },
 ];
@@ -69,6 +72,7 @@ export function createStaticAdaptersFromDetected(opts) {
             outbox: opts.outbox,
             secret: detected.secret,
             config: opts.config,
+            uiCallbackTokenStore: opts.uiCallbackTokenStore,
         }));
     }
     return adapters;

package/dist/control_plane_telegram_generation.d.ts

@@ -1,10 +1,11 @@
-import { ControlPlaneCommandPipeline, ControlPlaneOutbox, type ControlPlaneSignalObserver, type ReloadableGenerationIdentity, TelegramControlPlaneAdapter } from "@femtomc/mu-control-plane";
+import { ControlPlaneCommandPipeline, ControlPlaneOutbox, type ControlPlaneSignalObserver, type ReloadableGenerationIdentity, TelegramControlPlaneAdapter, UiCallbackTokenStore } from "@femtomc/mu-control-plane";
 import type { ControlPlaneConfig, TelegramGenerationReloadResult, TelegramGenerationSwapHooks } from "./control_plane_contract.js";
 export declare class TelegramAdapterGenerationManager {
     #private;
     constructor(opts: {
         pipeline: ControlPlaneCommandPipeline;
         outbox: ControlPlaneOutbox;
+        uiCallbackTokenStore: UiCallbackTokenStore;
         initialConfig: ControlPlaneConfig;
         nowMs?: () => number;
         onOutboxEnqueued?: () => void;

package/dist/control_plane_telegram_generation.js

@@ -79,6 +79,7 @@ async function runWithTimeout(opts) {
 export class TelegramAdapterGenerationManager {
     #pipeline;
     #outbox;
+    #uiCallbackTokenStore;
     #nowMs;
     #onOutboxEnqueued;
     #signalObserver;
@@ -90,6 +91,7 @@ export class TelegramAdapterGenerationManager {
     constructor(opts) {
         this.#pipeline = opts.pipeline;
         this.#outbox = opts.outbox;
+        this.#uiCallbackTokenStore = opts.uiCallbackTokenStore;
         this.#nowMs = opts.nowMs ?? Date.now;
         this.#onOutboxEnqueued = opts.onOutboxEnqueued ?? null;
         this.#signalObserver = opts.signalObserver ?? null;
@@ -115,6 +117,7 @@ export class TelegramAdapterGenerationManager {
             acceptIngress: opts.acceptIngress,
             ingressDrainEnabled: opts.ingressDrainEnabled,
             nowMs: this.#nowMs,
+            uiCallbackTokenStore: this.#uiCallbackTokenStore,
         });
     }
     async initialize() {

package/dist/server_routing.js

@@ -13,7 +13,7 @@ export function createServerRequestHandler(deps) {
         if (request.method === "OPTIONS") {
             return new Response(null, { status: 204, headers });
         }
-        if (path === "/healthz" || path === "/health") {
+        if (path === "/healthz") {
             return new Response("ok", { status: 200, headers });
         }
         if (path === "/api/server/shutdown") {

package/package.json

@@ -1,37 +1,37 @@
 {
-  "name": "@femtomc/mu-server",
-  "version": "26.2.106",
-  "description": "HTTP API server for mu control-plane transport/session plus run/activity scheduling coordination.",
-  "keywords": [
-    "mu",
-    "server",
-    "api",
-    "web",
-    "automation"
-  ],
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "mu-server": "./dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist/**"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "bun test",
-    "start": "bun run dist/cli.js"
-  },
-  "dependencies": {
-    "@femtomc/mu-agent": "26.2.106",
-    "@femtomc/mu-control-plane": "26.2.106",
-    "@femtomc/mu-core": "26.2.106"
-  }
+	"name": "@femtomc/mu-server",
+	"version": "26.2.108",
+	"description": "HTTP API server for mu control-plane transport/session plus run/activity scheduling coordination.",
+	"keywords": [
+		"mu",
+		"server",
+		"api",
+		"web",
+		"automation"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"mu-server": "./dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist/**"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "bun test",
+		"start": "bun run dist/cli.js"
+	},
+	"dependencies": {
+		"@femtomc/mu-agent": "26.2.108",
+		"@femtomc/mu-control-plane": "26.2.108",
+		"@femtomc/mu-core": "26.2.108"
+	}
 }