@femtomc/mu-server 26.2.100 → 26.2.102

package/README.md

@@ -185,6 +185,12 @@ 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.
+
 ## Running the Server
 
 ### With terminal operator session (recommended)

package/dist/control_plane.d.ts

@@ -53,9 +53,11 @@ export declare function buildTelegramSendMessagePayload(opts: {
 }): TelegramSendMessagePayload;
 export declare function splitTelegramMessageText(text: string, maxLen?: number): string[];
 export declare function splitSlackMessageText(text: string, maxLen?: number): string[];
+type TelegramCallbackDataEncoder = (commandText: string) => Promise<string>;
 export declare function deliverTelegramOutboxRecord(opts: {
     botToken: string;
     record: OutboxRecord;
+    encodeCallbackData?: TelegramCallbackDataEncoder;
 }): Promise<OutboxDeliveryHandlerResult>;
 export declare function deliverSlackOutboxRecord(opts: {
     botToken: string;

package/dist/control_plane.js

@@ -1,4 +1,5 @@
-import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneRuntime, getControlPlanePaths, TelegramControlPlaneAdapterSpec, } from "@femtomc/mu-control-plane";
+import { applyHudStylePreset, normalizeHudDocs } from "@femtomc/mu-core";
+import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneRuntime, buildSlackHudActionId, getControlPlanePaths, TelegramControlPlaneAdapterSpec, } 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";
@@ -141,6 +142,132 @@ export function splitTelegramMessageText(text, maxLen = TELEGRAM_MESSAGE_MAX_LEN
     return chunks;
 }
 const SLACK_MESSAGE_MAX_LEN = 3_500;
+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);
+}
+function truncateSlackText(text, maxLen = SLACK_BLOCK_TEXT_MAX_LEN) {
+    if (text.length <= maxLen) {
+        return text;
+    }
+    if (maxLen <= 1) {
+        return text.slice(0, maxLen);
+    }
+    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) {
+    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"));
+                }
+                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"));
+                }
+                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"));
+                }
+                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}`);
+                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 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 splitSlackMessageText(text, maxLen = SLACK_MESSAGE_MAX_LEN) {
     if (text.length <= maxLen) {
         return [text];
@@ -161,8 +288,46 @@ export function splitSlackMessageText(text, maxLen = SLACK_MESSAGE_MAX_LEN) {
     }
     return chunks;
 }
-function slackBlocksForOutboxRecord(_record, _body) {
-    return undefined;
+function slackBlocksForOutboxRecord(record, body) {
+    const hudDocs = hudDocsForPresentation(record.envelope.metadata?.hud_docs, SLACK_DOCS_MAX);
+    if (hudDocs.length === 0) {
+        return undefined;
+    }
+    const blocks = [];
+    blocks.push({
+        type: "section",
+        text: { type: "mrkdwn", text: truncateSlackText(body) },
+    });
+    for (const doc of hudDocs) {
+        if (blocks.length >= SLACK_BLOCKS_MAX) {
+            break;
+        }
+        const styledTitle = applySlackHudTextStyle(doc.title, doc.title_style, { defaultWeight: "strong" });
+        blocks.push({
+            type: "context",
+            elements: [{ type: "mrkdwn", text: truncateSlackText(`*HUD* · ${styledTitle}`) }],
+        });
+        for (const line of hudDocSectionLines(doc)) {
+            if (blocks.length >= SLACK_BLOCKS_MAX) {
+                break;
+            }
+            blocks.push({
+                type: "section",
+                text: { type: "mrkdwn", text: truncateSlackText(line) },
+            });
+        }
+        const buttons = hudActionButtons(doc);
+        for (let idx = 0; idx < 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),
+            });
+        }
+    }
+    return blocks.slice(0, SLACK_BLOCKS_MAX);
 }
 function slackThreadTsFromMetadata(metadata) {
     const candidates = [metadata?.slack_thread_ts, metadata?.slack_message_ts, metadata?.thread_ts];
@@ -181,8 +346,63 @@ function slackStatusMessageTsFromMetadata(metadata) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-function telegramReplyMarkupForOutboxRecord(_record) {
-    return undefined;
+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;
+    }
+    const lines = [body.trim()];
+    for (const doc of hudDocs) {
+        lines.push("", `HUD · ${doc.title}`);
+        for (const sectionLine of hudDocSectionLines(doc)) {
+            lines.push(stripSlackMrkdwn(sectionLine));
+        }
+    }
+    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: "" };
+    }
+    const buttons = [];
+    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) {
+            try {
+                callbackData = await opts.encodeCallbackData(action.command_text);
+            }
+            catch {
+                overflowLines.push(`• ${action.label}: ${action.command_text}`);
+                continue;
+            }
+        }
+        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")}` : "",
+    };
 }
 async function postTelegramMessage(botToken, payload) {
     return await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
@@ -272,12 +492,17 @@ async function sendTelegramTextChunks(opts) {
 }
 export async function deliverTelegramOutboxRecord(opts) {
     const { botToken, record } = opts;
-    const replyMarkup = telegramReplyMarkupForOutboxRecord(record);
+    const hudActions = await compileTelegramHudActions({
+        record,
+        encodeCallbackData: opts.encodeCallbackData,
+    });
+    const replyMarkup = hudActions.replyMarkup;
     const replyToMessageId = maybeParseTelegramMessageId(record.envelope.metadata?.telegram_reply_to_message_id);
+    const telegramText = `${telegramTextForOutboxRecord(record, record.envelope.body)}${hudActions.overflowText}`.trim();
     const fallbackMessagePayload = {
         ...buildTelegramSendMessagePayload({
             chatId: record.envelope.channel_conversation_id,
-            text: record.envelope.body,
+            text: telegramText,
             richFormatting: true,
         }),
         ...(replyMarkup ? { reply_markup: replyMarkup } : {}),
@@ -727,6 +952,13 @@ export async function bootstrapControlPlane(opts) {
                     return await deliverTelegramOutboxRecord({
                         botToken: telegramBotToken,
                         record,
+                        encodeCallbackData: async (commandText) => {
+                            const active = telegramManager.activeAdapter();
+                            if (!active) {
+                                return commandText;
+                            }
+                            return await active.issueCallbackToken({ commandText });
+                        },
                     });
                 },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-server",
-  "version": "26.2.100",
+  "version": "26.2.102",
   "description": "HTTP API server for mu control-plane transport/session plus run/activity scheduling coordination.",
   "keywords": [
     "mu",
@@ -30,8 +30,8 @@
     "start": "bun run dist/cli.js"
   },
   "dependencies": {
-    "@femtomc/mu-agent": "26.2.100",
-    "@femtomc/mu-control-plane": "26.2.100",
-    "@femtomc/mu-core": "26.2.100"
+    "@femtomc/mu-agent": "26.2.102",
+    "@femtomc/mu-control-plane": "26.2.102",
+    "@femtomc/mu-core": "26.2.102"
   }
 }