@femtomc/mu-server 26.2.40 → 26.2.42

package/dist/activity_supervisor.d.ts

@@ -0,0 +1,81 @@
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+export type ControlPlaneActivityStatus = "running" | "completed" | "failed" | "cancelled";
+export type ControlPlaneActivitySnapshot = {
+    activity_id: string;
+    kind: string;
+    title: string;
+    status: ControlPlaneActivityStatus;
+    heartbeat_every_ms: number;
+    heartbeat_count: number;
+    last_heartbeat_at_ms: number | null;
+    last_heartbeat_reason: string | null;
+    last_progress: string | null;
+    final_message: string | null;
+    metadata: Record<string, unknown>;
+    source: "api" | "command" | "system";
+    started_at_ms: number;
+    updated_at_ms: number;
+    finished_at_ms: number | null;
+};
+export type ControlPlaneActivityEventKind = "activity_started" | "activity_progress" | "activity_heartbeat" | "activity_completed" | "activity_failed" | "activity_cancelled";
+export type ControlPlaneActivityEvent = {
+    seq: number;
+    ts_ms: number;
+    kind: ControlPlaneActivityEventKind;
+    message: string;
+    activity: ControlPlaneActivitySnapshot;
+};
+export type ControlPlaneActivityMutationResult = {
+    ok: boolean;
+    reason: "not_found" | "not_running" | "missing_target" | null;
+    activity: ControlPlaneActivitySnapshot | null;
+};
+export type ControlPlaneActivitySupervisorOpts = {
+    nowMs?: () => number;
+    heartbeatScheduler?: ActivityHeartbeatScheduler;
+    defaultHeartbeatEveryMs?: number;
+    maxHistory?: number;
+    maxEventsPerActivity?: number;
+    onEvent?: (event: ControlPlaneActivityEvent) => void | Promise<void>;
+};
+export declare class ControlPlaneActivitySupervisor {
+    #private;
+    constructor(opts?: ControlPlaneActivitySupervisorOpts);
+    start(opts: {
+        title: string;
+        kind?: string;
+        heartbeatEveryMs?: number;
+        metadata?: Record<string, unknown>;
+        source?: "api" | "command" | "system";
+    }): ControlPlaneActivitySnapshot;
+    list(opts?: {
+        status?: ControlPlaneActivityStatus;
+        kind?: string;
+        limit?: number;
+    }): ControlPlaneActivitySnapshot[];
+    get(activityId: string): ControlPlaneActivitySnapshot | null;
+    events(activityId: string, opts?: {
+        limit?: number;
+    }): ControlPlaneActivityEvent[] | null;
+    progress(opts: {
+        activityId?: string | null;
+        message?: string | null;
+    }): ControlPlaneActivityMutationResult;
+    heartbeat(opts: {
+        activityId?: string | null;
+        reason?: string | null;
+    }): ControlPlaneActivityMutationResult;
+    complete(opts: {
+        activityId?: string | null;
+        message?: string | null;
+    }): ControlPlaneActivityMutationResult;
+    fail(opts: {
+        activityId?: string | null;
+        message?: string | null;
+    }): ControlPlaneActivityMutationResult;
+    cancel(opts: {
+        activityId?: string | null;
+        message?: string | null;
+    }): ControlPlaneActivityMutationResult;
+    stop(): void;
+}

package/dist/activity_supervisor.js

@@ -0,0 +1,306 @@
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+const DEFAULT_HEARTBEAT_EVERY_MS = 15_000;
+function defaultNowMs() {
+    return Date.now();
+}
+function normalizeKind(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return "generic";
+    }
+    return trimmed.toLowerCase();
+}
+function normalizeTitle(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error("activity_title_required");
+    }
+    return trimmed;
+}
+function normalizeHeartbeatEveryMs(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(0, Math.trunc(value));
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        return Math.max(0, Number.parseInt(value.trim(), 10));
+    }
+    return fallback;
+}
+function toSafeMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return { ...value };
+}
+function pushBounded(items, value, max) {
+    items.push(value);
+    if (items.length <= max) {
+        return;
+    }
+    items.splice(0, items.length - max);
+}
+function elapsedSeconds(snapshot, nowMs) {
+    return Math.max(0, Math.trunc((nowMs - snapshot.started_at_ms) / 1_000));
+}
+export class ControlPlaneActivitySupervisor {
+    #nowMs;
+    #heartbeatScheduler;
+    #ownsHeartbeatScheduler;
+    #defaultHeartbeatEveryMs;
+    #maxHistory;
+    #maxEventsPerActivity;
+    #onEvent;
+    #activities = new Map();
+    #seq = 0;
+    #counter = 0;
+    constructor(opts = {}) {
+        this.#nowMs = opts.nowMs ?? defaultNowMs;
+        this.#heartbeatScheduler = opts.heartbeatScheduler ?? new ActivityHeartbeatScheduler();
+        this.#ownsHeartbeatScheduler = !opts.heartbeatScheduler;
+        this.#defaultHeartbeatEveryMs = Math.max(0, Math.trunc(opts.defaultHeartbeatEveryMs ?? DEFAULT_HEARTBEAT_EVERY_MS));
+        this.#maxHistory = Math.max(20, Math.trunc(opts.maxHistory ?? 200));
+        this.#maxEventsPerActivity = Math.max(20, Math.trunc(opts.maxEventsPerActivity ?? 400));
+        this.#onEvent = opts.onEvent ?? null;
+    }
+    #nextActivityId() {
+        this.#counter += 1;
+        return `activity-${this.#counter.toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+    }
+    #snapshot(activity) {
+        return {
+            ...activity.snapshot,
+            metadata: { ...activity.snapshot.metadata },
+        };
+    }
+    #touch(activity) {
+        activity.snapshot.updated_at_ms = Math.trunc(this.#nowMs());
+    }
+    #emit(kind, activity, message) {
+        const event = {
+            seq: ++this.#seq,
+            ts_ms: Math.trunc(this.#nowMs()),
+            kind,
+            message,
+            activity: this.#snapshot(activity),
+        };
+        pushBounded(activity.events, event, this.#maxEventsPerActivity);
+        if (!this.#onEvent) {
+            return;
+        }
+        void Promise.resolve(this.#onEvent(event)).catch(() => {
+            // Do not crash on notifier failures.
+        });
+    }
+    #pruneHistory() {
+        const rows = [...this.#activities.values()].sort((a, b) => {
+            if (a.snapshot.started_at_ms !== b.snapshot.started_at_ms) {
+                return b.snapshot.started_at_ms - a.snapshot.started_at_ms;
+            }
+            return a.snapshot.activity_id.localeCompare(b.snapshot.activity_id);
+        });
+        let kept = 0;
+        for (const row of rows) {
+            if (row.snapshot.status === "running") {
+                kept += 1;
+                continue;
+            }
+            kept += 1;
+            if (kept <= this.#maxHistory) {
+                continue;
+            }
+            this.#heartbeatScheduler.unregister(row.snapshot.activity_id);
+            this.#activities.delete(row.snapshot.activity_id);
+        }
+    }
+    #resolveActivity(activityIdRaw) {
+        const id = activityIdRaw?.trim() ?? "";
+        if (id.length === 0) {
+            return null;
+        }
+        return this.#activities.get(id) ?? null;
+    }
+    #heartbeatMessage(activity) {
+        const nowMs = Math.trunc(this.#nowMs());
+        const elapsed = elapsedSeconds(activity.snapshot, nowMs);
+        const progress = activity.snapshot.last_progress ? ` · ${activity.snapshot.last_progress}` : "";
+        return `⏱ ${activity.snapshot.title} running for ${elapsed}s${progress}`;
+    }
+    #emitHeartbeat(activity, reason) {
+        activity.snapshot.heartbeat_count += 1;
+        activity.snapshot.last_heartbeat_at_ms = Math.trunc(this.#nowMs());
+        activity.snapshot.last_heartbeat_reason = reason?.trim() || "requested";
+        this.#touch(activity);
+        this.#emit("activity_heartbeat", activity, this.#heartbeatMessage(activity));
+    }
+    #registerHeartbeat(activity) {
+        if (activity.snapshot.heartbeat_every_ms <= 0) {
+            return;
+        }
+        this.#heartbeatScheduler.register({
+            activityId: activity.snapshot.activity_id,
+            everyMs: activity.snapshot.heartbeat_every_ms,
+            handler: async ({ reason }) => {
+                if (activity.snapshot.status !== "running") {
+                    return { status: "skipped", reason: "not_running" };
+                }
+                this.#emitHeartbeat(activity, reason);
+                return { status: "ran" };
+            },
+        });
+    }
+    start(opts) {
+        const nowMs = Math.trunc(this.#nowMs());
+        const snapshot = {
+            activity_id: this.#nextActivityId(),
+            kind: normalizeKind(opts.kind),
+            title: normalizeTitle(opts.title),
+            status: "running",
+            heartbeat_every_ms: normalizeHeartbeatEveryMs(opts.heartbeatEveryMs, this.#defaultHeartbeatEveryMs),
+            heartbeat_count: 0,
+            last_heartbeat_at_ms: null,
+            last_heartbeat_reason: null,
+            last_progress: null,
+            final_message: null,
+            metadata: toSafeMetadata(opts.metadata),
+            source: opts.source ?? "api",
+            started_at_ms: nowMs,
+            updated_at_ms: nowMs,
+            finished_at_ms: null,
+        };
+        const activity = {
+            snapshot,
+            events: [],
+        };
+        this.#activities.set(snapshot.activity_id, activity);
+        this.#registerHeartbeat(activity);
+        this.#emit("activity_started", activity, `🚀 Started activity ${snapshot.title} (${snapshot.activity_id}).`);
+        return this.#snapshot(activity);
+    }
+    list(opts = {}) {
+        const limit = Math.max(1, Math.min(500, Math.trunc(opts.limit ?? 100)));
+        const kind = opts.kind?.trim().toLowerCase() || null;
+        return [...this.#activities.values()]
+            .filter((activity) => {
+            if (opts.status && activity.snapshot.status !== opts.status) {
+                return false;
+            }
+            if (kind && activity.snapshot.kind !== kind) {
+                return false;
+            }
+            return true;
+        })
+            .sort((a, b) => {
+            if (a.snapshot.started_at_ms !== b.snapshot.started_at_ms) {
+                return b.snapshot.started_at_ms - a.snapshot.started_at_ms;
+            }
+            return a.snapshot.activity_id.localeCompare(b.snapshot.activity_id);
+        })
+            .slice(0, limit)
+            .map((activity) => this.#snapshot(activity));
+    }
+    get(activityId) {
+        const activity = this.#resolveActivity(activityId);
+        return activity ? this.#snapshot(activity) : null;
+    }
+    events(activityId, opts = {}) {
+        const activity = this.#resolveActivity(activityId);
+        if (!activity) {
+            return null;
+        }
+        const limit = Math.max(1, Math.min(2_000, Math.trunc(opts.limit ?? 200)));
+        return activity.events.slice(-limit).map((event) => ({
+            ...event,
+            activity: {
+                ...event.activity,
+                metadata: { ...event.activity.metadata },
+            },
+        }));
+    }
+    progress(opts) {
+        const activity = this.#resolveActivity(opts.activityId);
+        if (!opts.activityId?.trim()) {
+            return { ok: false, reason: "missing_target", activity: null };
+        }
+        if (!activity) {
+            return { ok: false, reason: "not_found", activity: null };
+        }
+        if (activity.snapshot.status !== "running") {
+            return { ok: false, reason: "not_running", activity: this.#snapshot(activity) };
+        }
+        const message = opts.message?.trim() || "progress updated";
+        activity.snapshot.last_progress = message;
+        this.#touch(activity);
+        this.#emit("activity_progress", activity, `📈 ${message}`);
+        return { ok: true, reason: null, activity: this.#snapshot(activity) };
+    }
+    heartbeat(opts) {
+        const activityId = opts.activityId?.trim() || "";
+        if (activityId.length === 0) {
+            return { ok: false, reason: "missing_target", activity: null };
+        }
+        const activity = this.#activities.get(activityId) ?? null;
+        if (!activity) {
+            return { ok: false, reason: "not_found", activity: null };
+        }
+        if (activity.snapshot.status !== "running") {
+            return { ok: false, reason: "not_running", activity: this.#snapshot(activity) };
+        }
+        const reason = opts.reason?.trim() || "manual";
+        if (this.#heartbeatScheduler.has(activityId)) {
+            this.#heartbeatScheduler.requestNow(activityId, { reason, coalesceMs: 0 });
+        }
+        else {
+            this.#emitHeartbeat(activity, reason);
+        }
+        return { ok: true, reason: null, activity: this.#snapshot(activity) };
+    }
+    #finish(opts) {
+        const activityId = opts.activityId?.trim() || "";
+        if (activityId.length === 0) {
+            return { ok: false, reason: "missing_target", activity: null };
+        }
+        const activity = this.#activities.get(activityId) ?? null;
+        if (!activity) {
+            return { ok: false, reason: "not_found", activity: null };
+        }
+        if (activity.snapshot.status !== "running") {
+            return { ok: false, reason: "not_running", activity: this.#snapshot(activity) };
+        }
+        activity.snapshot.status = opts.status;
+        activity.snapshot.final_message = opts.message?.trim() || null;
+        activity.snapshot.finished_at_ms = Math.trunc(this.#nowMs());
+        activity.snapshot.updated_at_ms = activity.snapshot.finished_at_ms;
+        this.#heartbeatScheduler.unregister(activity.snapshot.activity_id);
+        switch (opts.status) {
+            case "completed":
+                this.#emit("activity_completed", activity, `✅ Activity completed: ${activity.snapshot.title}${activity.snapshot.final_message ? ` · ${activity.snapshot.final_message}` : ""}`);
+                break;
+            case "failed":
+                this.#emit("activity_failed", activity, `❌ Activity failed: ${activity.snapshot.title}${activity.snapshot.final_message ? ` · ${activity.snapshot.final_message}` : ""}`);
+                break;
+            case "cancelled":
+                this.#emit("activity_cancelled", activity, `🛑 Activity cancelled: ${activity.snapshot.title}${activity.snapshot.final_message ? ` · ${activity.snapshot.final_message}` : ""}`);
+                break;
+        }
+        this.#pruneHistory();
+        return { ok: true, reason: null, activity: this.#snapshot(activity) };
+    }
+    complete(opts) {
+        return this.#finish({ ...opts, status: "completed" });
+    }
+    fail(opts) {
+        return this.#finish({ ...opts, status: "failed" });
+    }
+    cancel(opts) {
+        return this.#finish({ ...opts, status: "cancelled" });
+    }
+    stop() {
+        for (const activity of this.#activities.values()) {
+            this.#heartbeatScheduler.unregister(activity.snapshot.activity_id);
+        }
+        if (this.#ownsHeartbeatScheduler) {
+            this.#heartbeatScheduler.stop();
+        }
+        this.#activities.clear();
+    }
+}

package/dist/control_plane.d.ts

@@ -1,6 +1,8 @@
 import { type MessagingOperatorBackend, MessagingOperatorRuntime } from "@femtomc/mu-agent";
 import { type Channel } from "@femtomc/mu-control-plane";
 import { type MuConfig } from "./config.js";
+import { type ControlPlaneRunHeartbeatResult, type ControlPlaneRunInterruptResult, type ControlPlaneRunSnapshot, type ControlPlaneRunTrace } from "./run_supervisor.js";
+import type { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export type ActiveAdapter = {
     name: Channel;
     route: string;
@@ -8,6 +10,32 @@ export type ActiveAdapter = {
 export type ControlPlaneHandle = {
     activeAdapters: ActiveAdapter[];
     handleWebhook(path: string, req: Request): Promise<Response | null>;
+    listRuns?(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<ControlPlaneRunSnapshot[]>;
+    getRun?(idOrRoot: string): Promise<ControlPlaneRunSnapshot | null>;
+    startRun?(opts: {
+        prompt: string;
+        maxSteps?: number;
+    }): Promise<ControlPlaneRunSnapshot>;
+    resumeRun?(opts: {
+        rootIssueId: string;
+        maxSteps?: number;
+    }): Promise<ControlPlaneRunSnapshot>;
+    interruptRun?(opts: {
+        jobId?: string | null;
+        rootIssueId?: string | null;
+    }): Promise<ControlPlaneRunInterruptResult>;
+    heartbeatRun?(opts: {
+        jobId?: string | null;
+        rootIssueId?: string | null;
+        reason?: string | null;
+    }): Promise<ControlPlaneRunHeartbeatResult>;
+    traceRun?(opts: {
+        idOrRoot: string;
+        limit?: number;
+    }): Promise<ControlPlaneRunTrace | null>;
     stop(): Promise<void>;
 };
 export type ControlPlaneConfig = MuConfig["control_plane"];
@@ -24,11 +52,30 @@ type DetectedAdapter = {
     botUsername: string | null;
 };
 export declare function detectAdapters(config: ControlPlaneConfig): DetectedAdapter[];
+export type TelegramSendMessagePayload = {
+    chat_id: string;
+    text: string;
+    parse_mode?: "Markdown";
+    disable_web_page_preview?: boolean;
+};
+/**
+ * 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 declare function renderTelegramMarkdown(text: string): string;
+export declare function containsTelegramMathNotation(text: string): boolean;
+export declare function buildTelegramSendMessagePayload(opts: {
+    chatId: string;
+    text: string;
+    richFormatting: boolean;
+}): TelegramSendMessagePayload;
 export type BootstrapControlPlaneOpts = {
     repoRoot: string;
     config?: ControlPlaneConfig;
     operatorRuntime?: MessagingOperatorRuntime | null;
     operatorBackend?: MessagingOperatorBackend;
+    heartbeatScheduler?: ActivityHeartbeatScheduler;
 };
 export declare function bootstrapControlPlane(opts: BootstrapControlPlaneOpts): Promise<ControlPlaneHandle | null>;
 export {};