@femtomc/mu-server 26.2.98 → 26.2.99

package/README.md

@@ -1,8 +1,12 @@
 # @femtomc/mu-server
 
-HTTP API server for mu control-plane infrastructure. Powers `mu serve`, messaging frontend transport routes, and control-plane/session coordination endpoints.
+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 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.
 
 ## Installation
 
@@ -141,66 +145,45 @@ Use `mu store paths --pretty` to resolve `<store>` for the active repo/workspace
   - `GET /api/control-plane/events`
   - `GET /api/control-plane/events/tail`
 
-## Messaging adapter setup (workspace config)
+## Messaging adapter setup (skills-first)
 
-1) Resolve workspace paths and inspect current readiness:
+For first-time channel onboarding, prefer bundled setup skills from `mu`
+(`setup-slack`, `setup-discord`, `setup-telegram`, `setup-neovim`).
+These workflows are agent-first: the agent patches config, reloads control-plane,
+verifies routes/capabilities, collects IDs from audit where possible, and asks users
+only for required external-console steps and secret handoff.
 
-```bash
-mu store paths --pretty
-mu control status --pretty
-```
-
-2) Edit `<store>/config.json` and set adapter secrets:
-
-- Slack: `control_plane.adapters.slack.signing_secret`, `bot_token`
-- Discord: `control_plane.adapters.discord.signing_secret`
-- Telegram: `control_plane.adapters.telegram.webhook_secret`, `bot_token`, `bot_username`
-- Neovim: `control_plane.adapters.neovim.shared_secret`
-- Optional operator tuning: `control_plane.operator.timeout_ms` (max wall-time per messaging turn, default `600000`).
-
-3) Reload live control-plane runtime:
+Baseline status/verification commands:
 
 ```bash
+mu control status --pretty
+mu store paths --pretty
 mu control reload
-# or POST /api/control-plane/reload
+curl -s http://localhost:3000/api/control-plane/channels | jq '.channels'
+mu control identities --all --pretty
 ```
 
-4) Link identities for channel actors (examples):
-
-```bash
-mu control link --channel slack --actor-id U123 --tenant-id T123
-mu control link --channel discord --actor-id <user-id> --tenant-id <guild-id>
-mu control link --channel telegram --actor-id <chat-id> --tenant-id telegram-bot
-```
-
-For Neovim, use `:Mu link` in `mu.nvim` after configuring `shared_secret`.
-
 ## Media support operations checklist
 
-When validating attachment support end-to-end, use this sequence:
+When validating attachment support end-to-end:
 
-1. Configure adapter secrets/tokens in `<store>/config.json` (Slack/Telegram need bot tokens for media egress).
+1. Ensure Slack/Telegram bot tokens are configured in `<store>/config.json`.
 2. Reload control-plane (`mu control reload`).
-3. Verify `/api/control-plane/channels` media capability flags:
+3. Verify `/api/control-plane/channels` media flags:
    - `media.outbound_delivery`
    - `media.inbound_attachment_download`
-4. Send a text-only control-plane turn and verify normal delivery semantics still hold.
-5. Send attachment-bearing ingress/outbox payloads and verify channel-specific routing:
-   - Slack media upload through `files.upload`
-   - Telegram PNG/JPEG/WEBP images through `sendPhoto`
-   - Telegram SVG/PDF through `sendDocument`
-
-Operational fallback expectations:
-
-- If media upload fails, Telegram delivery falls back to text `sendMessage`.
-- Telegram text delivery chunks long messages into deterministic in-order `sendMessage` calls to stay below API size limits.
-- When outbound metadata includes `telegram_reply_to_message_id`, Telegram delivery anchors replies to the originating chat message.
-- Invalid/non-integer `telegram_reply_to_message_id` metadata is ignored so delivery degrades gracefully to non-anchored sends.
-- Awaiting-confirmation envelopes include Telegram inline `Confirm`/`Cancel` callback buttons when interaction metadata provides confirmation actions.
-- Telegram callback payloads are contract-limited to `confirm:<command_id>` and `cancel:<command_id>`; unsupported payloads are explicitly rejected.
-- Callback buttons keep parity with command fallback: `/mu confirm <id>` and `/mu cancel <id>` remain valid.
-- Group/supergroup Telegram freeform text is deterministic no-op with guidance; explicit `/mu ...` commands stay actionable.
-- If Slack/Telegram bot token is missing, channel capability reason codes should report `*_bot_token_missing` and outbound delivery retries rather than hard-crashing runtime.
+4. Run one text-only turn and verify normal delivery.
+5. Run one attachment-bearing turn and verify channel-specific routing:
+   - Slack media upload via `files.upload`
+   - Telegram PNG/JPEG/WEBP via `sendPhoto`
+   - Telegram SVG/PDF via `sendDocument`
+
+Operational fallbacks:
+
+- Telegram media upload failure falls back to text `sendMessage`.
+- Telegram long text is deterministically chunked into ordered `sendMessage` calls.
+- `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.
 
 ## Running the Server
 

package/dist/control_plane.js

@@ -161,52 +161,8 @@ export function splitSlackMessageText(text, maxLen = SLACK_MESSAGE_MAX_LEN) {
     }
     return chunks;
 }
-function slackBlocksForOutboxRecord(record, body) {
-    const interactionMessage = record.envelope.metadata?.interaction_message;
-    if (!interactionMessage || typeof interactionMessage !== "object") {
-        return undefined;
-    }
-    const rawActions = interactionMessage.actions;
-    if (!Array.isArray(rawActions) || rawActions.length === 0) {
-        return undefined;
-    }
-    const buttons = [];
-    for (const action of rawActions) {
-        if (!action || typeof action !== "object") {
-            continue;
-        }
-        const candidate = action;
-        if (typeof candidate.label !== "string" || typeof candidate.command !== "string") {
-            continue;
-        }
-        const normalized = candidate.command.trim().replace(/^\/mu\s+/i, "");
-        const confirm = /^confirm\s+([^\s]+)$/i.exec(normalized);
-        if (confirm?.[1]) {
-            buttons.push({
-                type: "button",
-                text: { type: "plain_text", text: candidate.label },
-                value: `confirm:${confirm[1]}`,
-                action_id: `confirm_${confirm[1]}`,
-            });
-            continue;
-        }
-        const cancel = /^cancel\s+([^\s]+)$/i.exec(normalized);
-        if (cancel?.[1]) {
-            buttons.push({
-                type: "button",
-                text: { type: "plain_text", text: candidate.label },
-                value: `cancel:${cancel[1]}`,
-                action_id: `cancel_${cancel[1]}`,
-            });
-        }
-    }
-    if (buttons.length === 0) {
-        return undefined;
-    }
-    return [
-        { type: "section", text: { type: "mrkdwn", text: body } },
-        { type: "actions", elements: buttons },
-    ];
+function slackBlocksForOutboxRecord(_record, _body) {
+    return undefined;
 }
 function slackThreadTsFromMetadata(metadata) {
     const candidates = [metadata?.slack_thread_ts, metadata?.slack_message_ts, metadata?.thread_ts];
@@ -225,36 +181,8 @@ function slackStatusMessageTsFromMetadata(metadata) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-function telegramReplyMarkupForOutboxRecord(record) {
-    const interactionMessage = record.envelope.metadata?.interaction_message;
-    if (!interactionMessage || typeof interactionMessage !== "object") {
-        return undefined;
-    }
-    const rawActions = interactionMessage.actions;
-    if (!Array.isArray(rawActions) || rawActions.length === 0) {
-        return undefined;
-    }
-    const row = [];
-    for (const action of rawActions) {
-        if (!action || typeof action !== "object") {
-            continue;
-        }
-        const candidate = action;
-        if (typeof candidate.label !== "string" || typeof candidate.command !== "string") {
-            continue;
-        }
-        const normalized = candidate.command.trim().replace(/^\/mu\s+/i, "");
-        const confirm = /^confirm\s+([^\s]+)$/i.exec(normalized);
-        if (confirm?.[1]) {
-            row.push({ text: candidate.label, callback_data: `confirm:${confirm[1]}` });
-            continue;
-        }
-        const cancel = /^cancel\s+([^\s]+)$/i.exec(normalized);
-        if (cancel?.[1]) {
-            row.push({ text: candidate.label, callback_data: `cancel:${cancel[1]}` });
-        }
-    }
-    return row.length > 0 ? { inline_keyboard: [row] } : undefined;
+function telegramReplyMarkupForOutboxRecord(_record) {
+    return undefined;
 }
 async function postTelegramMessage(botToken, payload) {
     return await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
@@ -710,94 +638,6 @@ export async function bootstrapControlPlane(opts) {
         pipeline = new ControlPlaneCommandPipeline({
             runtime,
             operator,
-            mutationExecutor: async (record) => {
-                if (record.target_type === "reload" || record.target_type === "update") {
-                    if (record.command_args.length > 0) {
-                        return {
-                            terminalState: "failed",
-                            errorCode: "cli_validation_failed",
-                            trace: {
-                                cliCommandKind: record.target_type,
-                            },
-                            mutatingEvents: [
-                                {
-                                    eventType: "session.lifecycle.command.failed",
-                                    payload: {
-                                        action: record.target_type,
-                                        reason: "unexpected_args",
-                                        args: record.command_args,
-                                    },
-                                },
-                            ],
-                        };
-                    }
-                    const action = record.target_type;
-                    const executeLifecycleAction = action === "reload" ? opts.sessionLifecycle.reload : opts.sessionLifecycle.update;
-                    try {
-                        const lifecycle = await executeLifecycleAction();
-                        if (!lifecycle.ok) {
-                            return {
-                                terminalState: "failed",
-                                errorCode: "session_lifecycle_failed",
-                                trace: {
-                                    cliCommandKind: action,
-                                },
-                                mutatingEvents: [
-                                    {
-                                        eventType: "session.lifecycle.command.failed",
-                                        payload: {
-                                            action,
-                                            reason: lifecycle.message,
-                                            details: lifecycle.details ?? null,
-                                        },
-                                    },
-                                ],
-                            };
-                        }
-                        return {
-                            terminalState: "completed",
-                            result: {
-                                ok: true,
-                                action,
-                                message: lifecycle.message,
-                                details: lifecycle.details ?? null,
-                            },
-                            trace: {
-                                cliCommandKind: action,
-                            },
-                            mutatingEvents: [
-                                {
-                                    eventType: `session.lifecycle.command.${action}`,
-                                    payload: {
-                                        action,
-                                        message: lifecycle.message,
-                                        details: lifecycle.details ?? null,
-                                    },
-                                },
-                            ],
-                        };
-                    }
-                    catch (err) {
-                        return {
-                            terminalState: "failed",
-                            errorCode: err instanceof Error && err.message ? err.message : "session_lifecycle_failed",
-                            trace: {
-                                cliCommandKind: action,
-                            },
-                            mutatingEvents: [
-                                {
-                                    eventType: "session.lifecycle.command.failed",
-                                    payload: {
-                                        action,
-                                        reason: err instanceof Error && err.message ? err.message : "session_lifecycle_failed",
-                                    },
-                                },
-                            ],
-                        };
-                    }
-                }
-                return null;
-            },
         });
         await pipeline.start();
         const telegramManager = new TelegramAdapterGenerationManager({
@@ -1058,11 +898,11 @@ export async function bootstrapControlPlane(opts) {
                 }
                 return result;
             },
-            async submitTerminalCommand(terminalOpts) {
+            async submitAutonomousIngress(autonomousOpts) {
                 if (!pipeline) {
                     throw new Error("control_plane_pipeline_unavailable");
                 }
-                return await pipeline.handleTerminalInbound(terminalOpts);
+                return await pipeline.handleAutonomousIngress(autonomousOpts);
             },
             async stop() {
                 wakeDeliveryObserver = null;

package/dist/control_plane_contract.d.ts

@@ -123,10 +123,11 @@ export type ControlPlaneHandle = {
         config: ControlPlaneConfig;
         reason: string;
     }): Promise<TelegramGenerationReloadResult>;
-    submitTerminalCommand?(opts: {
-        commandText: string;
+    submitAutonomousIngress?(opts: {
+        text: string;
         repoRoot: string;
         requestId?: string;
+        metadata?: Record<string, unknown>;
     }): Promise<CommandPipelineResult>;
     stop(): Promise<void>;
 };

package/dist/server.js

@@ -74,7 +74,7 @@ function extractWakeTurnReply(turnResult) {
     const compact = presented.compact.trim();
     return compact.length > 0 ? compact : null;
 }
-function buildWakeTurnCommandText(opts) {
+function buildWakeTurnIngressText(opts) {
     const wakeSource = stringField(opts.payload, "wake_source") ?? "unknown";
     const programId = stringField(opts.payload, "program_id") ?? "unknown";
     const title = stringField(opts.payload, "title") ?? "(untitled wake program)";
@@ -98,7 +98,7 @@ function buildWakeTurnCommandText(opts) {
         "",
         `payload=${payloadSnapshot}`,
         "",
-        "If action is needed, produce exactly one `/mu ...` command. If no action is needed, return a short operator response that can be broadcast verbatim.",
+        "Respond conversationally with exactly one concise operator message suitable for immediate broadcast.",
     ].join("\n");
 }
 export function createContext(repoRoot) {
@@ -142,7 +142,8 @@ function createServer(options = {}) {
         const programId = stringField(opts.payload, "program_id");
         const sourceTsMs = numberField(opts.payload, "source_ts_ms");
         let decision;
-        if (typeof controlPlaneProxy.submitTerminalCommand !== "function") {
+        const autonomousIngress = controlPlaneProxy.submitAutonomousIngress;
+        if (typeof autonomousIngress !== "function") {
             decision = {
                 outcome: "fallback",
                 reason: "control_plane_unavailable",
@@ -155,14 +156,21 @@ function createServer(options = {}) {
         else {
             const turnRequestId = `wake-turn-${wakeId}`;
             try {
-                const turnResult = await controlPlaneProxy.submitTerminalCommand({
-                    commandText: buildWakeTurnCommandText({
-                        wakeId,
-                        message: opts.message,
-                        payload: opts.payload,
-                    }),
+                const ingressText = buildWakeTurnIngressText({
+                    wakeId,
+                    message: opts.message,
+                    payload: opts.payload,
+                });
+                const turnResult = await autonomousIngress({
+                    text: ingressText,
                     repoRoot: context.repoRoot,
                     requestId: turnRequestId,
+                    metadata: {
+                        wake_id: wakeId,
+                        wake_source: wakeSource,
+                        program_id: programId,
+                        source_ts_ms: sourceTsMs,
+                    },
                 });
                 if (turnResult.kind === "noop" || turnResult.kind === "invalid") {
                     decision = {
@@ -404,12 +412,12 @@ function createServer(options = {}) {
             const handle = reloadManager.getControlPlaneCurrent();
             handle?.setWakeDeliveryObserver?.(observer ?? null);
         },
-        async submitTerminalCommand(opts) {
+        async submitAutonomousIngress(opts) {
             const handle = reloadManager.getControlPlaneCurrent();
-            if (!handle?.submitTerminalCommand) {
-                throw new Error("control_plane_unavailable");
+            if (handle?.submitAutonomousIngress) {
+                return await handle.submitAutonomousIngress(opts);
             }
-            return await handle.submitTerminalCommand(opts);
+            throw new Error("control_plane_unavailable");
         },
         async stop() {
             const handle = reloadManager.getControlPlaneCurrent();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-server",
-  "version": "26.2.98",
+  "version": "26.2.99",
   "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.98",
-    "@femtomc/mu-control-plane": "26.2.98",
-    "@femtomc/mu-core": "26.2.98"
+    "@femtomc/mu-agent": "26.2.99",
+    "@femtomc/mu-control-plane": "26.2.99",
+    "@femtomc/mu-core": "26.2.99"
   }
 }