@femtomc/mu-server 26.2.40 → 26.2.42

package/dist/control_plane.js

@@ -1,6 +1,7 @@
 import { ApprovedCommandBroker, CommandContextResolver, MessagingOperatorRuntime, PiMessagingOperatorBackend, serveExtensionPaths, } from "@femtomc/mu-agent";
-import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneOutboxDispatcher, ControlPlaneRuntime, DiscordControlPlaneAdapter, getControlPlanePaths, SlackControlPlaneAdapter, TelegramControlPlaneAdapter, } from "@femtomc/mu-control-plane";
+import { ControlPlaneCommandPipeline, ControlPlaneOutbox, ControlPlaneOutboxDispatcher, correlationFromCommandRecord, ControlPlaneRuntime, DiscordControlPlaneAdapter, getControlPlanePaths, SlackControlPlaneAdapter, TelegramControlPlaneAdapter, } from "@femtomc/mu-control-plane";
 import { DEFAULT_MU_CONFIG } from "./config.js";
+import { ControlPlaneRunSupervisor, } from "./run_supervisor.js";
 export function detectAdapters(config) {
     const adapters = [];
     const slackSecret = config.adapters.slack.signing_secret;
@@ -22,6 +23,120 @@ export function detectAdapters(config) {
     }
     return adapters;
 }
+function sha256Hex(input) {
+    const hasher = new Bun.CryptoHasher("sha256");
+    hasher.update(input);
+    return hasher.digest("hex");
+}
+function outboxKindForRunEvent(kind) {
+    switch (kind) {
+        case "run_completed":
+            return "result";
+        case "run_failed":
+            return "error";
+        default:
+            return "lifecycle";
+    }
+}
+async function enqueueRunEventOutbox(opts) {
+    const command = opts.event.command;
+    if (!command) {
+        return null;
+    }
+    const baseCorrelation = correlationFromCommandRecord(command);
+    const correlation = {
+        ...baseCorrelation,
+        run_root_id: opts.event.run.root_issue_id ?? baseCorrelation.run_root_id,
+    };
+    const envelope = {
+        v: 1,
+        ts_ms: opts.nowMs,
+        channel: command.channel,
+        channel_tenant_id: command.channel_tenant_id,
+        channel_conversation_id: command.channel_conversation_id,
+        request_id: command.request_id,
+        response_id: `resp-${sha256Hex(`run-event:${opts.event.run.job_id}:${opts.event.seq}:${opts.nowMs}`).slice(0, 20)}`,
+        kind: outboxKindForRunEvent(opts.event.kind),
+        body: opts.event.message,
+        correlation,
+        metadata: {
+            async_run: true,
+            run_event_kind: opts.event.kind,
+            run_event_seq: opts.event.seq,
+            run: opts.event.run,
+        },
+    };
+    const decision = await opts.outbox.enqueue({
+        dedupeKey: `run-event:${opts.event.run.job_id}:${opts.event.seq}`,
+        envelope,
+        nowMs: opts.nowMs,
+        maxAttempts: 6,
+    });
+    return decision.record;
+}
+/**
+ * Telegram supports a markdown dialect that uses single markers for emphasis.
+ * Normalize the most common LLM/GitHub-style markers (`**bold**`, `__italic__`, headings)
+ * while preserving fenced code blocks verbatim.
+ */
+export function renderTelegramMarkdown(text) {
+    const normalized = text.replaceAll("\r\n", "\n");
+    const lines = normalized.split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        let next = line;
+        next = next.replace(/^#{1,6}\s+(.+)$/, "*$1*");
+        next = next.replace(/\*\*(.+?)\*\*/g, "*$1*");
+        next = next.replace(/__(.+?)__/g, "_$1_");
+        out.push(next);
+    }
+    return out.join("\n");
+}
+const TELEGRAM_MATH_PATTERNS = [
+    /\$\$[\s\S]+?\$\$/m,
+    /(^|[^\\])\$[^$\n]+\$/m,
+    /\\\([\s\S]+?\\\)/m,
+    /\\\[[\s\S]+?\\\]/m,
+];
+export function containsTelegramMathNotation(text) {
+    if (text.trim().length === 0) {
+        return false;
+    }
+    return TELEGRAM_MATH_PATTERNS.some((pattern) => pattern.test(text));
+}
+export function buildTelegramSendMessagePayload(opts) {
+    if (!opts.richFormatting || containsTelegramMathNotation(opts.text)) {
+        return {
+            chat_id: opts.chatId,
+            text: opts.text,
+        };
+    }
+    return {
+        chat_id: opts.chatId,
+        text: renderTelegramMarkdown(opts.text),
+        parse_mode: "Markdown",
+        disable_web_page_preview: true,
+    };
+}
+async function postTelegramMessage(botToken, payload) {
+    return await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+}
+const OUTBOX_DRAIN_INTERVAL_MS = 500;
 function buildMessagingOperatorRuntime(opts) {
     if (!opts.config.operator.enabled) {
         return null;
@@ -50,6 +165,7 @@ export async function bootstrapControlPlane(opts) {
     const paths = getControlPlanePaths(opts.repoRoot);
     const runtime = new ControlPlaneRuntime({ repoRoot: opts.repoRoot });
     let pipeline = null;
+    let runSupervisor = null;
     let drainInterval = null;
     try {
         await runtime.start();
@@ -60,10 +176,122 @@ export async function bootstrapControlPlane(opts) {
                 config: controlPlaneConfig,
                 backend: opts.operatorBackend,
             });
-        pipeline = new ControlPlaneCommandPipeline({ runtime, operator });
-        await pipeline.start();
         const outbox = new ControlPlaneOutbox(paths.outboxPath);
         await outbox.load();
+        let scheduleOutboxDrainRef = null;
+        runSupervisor = new ControlPlaneRunSupervisor({
+            repoRoot: opts.repoRoot,
+            heartbeatScheduler: opts.heartbeatScheduler,
+            onEvent: async (event) => {
+                const outboxRecord = await enqueueRunEventOutbox({
+                    outbox,
+                    event,
+                    nowMs: Math.trunc(Date.now()),
+                });
+                if (outboxRecord) {
+                    scheduleOutboxDrainRef?.();
+                }
+            },
+        });
+        pipeline = new ControlPlaneCommandPipeline({
+            runtime,
+            operator,
+            mutationExecutor: async (record) => {
+                if (record.target_type === "run start" || record.target_type === "run resume") {
+                    try {
+                        const launched = await runSupervisor?.startFromCommand(record);
+                        if (!launched) {
+                            return null;
+                        }
+                        return {
+                            terminalState: "completed",
+                            result: {
+                                ok: true,
+                                async_run: true,
+                                run_job_id: launched.job_id,
+                                run_root_id: launched.root_issue_id,
+                                run_status: launched.status,
+                                run_mode: launched.mode,
+                                run_source: launched.source,
+                            },
+                            trace: {
+                                cliCommandKind: launched.mode,
+                                runRootId: launched.root_issue_id,
+                            },
+                            mutatingEvents: [
+                                {
+                                    eventType: "run.supervisor.start",
+                                    payload: {
+                                        run_job_id: launched.job_id,
+                                        run_mode: launched.mode,
+                                        run_root_id: launched.root_issue_id,
+                                        run_source: launched.source,
+                                    },
+                                },
+                            ],
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            terminalState: "failed",
+                            errorCode: err instanceof Error && err.message ? err.message : "run_supervisor_start_failed",
+                            trace: {
+                                cliCommandKind: record.target_type.replaceAll(" ", "_"),
+                                runRootId: record.target_id,
+                            },
+                        };
+                    }
+                }
+                if (record.target_type === "run interrupt") {
+                    const result = runSupervisor?.interrupt({
+                        rootIssueId: record.target_id,
+                    }) ?? { ok: false, reason: "not_found", run: null };
+                    if (!result.ok) {
+                        return {
+                            terminalState: "failed",
+                            errorCode: result.reason ?? "run_interrupt_failed",
+                            trace: {
+                                cliCommandKind: "run_interrupt",
+                                runRootId: result.run?.root_issue_id ?? record.target_id,
+                            },
+                            mutatingEvents: [
+                                {
+                                    eventType: "run.supervisor.interrupt.failed",
+                                    payload: {
+                                        reason: result.reason,
+                                        target: record.target_id,
+                                    },
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        terminalState: "completed",
+                        result: {
+                            ok: true,
+                            async_run: true,
+                            interrupted: true,
+                            run: result.run,
+                        },
+                        trace: {
+                            cliCommandKind: "run_interrupt",
+                            runRootId: result.run?.root_issue_id ?? record.target_id,
+                        },
+                        mutatingEvents: [
+                            {
+                                eventType: "run.supervisor.interrupt",
+                                payload: {
+                                    target: record.target_id,
+                                    run: result.run,
+                                },
+                            },
+                        ],
+                    };
+                }
+                return null;
+            },
+        });
+        await pipeline.start();
         let telegramBotToken = null;
         const adapterMap = new Map();
         for (const d of detected) {
@@ -113,42 +341,73 @@ export async function bootstrapControlPlane(opts) {
                 if (!telegramBotToken) {
                     return { kind: "retry", error: "telegram bot token not configured in .mu/config.json" };
                 }
-                const res = await fetch(`https://api.telegram.org/bot${telegramBotToken}/sendMessage`, {
-                    method: "POST",
-                    headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify({
-                        chat_id: envelope.channel_conversation_id,
-                        text: envelope.body,
-                    }),
+                const richPayload = buildTelegramSendMessagePayload({
+                    chatId: envelope.channel_conversation_id,
+                    text: envelope.body,
+                    richFormatting: true,
                 });
+                let res = await postTelegramMessage(telegramBotToken, richPayload);
+                // Fallback: if Telegram rejects markdown entities, retry as plain text.
+                if (!res.ok && res.status === 400 && richPayload.parse_mode) {
+                    const plainPayload = buildTelegramSendMessagePayload({
+                        chatId: envelope.channel_conversation_id,
+                        text: envelope.body,
+                        richFormatting: false,
+                    });
+                    res = await postTelegramMessage(telegramBotToken, plainPayload);
+                }
                 if (res.ok) {
                     return { kind: "delivered" };
                 }
+                const responseBody = await res.text().catch(() => "");
                 if (res.status === 429 || res.status >= 500) {
                     const retryAfter = res.headers.get("retry-after");
                     const retryDelayMs = retryAfter ? Number.parseInt(retryAfter, 10) * 1000 : undefined;
                     return {
                         kind: "retry",
-                        error: `telegram sendMessage ${res.status}: ${await res.text().catch(() => "")}`,
+                        error: `telegram sendMessage ${res.status}: ${responseBody}`,
                         retryDelayMs: retryDelayMs && Number.isFinite(retryDelayMs) ? retryDelayMs : undefined,
                     };
                 }
                 return {
                     kind: "retry",
-                    error: `telegram sendMessage ${res.status}: ${await res.text().catch(() => "")}`,
+                    error: `telegram sendMessage ${res.status}: ${responseBody}`,
                 };
             }
             return undefined;
         };
         const dispatcher = new ControlPlaneOutboxDispatcher({ outbox, deliver });
-        drainInterval = setInterval(async () => {
+        let drainingOutbox = false;
+        let drainRequested = false;
+        const drainOutboxNow = async () => {
+            if (drainingOutbox) {
+                drainRequested = true;
+                return;
+            }
+            drainingOutbox = true;
             try {
-                await dispatcher.drainDue();
+                do {
+                    drainRequested = false;
+                    await dispatcher.drainDue();
+                } while (drainRequested);
             }
             catch {
-                // Swallow errors — the dispatcher already handles retries internally.
+                // Swallow errors — the dispatcher handles retries internally.
+            }
+            finally {
+                drainingOutbox = false;
             }
-        }, 2_000);
+        };
+        const scheduleOutboxDrain = () => {
+            queueMicrotask(() => {
+                void drainOutboxNow();
+            });
+        };
+        scheduleOutboxDrainRef = scheduleOutboxDrain;
+        drainInterval = setInterval(() => {
+            scheduleOutboxDrain();
+        }, OUTBOX_DRAIN_INTERVAL_MS);
+        scheduleOutboxDrain();
         return {
             activeAdapters: [...adapterMap.values()].map((v) => v.info),
             async handleWebhook(path, req) {
@@ -156,13 +415,57 @@ export async function bootstrapControlPlane(opts) {
                 if (!entry)
                     return null;
                 const result = await entry.adapter.ingest(req);
+                if (result.outboxRecord) {
+                    scheduleOutboxDrain();
+                }
                 return result.response;
             },
+            async listRuns(opts = {}) {
+                return (runSupervisor?.list({
+                    status: opts.status,
+                    limit: opts.limit,
+                }) ?? []);
+            },
+            async getRun(idOrRoot) {
+                return runSupervisor?.get(idOrRoot) ?? null;
+            },
+            async startRun(startOpts) {
+                const run = await runSupervisor?.launchStart({
+                    prompt: startOpts.prompt,
+                    maxSteps: startOpts.maxSteps,
+                    source: "api",
+                });
+                if (!run) {
+                    throw new Error("run_supervisor_unavailable");
+                }
+                return run;
+            },
+            async resumeRun(resumeOpts) {
+                const run = await runSupervisor?.launchResume({
+                    rootIssueId: resumeOpts.rootIssueId,
+                    maxSteps: resumeOpts.maxSteps,
+                    source: "api",
+                });
+                if (!run) {
+                    throw new Error("run_supervisor_unavailable");
+                }
+                return run;
+            },
+            async interruptRun(interruptOpts) {
+                return runSupervisor?.interrupt(interruptOpts) ?? { ok: false, reason: "not_found", run: null };
+            },
+            async heartbeatRun(heartbeatOpts) {
+                return runSupervisor?.heartbeat(heartbeatOpts) ?? { ok: false, reason: "not_found", run: null };
+            },
+            async traceRun(traceOpts) {
+                return (await runSupervisor?.trace(traceOpts.idOrRoot, { limit: traceOpts.limit })) ?? null;
+            },
             async stop() {
                 if (drainInterval) {
                     clearInterval(drainInterval);
                     drainInterval = null;
                 }
+                await runSupervisor?.stop();
                 try {
                     await pipeline?.stop();
                 }
@@ -177,6 +480,12 @@ export async function bootstrapControlPlane(opts) {
             clearInterval(drainInterval);
             drainInterval = null;
         }
+        try {
+            await runSupervisor?.stop();
+        }
+        catch {
+            // Best effort cleanup.
+        }
         try {
             await pipeline?.stop();
         }

package/dist/heartbeat_programs.d.ts

@@ -0,0 +1,93 @@
+import type { JsonlStore } from "@femtomc/mu-core";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+export type HeartbeatProgramTarget = {
+    kind: "run";
+    job_id: string | null;
+    root_issue_id: string | null;
+} | {
+    kind: "activity";
+    activity_id: string;
+};
+export type HeartbeatProgramSnapshot = {
+    v: 1;
+    program_id: string;
+    title: string;
+    enabled: boolean;
+    every_ms: number;
+    reason: string;
+    target: HeartbeatProgramTarget;
+    metadata: Record<string, unknown>;
+    created_at_ms: number;
+    updated_at_ms: number;
+    last_triggered_at_ms: number | null;
+    last_result: "ok" | "not_found" | "not_running" | "failed" | null;
+    last_error: string | null;
+};
+export type HeartbeatProgramOperationResult = {
+    ok: boolean;
+    reason: "not_found" | "missing_target" | "invalid_target" | "not_running" | "failed" | null;
+    program: HeartbeatProgramSnapshot | null;
+};
+export type HeartbeatProgramTickEvent = {
+    ts_ms: number;
+    program_id: string;
+    message: string;
+    status: "ok" | "not_found" | "not_running" | "failed";
+    reason: string | null;
+    program: HeartbeatProgramSnapshot;
+};
+export type HeartbeatProgramRegistryOpts = {
+    repoRoot: string;
+    heartbeatScheduler: ActivityHeartbeatScheduler;
+    nowMs?: () => number;
+    store?: JsonlStore<HeartbeatProgramSnapshot>;
+    runHeartbeat: (opts: {
+        jobId?: string | null;
+        rootIssueId?: string | null;
+        reason?: string | null;
+    }) => Promise<{
+        ok: boolean;
+        reason: "not_found" | "not_running" | "missing_target" | null;
+    }>;
+    activityHeartbeat: (opts: {
+        activityId?: string | null;
+        reason?: string | null;
+    }) => Promise<{
+        ok: boolean;
+        reason: "not_found" | "not_running" | "missing_target" | null;
+    }>;
+    onTickEvent?: (event: HeartbeatProgramTickEvent) => void | Promise<void>;
+};
+export declare class HeartbeatProgramRegistry {
+    #private;
+    constructor(opts: HeartbeatProgramRegistryOpts);
+    list(opts?: {
+        enabled?: boolean;
+        targetKind?: "run" | "activity";
+        limit?: number;
+    }): Promise<HeartbeatProgramSnapshot[]>;
+    get(programId: string): Promise<HeartbeatProgramSnapshot | null>;
+    create(opts: {
+        title: string;
+        target: HeartbeatProgramTarget;
+        everyMs?: number;
+        reason?: string;
+        enabled?: boolean;
+        metadata?: Record<string, unknown>;
+    }): Promise<HeartbeatProgramSnapshot>;
+    update(opts: {
+        programId: string;
+        title?: string;
+        everyMs?: number;
+        reason?: string;
+        enabled?: boolean;
+        target?: HeartbeatProgramTarget;
+        metadata?: Record<string, unknown>;
+    }): Promise<HeartbeatProgramOperationResult>;
+    remove(programId: string): Promise<HeartbeatProgramOperationResult>;
+    trigger(opts: {
+        programId?: string | null;
+        reason?: string | null;
+    }): Promise<HeartbeatProgramOperationResult>;
+    stop(): void;
+}