@femtomc/mu-agent 26.2.35 → 26.2.37

package/README.md

@@ -26,3 +26,55 @@ From repo root (`mu/`):
 bun run build
 bun test packages/orchestrator packages/control-plane
 ```
+
+## Serve-mode extensions (`mu serve`)
+
+When `mu serve` starts the interactive assistant, it loads
+`serveExtensionPaths` from `src/extensions/index.ts` (path-based extensions,
+not anonymous inline factories).
+
+Current stack:
+
+- `brandingExtension` — mu header/footer/widgets
+- `serverToolsExtension` — status + issues/forum/events/control-plane tools
+- `eventLogExtension` — event tail + watch widget
+- `messagingSetupExtension` — adapter diagnostics and setup guidance
+
+`mu serve` sets `MU_SERVER_URL` automatically for these extensions.
+
+## Slash commands (operator-facing)
+
+- `/mu-status` — concise server status
+- `/mu-control` — active control-plane adapters and webhook routes
+- `/mu-setup` — adapter preflight
+- `/mu-setup plan <adapter>` — actionable wiring plan
+- `/mu-setup apply <adapter>` — guided config apply + control-plane reload
+- `/mu-setup verify [adapter]` — runtime verification for mounted routes
+- `/mu-setup <adapter>` — sends adapter setup brief to mu agent (`--no-agent` prints local guide)
+- `/mu-events [n]` / `/mu-events tail [n]` — event log tail
+- `/mu-events watch on|off` — toggle event watch widget
+- `/mu-brand on|off|toggle` — enable/disable UI branding
+
+## Tools (agent/meta-agent-facing)
+
+- `mu_status()`
+  - High-level server status.
+- `mu_control_plane({ action })`
+  - `action`: `status | adapters | routes`
+- `mu_issues({ action, ... })`
+  - `action`: `list | get | ready`
+- `mu_forum({ action, ... })`
+  - `action`: `read | post | topics`
+- `mu_events({ action, ... })`
+  - `action`: `tail | query`
+- `mu_messaging_setup({ action, adapter?, public_base_url? })`
+  - `action`: `check | preflight | guide | plan | apply | verify`
+  - `adapter`: `slack | discord | telegram | gmail`
+
+## Messaging setup notes
+
+- Runtime setup state comes from `GET /api/config` and `.mu/config.json`.
+- `slack`, `discord`, `telegram` are currently modeled as available adapters.
+- `gmail` is modeled as planned guidance (not mounted by runtime yet).
+- `mu_messaging_setup(action=preflight)` is the quickest health check during
+  onboarding.

package/dist/extensions/branding.d.ts

@@ -0,0 +1,13 @@
+/**
+ * mu-branding — Custom serve-mode TUI chrome for mu.
+ *
+ * Adds:
+ * - Custom header + footer
+ * - Quick command widget above the editor
+ * - Terminal title and working message branding
+ * - Lightweight periodic status refresh (open/ready/control-plane)
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function brandingExtension(pi: ExtensionAPI): void;
+export default brandingExtension;
+//# sourceMappingURL=branding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branding.d.ts","sourceRoot":"","sources":["../../src/extensions/branding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA+CpF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,QA4NjD;AAED,eAAe,iBAAiB,CAAC"}

package/dist/extensions/branding.js

@@ -0,0 +1,253 @@
+/**
+ * mu-branding — Custom serve-mode TUI chrome for mu.
+ *
+ * Adds:
+ * - Custom header + footer
+ * - Quick command widget above the editor
+ * - Terminal title and working message branding
+ * - Lightweight periodic status refresh (open/ready/control-plane)
+ */
+import { basename } from "node:path";
+import { fetchMuStatus, muServerUrl } from "./shared.js";
+const EMPTY_SNAPSHOT = {
+    openCount: 0,
+    readyCount: 0,
+    controlPlaneActive: false,
+    adapters: [],
+    error: null,
+};
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+function visibleWidth(text) {
+    return text.replace(ANSI_RE, "").length;
+}
+function truncateToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    if (visibleWidth(text) <= width)
+        return text;
+    const plain = text.replace(ANSI_RE, "");
+    if (width === 1)
+        return plain.slice(0, 1);
+    return `${plain.slice(0, width - 1)}…`;
+}
+function routesFromStatus(adapters, routes) {
+    if (routes && routes.length > 0)
+        return routes;
+    return adapters.map((name) => ({ name, route: `/webhooks/${name}` }));
+}
+function modelLabelFromContext(ctx) {
+    if (!ctx.model)
+        return "model:unknown";
+    return `${ctx.model.provider}/${ctx.model.id}`;
+}
+function modelLabelFromEventModel(model) {
+    return `${model.provider}/${model.id}`;
+}
+export function brandingExtension(pi) {
+    let enabled = true;
+    let repoName = "mu";
+    let currentModel = "model:unknown";
+    let snapshot = { ...EMPTY_SNAPSHOT };
+    let activeCtx = null;
+    let pollTimer = null;
+    let footerRequestRender = null;
+    function refreshWidget(ctx) {
+        if (!ctx.hasUI)
+            return;
+        ctx.ui.setWidget("mu-quick-actions", (_tui, theme) => ({
+            render(width) {
+                const cpState = snapshot.error
+                    ? theme.fg("warning", "cp unavailable")
+                    : snapshot.controlPlaneActive
+                        ? theme.fg("success", `cp ${snapshot.adapters.join(",") || "on"}`)
+                        : theme.fg("muted", "cp off");
+                const line1 = `${theme.fg("accent", "μ")}${theme.fg("dim", " quick actions")}: ${theme.fg("muted", "/mu-status  /mu-control  /mu-setup  /mu-events")}`;
+                const line2 = `${theme.fg("dim", `open ${snapshot.openCount} · ready ${snapshot.readyCount}`)} · ${cpState}`;
+                return [truncateToWidth(line1, width), truncateToWidth(line2, width)];
+            },
+            invalidate() { },
+        }));
+    }
+    function applyChrome(ctx) {
+        if (!ctx.hasUI || !enabled)
+            return;
+        ctx.ui.setTitle(`mu • ${repoName}`);
+        ctx.ui.setWorkingMessage("μ working...");
+        ctx.ui.setHeader((_tui, theme) => ({
+            render(width) {
+                const line1 = `${theme.fg("accent", theme.bold("μ"))} ${theme.bold("mu")} ${theme.fg("muted", "serve console")}`;
+                const line2 = theme.fg("dim", `repo: ${repoName}`);
+                const line3 = theme.fg("muted", "status via: mu_status · mu_control_plane · mu_messaging_setup");
+                return [
+                    "",
+                    truncateToWidth(line1, width),
+                    truncateToWidth(line2, width),
+                    truncateToWidth(line3, width),
+                    "",
+                ];
+            },
+            invalidate() { },
+        }));
+        ctx.ui.setFooter((tui, theme, footerData) => {
+            const requestRender = () => tui.requestRender();
+            const unsubscribeBranch = footerData.onBranchChange(requestRender);
+            footerRequestRender = requestRender;
+            return {
+                dispose() {
+                    if (footerRequestRender === requestRender) {
+                        footerRequestRender = null;
+                    }
+                    unsubscribeBranch();
+                },
+                invalidate() { },
+                render(width) {
+                    const cpLabel = snapshot.error
+                        ? theme.fg("warning", "cp:unavailable")
+                        : snapshot.controlPlaneActive
+                            ? theme.fg("success", `cp:${snapshot.adapters.join(",") || "on"}`)
+                            : theme.fg("muted", "cp:off");
+                    const left = [
+                        theme.fg("accent", "μ"),
+                        theme.fg("dim", repoName),
+                        theme.fg("muted", "|"),
+                        theme.fg("dim", `open ${snapshot.openCount} ready ${snapshot.readyCount}`),
+                        theme.fg("muted", "|"),
+                        cpLabel,
+                    ].join(" ");
+                    const branch = footerData.getGitBranch();
+                    const right = theme.fg("dim", branch ? `${currentModel} · branch:${branch}` : currentModel);
+                    const pad = " ".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+                    return [truncateToWidth(`${left}${pad}${right}`, width)];
+                },
+            };
+        });
+        refreshWidget(ctx);
+    }
+    function clearChrome(ctx) {
+        if (!ctx.hasUI)
+            return;
+        ctx.ui.setHeader(undefined);
+        ctx.ui.setFooter(undefined);
+        ctx.ui.setWidget("mu-quick-actions", undefined);
+        ctx.ui.setWorkingMessage();
+        ctx.ui.setStatus("mu-overview", undefined);
+    }
+    async function refreshStatus(ctx) {
+        if (!ctx.hasUI || !enabled)
+            return;
+        if (!muServerUrl()) {
+            snapshot = {
+                ...EMPTY_SNAPSHOT,
+                error: "MU_SERVER_URL not set",
+            };
+            ctx.ui.setStatus("mu-overview", ctx.ui.theme.fg("warning", "μ server unavailable"));
+            refreshWidget(ctx);
+            footerRequestRender?.();
+            return;
+        }
+        try {
+            const status = await fetchMuStatus(4_000);
+            const cp = status.control_plane ?? {
+                active: false,
+                adapters: [],
+                routes: [],
+            };
+            snapshot = {
+                openCount: status.open_count,
+                readyCount: status.ready_count,
+                controlPlaneActive: cp.active,
+                adapters: routesFromStatus(cp.adapters, cp.routes).map((entry) => entry.name),
+                error: null,
+            };
+            ctx.ui.setStatus("mu-overview", ctx.ui.theme.fg("dim", `μ open ${snapshot.openCount} · ready ${snapshot.readyCount} · cp ${snapshot.controlPlaneActive ? "on" : "off"}`));
+        }
+        catch (err) {
+            snapshot = {
+                ...EMPTY_SNAPSHOT,
+                error: err instanceof Error ? err.message : String(err),
+            };
+            ctx.ui.setStatus("mu-overview", ctx.ui.theme.fg("warning", "μ status refresh failed"));
+        }
+        refreshWidget(ctx);
+        footerRequestRender?.();
+    }
+    function ensurePolling() {
+        if (pollTimer)
+            return;
+        pollTimer = setInterval(() => {
+            if (!activeCtx)
+                return;
+            void refreshStatus(activeCtx);
+        }, 12_000);
+    }
+    function stopPolling() {
+        if (!pollTimer)
+            return;
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+    async function initialize(ctx) {
+        activeCtx = ctx;
+        repoName = basename(ctx.cwd);
+        currentModel = modelLabelFromContext(ctx);
+        if (!ctx.hasUI)
+            return;
+        if (enabled) {
+            applyChrome(ctx);
+            await refreshStatus(ctx);
+            ensurePolling();
+        }
+        else {
+            clearChrome(ctx);
+            stopPolling();
+        }
+    }
+    pi.on("session_start", async (_event, ctx) => {
+        await initialize(ctx);
+    });
+    pi.on("session_switch", async (_event, ctx) => {
+        await initialize(ctx);
+    });
+    pi.on("model_select", async (event, ctx) => {
+        currentModel = modelLabelFromEventModel(event.model);
+        if (!ctx.hasUI || !enabled)
+            return;
+        ctx.ui.setStatus("mu-model", ctx.ui.theme.fg("dim", currentModel));
+        footerRequestRender?.();
+    });
+    pi.on("session_shutdown", async () => {
+        stopPolling();
+        footerRequestRender = null;
+        activeCtx = null;
+    });
+    pi.registerCommand("mu-brand", {
+        description: "Toggle mu TUI branding (`/mu-brand on|off|toggle`)",
+        handler: async (args, ctx) => {
+            const mode = args.trim().toLowerCase();
+            if (mode === "on") {
+                enabled = true;
+            }
+            else if (mode === "off") {
+                enabled = false;
+            }
+            else {
+                enabled = !enabled;
+            }
+            if (!ctx.hasUI) {
+                ctx.ui.notify(`mu branding ${enabled ? "enabled" : "disabled"}.`, "info");
+                return;
+            }
+            if (enabled) {
+                applyChrome(ctx);
+                await refreshStatus(ctx);
+                ensurePolling();
+            }
+            else {
+                clearChrome(ctx);
+                stopPolling();
+            }
+            ctx.ui.notify(`mu branding ${enabled ? "enabled" : "disabled"}.`, "info");
+        },
+    });
+}
+export default brandingExtension;

package/dist/extensions/event-log.d.ts

@@ -0,0 +1,11 @@
+/**
+ * mu-event-log — Event stream helper for mu serve.
+ *
+ * - Status line with last event type and tail count
+ * - Optional watch widget below editor (`/mu-events watch on|off`)
+ * - Command for quick tail inspection (`/mu-events [n]` or `/mu-events tail [n]`)
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function eventLogExtension(pi: ExtensionAPI): void;
+export default eventLogExtension;
+//# sourceMappingURL=event-log.d.ts.map

package/dist/extensions/event-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.d.ts","sourceRoot":"","sources":["../../src/extensions/event-log.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAgCpF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,QAgHjD;AAED,eAAe,iBAAiB,CAAC"}

package/dist/extensions/event-log.js

@@ -0,0 +1,134 @@
+/**
+ * mu-event-log — Event stream helper for mu serve.
+ *
+ * - Status line with last event type and tail count
+ * - Optional watch widget below editor (`/mu-events watch on|off`)
+ * - Command for quick tail inspection (`/mu-events [n]` or `/mu-events tail [n]`)
+ */
+import { clampInt, fetchMuJson, muServerUrl } from "./shared.js";
+function eventTime(tsMs) {
+    return new Date(tsMs).toLocaleTimeString();
+}
+function formatEventLine(event) {
+    const ts = eventTime(event.ts_ms);
+    const payloadHint = event.issue_id ? ` issue:${event.issue_id}` : "";
+    return `${ts}  ${event.type}  (${event.source})${payloadHint}`;
+}
+async function fetchTail(n) {
+    if (!muServerUrl())
+        return [];
+    try {
+        return await fetchMuJson(`/api/events/tail?n=${n}`, { timeoutMs: 6_000 });
+    }
+    catch {
+        return [];
+    }
+}
+export function eventLogExtension(pi) {
+    let watchEnabled = false;
+    let pollTimer = null;
+    let activeCtx = null;
+    async function refresh(ctx, opts = {}) {
+        if (!ctx.hasUI)
+            return;
+        const tail = clampInt(opts.tail, 8, 1, 50);
+        const events = await fetchTail(tail);
+        if (events.length === 0) {
+            ctx.ui.setStatus("mu-events", ctx.ui.theme.fg("dim", "events: none"));
+            if (watchEnabled) {
+                ctx.ui.setWidget("mu-events", [ctx.ui.theme.fg("dim", "(no events yet)")], { placement: "belowEditor" });
+            }
+            return;
+        }
+        const last = events[events.length - 1];
+        ctx.ui.setStatus("mu-events", ctx.ui.theme.fg("dim", `events: ${events.length} · last ${last.type}`));
+        if (watchEnabled) {
+            const lines = events.slice(-5).map((event) => `  ${formatEventLine(event)}`);
+            ctx.ui.setWidget("mu-events", lines, { placement: "belowEditor" });
+        }
+    }
+    function stopPolling() {
+        if (!pollTimer)
+            return;
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+    function ensurePolling() {
+        if (pollTimer)
+            return;
+        pollTimer = setInterval(() => {
+            if (!activeCtx)
+                return;
+            void refresh(activeCtx);
+        }, 8_000);
+    }
+    function setWatchEnabled(next) {
+        watchEnabled = next;
+        if (watchEnabled) {
+            ensurePolling();
+            if (activeCtx) {
+                void refresh(activeCtx);
+            }
+            return;
+        }
+        if (activeCtx?.hasUI) {
+            activeCtx.ui.setWidget("mu-events", undefined);
+        }
+        stopPolling();
+    }
+    pi.on("session_start", async (_event, ctx) => {
+        activeCtx = ctx;
+        if (!ctx.hasUI)
+            return;
+        await refresh(ctx);
+        if (watchEnabled)
+            ensurePolling();
+    });
+    pi.on("session_switch", async (_event, ctx) => {
+        activeCtx = ctx;
+        if (!ctx.hasUI)
+            return;
+        await refresh(ctx);
+        if (watchEnabled)
+            ensurePolling();
+    });
+    pi.on("session_shutdown", async () => {
+        stopPolling();
+        activeCtx = null;
+    });
+    pi.registerCommand("mu-events", {
+        description: "Inspect events (`/mu-events [n]`, `/mu-events tail [n]`, `/mu-events watch on|off`)",
+        handler: async (args, ctx) => {
+            const tokens = args
+                .trim()
+                .split(/\s+/)
+                .filter((token) => token.length > 0);
+            if (tokens[0] === "watch") {
+                const mode = (tokens[1] ?? "toggle").toLowerCase();
+                if (mode === "on") {
+                    setWatchEnabled(true);
+                    ctx.ui.notify("Event watch enabled.", "info");
+                    return;
+                }
+                if (mode === "off") {
+                    setWatchEnabled(false);
+                    ctx.ui.notify("Event watch disabled.", "info");
+                    return;
+                }
+                setWatchEnabled(!watchEnabled);
+                ctx.ui.notify(`Event watch ${watchEnabled ? "enabled" : "disabled"}.`, "info");
+                return;
+            }
+            const requestedLimit = tokens[0] === "tail" ? Number.parseInt(tokens[1] ?? "20", 10) : Number.parseInt(tokens[0] ?? "20", 10);
+            const limit = clampInt(Number.isFinite(requestedLimit) ? requestedLimit : undefined, 20, 1, 100);
+            const events = await fetchTail(limit);
+            if (events.length === 0) {
+                ctx.ui.notify("No events found.", "info");
+                return;
+            }
+            const lines = events.map((event) => formatEventLine(event));
+            ctx.ui.notify(lines.join("\n"), "info");
+        },
+    });
+}
+export default eventLogExtension;

package/dist/extensions/index.d.ts

@@ -0,0 +1,21 @@
+export { brandingExtension } from "./branding.js";
+export { eventLogExtension } from "./event-log.js";
+export { messagingSetupExtension } from "./messaging-setup.js";
+export { serverToolsExtension } from "./server-tools.js";
+import { brandingExtension } from "./branding.js";
+/**
+ * Serve-mode extension module paths.
+ *
+ * Prefer this for session creation so extensions are loaded through pi's
+ * normal path-based loader (discoverable and visible by file path), not as
+ * anonymous inline factories.
+ */
+export declare const serveExtensionPaths: string[];
+/**
+ * Legacy serve-mode extension factories.
+ *
+ * Kept for compatibility in cases where callers need programmatic inline
+ * factories, but path-based loading is preferred.
+ */
+export declare const serveExtensionFactories: (typeof brandingExtension)[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAYlD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,UAE/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,8BAKnC,CAAC"}

package/dist/extensions/index.js

@@ -0,0 +1,33 @@
+export { brandingExtension } from "./branding.js";
+export { eventLogExtension } from "./event-log.js";
+export { messagingSetupExtension } from "./messaging-setup.js";
+export { serverToolsExtension } from "./server-tools.js";
+import { brandingExtension } from "./branding.js";
+import { eventLogExtension } from "./event-log.js";
+import { messagingSetupExtension } from "./messaging-setup.js";
+import { serverToolsExtension } from "./server-tools.js";
+const SERVE_EXTENSION_MODULE_BASENAMES = ["branding", "server-tools", "event-log", "messaging-setup"];
+const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? "ts" : "js";
+function resolveBundledExtensionPath(moduleBasename) {
+    return new URL(`./${moduleBasename}.${RUNTIME_EXTENSION}`, import.meta.url).pathname;
+}
+/**
+ * Serve-mode extension module paths.
+ *
+ * Prefer this for session creation so extensions are loaded through pi's
+ * normal path-based loader (discoverable and visible by file path), not as
+ * anonymous inline factories.
+ */
+export const serveExtensionPaths = SERVE_EXTENSION_MODULE_BASENAMES.map((moduleBasename) => resolveBundledExtensionPath(moduleBasename));
+/**
+ * Legacy serve-mode extension factories.
+ *
+ * Kept for compatibility in cases where callers need programmatic inline
+ * factories, but path-based loading is preferred.
+ */
+export const serveExtensionFactories = [
+    brandingExtension,
+    serverToolsExtension,
+    eventLogExtension,
+    messagingSetupExtension,
+];

package/dist/extensions/messaging-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * mu-messaging-setup — Adapter configuration diagnostics + guided setup.
+ *
+ * Goals:
+ * - Make `/mu-setup <adapter>` hand setup context to the active mu agent.
+ * - Keep configuration in `.mu/config.json` (no process.env mutations).
+ * - Support plan/apply/verify workflow with in-process control-plane reload.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function messagingSetupExtension(pi: ExtensionAPI): void;
+export default messagingSetupExtension;
+//# sourceMappingURL=messaging-setup.d.ts.map

package/dist/extensions/messaging-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-setup.d.ts","sourceRoot":"","sources":["../../src/extensions/messaging-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAA6C,MAAM,+BAA+B,CAAC;AAgjC7G,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,QAqPvD;AAED,eAAe,uBAAuB,CAAC"}