@femtomc/mu-server 26.2.41 → 26.2.42

package/dist/index.js

@@ -1,3 +1,6 @@
 export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
+export { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
+export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
+export { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export { createContext, createServer, createServerAsync } from "./server.js";

package/dist/run_supervisor.d.ts

@@ -0,0 +1,101 @@
+import type { CommandRecord } from "@femtomc/mu-control-plane";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+export type ControlPlaneRunMode = "run_start" | "run_resume";
+export type ControlPlaneRunStatus = "running" | "completed" | "failed" | "cancelled";
+export type ControlPlaneRunSnapshot = {
+    job_id: string;
+    mode: ControlPlaneRunMode;
+    status: ControlPlaneRunStatus;
+    prompt: string | null;
+    root_issue_id: string | null;
+    max_steps: number;
+    command_id: string | null;
+    source: "command" | "api";
+    started_at_ms: number;
+    updated_at_ms: number;
+    finished_at_ms: number | null;
+    exit_code: number | null;
+    pid: number | null;
+    last_progress: string | null;
+};
+export type ControlPlaneRunTrace = {
+    run: ControlPlaneRunSnapshot;
+    stdout: string[];
+    stderr: string[];
+    log_hints: string[];
+    trace_files: string[];
+};
+export type ControlPlaneRunInterruptResult = {
+    ok: boolean;
+    reason: "not_found" | "not_running" | "missing_target" | null;
+    run: ControlPlaneRunSnapshot | null;
+};
+export type ControlPlaneRunHeartbeatResult = {
+    ok: boolean;
+    reason: "not_found" | "not_running" | "missing_target" | null;
+    run: ControlPlaneRunSnapshot | null;
+};
+export type ControlPlaneRunEventKind = "run_started" | "run_root_discovered" | "run_progress" | "run_heartbeat" | "run_interrupt_requested" | "run_completed" | "run_failed" | "run_cancelled";
+export type ControlPlaneRunEvent = {
+    seq: number;
+    ts_ms: number;
+    kind: ControlPlaneRunEventKind;
+    message: string;
+    run: ControlPlaneRunSnapshot;
+    command: CommandRecord | null;
+};
+export type ControlPlaneRunProcess = {
+    pid: number;
+    stdout: ReadableStream<Uint8Array> | null;
+    stderr: ReadableStream<Uint8Array> | null;
+    exited: Promise<number>;
+    kill(signal?: number | string): void;
+};
+export type ControlPlaneRunSupervisorOpts = {
+    repoRoot: string;
+    nowMs?: () => number;
+    spawnProcess?: (opts: {
+        argv: string[];
+        cwd: string;
+    }) => ControlPlaneRunProcess;
+    heartbeatIntervalMs?: number;
+    heartbeatScheduler?: ActivityHeartbeatScheduler;
+    maxStoredLines?: number;
+    maxHistory?: number;
+    onEvent?: (event: ControlPlaneRunEvent) => void | Promise<void>;
+};
+export declare class ControlPlaneRunSupervisor {
+    #private;
+    constructor(opts: ControlPlaneRunSupervisorOpts);
+    launchStart(opts: {
+        prompt: string;
+        maxSteps?: number;
+        command?: CommandRecord | null;
+        source?: "command" | "api";
+    }): Promise<ControlPlaneRunSnapshot>;
+    launchResume(opts: {
+        rootIssueId: string;
+        maxSteps?: number;
+        command?: CommandRecord | null;
+        source?: "command" | "api";
+    }): Promise<ControlPlaneRunSnapshot>;
+    list(opts?: {
+        status?: ControlPlaneRunStatus;
+        limit?: number;
+    }): ControlPlaneRunSnapshot[];
+    get(idOrRoot: string): ControlPlaneRunSnapshot | null;
+    trace(idOrRoot: string, opts?: {
+        limit?: number;
+    }): Promise<ControlPlaneRunTrace | null>;
+    interrupt(opts: {
+        jobId?: string | null;
+        rootIssueId?: string | null;
+    }): ControlPlaneRunInterruptResult;
+    heartbeat(opts: {
+        jobId?: string | null;
+        rootIssueId?: string | null;
+        reason?: string | null;
+    }): ControlPlaneRunHeartbeatResult;
+    startFromCommand(command: CommandRecord): Promise<ControlPlaneRunSnapshot | null>;
+    stop(): Promise<void>;
+}

package/dist/run_supervisor.js

@@ -0,0 +1,480 @@
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+const DEFAULT_MAX_STEPS = 20;
+const ROOT_RE = /\bRoot:\s*(mu-[a-z0-9][a-z0-9-]*)\b/i;
+const STEP_RE = /^(Step|Done)\s+\d+\/\d+\s+/;
+const LOG_HINT_RE = /\blogs:\s+(\S+)/i;
+function defaultNowMs() {
+    return Date.now();
+}
+function defaultSpawnProcess(opts) {
+    const proc = Bun.spawn({
+        cmd: opts.argv,
+        cwd: opts.cwd,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+        env: Bun.env,
+    });
+    return {
+        pid: proc.pid,
+        stdout: proc.stdout,
+        stderr: proc.stderr,
+        exited: proc.exited,
+        kill(signal) {
+            proc.kill(signal);
+        },
+    };
+}
+function toPositiveInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(1, Math.trunc(value));
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        return Math.max(1, Number.parseInt(value, 10));
+    }
+    return fallback;
+}
+function normalizeIssueId(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!/^mu-[a-z0-9][a-z0-9-]*$/i.test(trimmed)) {
+        return null;
+    }
+    return trimmed.toLowerCase();
+}
+function pushBounded(lines, line, maxLines) {
+    lines.push(line);
+    if (lines.length <= maxLines) {
+        return;
+    }
+    lines.splice(0, lines.length - maxLines);
+}
+async function consumeStreamLines(stream, onLine) {
+    if (!stream) {
+        return;
+    }
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            pending += decoder.decode(value, { stream: true });
+            while (true) {
+                const newline = pending.indexOf("\n");
+                if (newline < 0) {
+                    break;
+                }
+                const line = pending.slice(0, newline).replace(/\r$/, "");
+                pending = pending.slice(newline + 1);
+                onLine(line);
+            }
+        }
+        pending += decoder.decode();
+        const finalLine = pending.replace(/\r$/, "").trimEnd();
+        if (finalLine.length > 0) {
+            onLine(finalLine);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function describeRun(snapshot) {
+    const root = snapshot.root_issue_id ?? snapshot.job_id;
+    return `${snapshot.mode} ${root}`;
+}
+export class ControlPlaneRunSupervisor {
+    #repoRoot;
+    #nowMs;
+    #spawnProcess;
+    #heartbeatIntervalMs;
+    #heartbeatScheduler;
+    #ownsHeartbeatScheduler;
+    #maxStoredLines;
+    #maxHistory;
+    #onEvent;
+    #jobsById = new Map();
+    #jobIdByRootIssueId = new Map();
+    #seq = 0;
+    #jobCounter = 0;
+    constructor(opts) {
+        this.#repoRoot = opts.repoRoot;
+        this.#nowMs = opts.nowMs ?? defaultNowMs;
+        this.#spawnProcess = opts.spawnProcess ?? defaultSpawnProcess;
+        this.#heartbeatIntervalMs = Math.max(2_000, Math.trunc(opts.heartbeatIntervalMs ?? 15_000));
+        this.#heartbeatScheduler = opts.heartbeatScheduler ?? new ActivityHeartbeatScheduler();
+        this.#ownsHeartbeatScheduler = !opts.heartbeatScheduler;
+        this.#maxStoredLines = Math.max(50, Math.trunc(opts.maxStoredLines ?? 1_000));
+        this.#maxHistory = Math.max(20, Math.trunc(opts.maxHistory ?? 200));
+        this.#onEvent = opts.onEvent ?? null;
+    }
+    #nextJobId() {
+        this.#jobCounter += 1;
+        return `run-job-${this.#jobCounter.toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+    }
+    #snapshot(job) {
+        return { ...job.snapshot };
+    }
+    #allJobsSorted() {
+        return [...this.#jobsById.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.job_id.localeCompare(b.snapshot.job_id);
+        });
+    }
+    #pruneHistory() {
+        const jobs = this.#allJobsSorted();
+        let kept = 0;
+        for (const job of jobs) {
+            if (job.snapshot.status === "running") {
+                kept += 1;
+                continue;
+            }
+            kept += 1;
+            if (kept <= this.#maxHistory) {
+                continue;
+            }
+            this.#jobsById.delete(job.snapshot.job_id);
+            if (job.snapshot.root_issue_id) {
+                const current = this.#jobIdByRootIssueId.get(job.snapshot.root_issue_id);
+                if (current === job.snapshot.job_id) {
+                    this.#jobIdByRootIssueId.delete(job.snapshot.root_issue_id);
+                }
+            }
+        }
+    }
+    #emit(kind, job, message) {
+        if (!this.#onEvent) {
+            return;
+        }
+        const event = {
+            seq: ++this.#seq,
+            ts_ms: Math.trunc(this.#nowMs()),
+            kind,
+            message,
+            run: this.#snapshot(job),
+            command: job.command,
+        };
+        void Promise.resolve(this.#onEvent(event)).catch(() => {
+            // Swallow notifier errors to avoid destabilizing run supervision.
+        });
+    }
+    #touch(job) {
+        job.snapshot.updated_at_ms = Math.trunc(this.#nowMs());
+    }
+    #markRootIssueId(job, rootIssueId) {
+        const normalized = normalizeIssueId(rootIssueId);
+        if (!normalized) {
+            return;
+        }
+        if (job.snapshot.root_issue_id === normalized) {
+            return;
+        }
+        job.snapshot.root_issue_id = normalized;
+        this.#jobIdByRootIssueId.set(normalized, job.snapshot.job_id);
+        this.#touch(job);
+        this.#emit("run_root_discovered", job, `🧩 Run root identified: ${normalized}`);
+    }
+    #handleLine(job, stream, line) {
+        if (stream === "stdout") {
+            pushBounded(job.stdout_lines, line, this.#maxStoredLines);
+        }
+        else {
+            pushBounded(job.stderr_lines, line, this.#maxStoredLines);
+        }
+        const rootMatch = ROOT_RE.exec(line);
+        if (rootMatch?.[1]) {
+            this.#markRootIssueId(job, rootMatch[1]);
+        }
+        const logHintMatch = LOG_HINT_RE.exec(line);
+        if (logHintMatch?.[1]) {
+            job.log_hints.add(logHintMatch[1]);
+            this.#touch(job);
+        }
+        if (STEP_RE.test(line)) {
+            job.snapshot.last_progress = line.trim();
+            this.#touch(job);
+            this.#emit("run_progress", job, `📈 ${line.trim()}`);
+        }
+    }
+    async #launch(opts) {
+        const nowMs = Math.trunc(this.#nowMs());
+        const process = this.#spawnProcess({ argv: opts.argv, cwd: this.#repoRoot });
+        const snapshot = {
+            job_id: this.#nextJobId(),
+            mode: opts.mode,
+            status: "running",
+            prompt: opts.prompt,
+            root_issue_id: opts.rootIssueId,
+            max_steps: opts.maxSteps,
+            command_id: opts.command?.command_id ?? null,
+            source: opts.source,
+            started_at_ms: nowMs,
+            updated_at_ms: nowMs,
+            finished_at_ms: null,
+            exit_code: null,
+            pid: process.pid,
+            last_progress: null,
+        };
+        const job = {
+            snapshot,
+            command: opts.command,
+            process,
+            stdout_lines: [],
+            stderr_lines: [],
+            log_hints: new Set(),
+            interrupt_requested: false,
+            hard_kill_timer: null,
+        };
+        this.#jobsById.set(snapshot.job_id, job);
+        if (snapshot.root_issue_id) {
+            this.#jobIdByRootIssueId.set(snapshot.root_issue_id, snapshot.job_id);
+        }
+        this.#emit("run_started", job, `🚀 Started ${describeRun(snapshot)} (job ${snapshot.job_id}, pid ${snapshot.pid ?? "?"})`);
+        this.#heartbeatScheduler.register({
+            activityId: snapshot.job_id,
+            everyMs: this.#heartbeatIntervalMs,
+            handler: async () => {
+                if (job.snapshot.status !== "running") {
+                    return { status: "skipped", reason: "not_running" };
+                }
+                const elapsedSec = Math.max(0, Math.trunc((this.#nowMs() - job.snapshot.started_at_ms) / 1_000));
+                const root = job.snapshot.root_issue_id ?? job.snapshot.job_id;
+                const progress = job.snapshot.last_progress ? ` · ${job.snapshot.last_progress}` : "";
+                this.#emit("run_heartbeat", job, `⏱ ${root} running for ${elapsedSec}s${progress}`);
+                return { status: "ran" };
+            },
+        });
+        void (async () => {
+            const stdoutTask = consumeStreamLines(process.stdout, (line) => this.#handleLine(job, "stdout", line));
+            const stderrTask = consumeStreamLines(process.stderr, (line) => this.#handleLine(job, "stderr", line));
+            const exitCode = await process.exited.catch(() => -1);
+            await Promise.allSettled([stdoutTask, stderrTask]);
+            this.#heartbeatScheduler.unregister(job.snapshot.job_id);
+            if (job.hard_kill_timer) {
+                clearTimeout(job.hard_kill_timer);
+                job.hard_kill_timer = null;
+            }
+            job.snapshot.exit_code = exitCode;
+            job.snapshot.finished_at_ms = Math.trunc(this.#nowMs());
+            job.snapshot.updated_at_ms = job.snapshot.finished_at_ms;
+            if (job.interrupt_requested) {
+                job.snapshot.status = "cancelled";
+                this.#emit("run_cancelled", job, `🛑 ${describeRun(job.snapshot)} interrupted (exit ${exitCode}).`);
+            }
+            else if (exitCode === 0) {
+                job.snapshot.status = "completed";
+                this.#emit("run_completed", job, `✅ ${describeRun(job.snapshot)} completed successfully.`);
+            }
+            else {
+                job.snapshot.status = "failed";
+                this.#emit("run_failed", job, `❌ ${describeRun(job.snapshot)} failed (exit ${exitCode}).`);
+            }
+            this.#pruneHistory();
+        })();
+        return this.#snapshot(job);
+    }
+    async launchStart(opts) {
+        const prompt = opts.prompt.trim();
+        if (prompt.length === 0) {
+            throw new Error("run_start_prompt_required");
+        }
+        const maxSteps = toPositiveInt(opts.maxSteps, DEFAULT_MAX_STEPS);
+        const argv = ["mu", "run", prompt, "--max-steps", String(maxSteps), "--raw-stream"];
+        return await this.#launch({
+            mode: "run_start",
+            prompt,
+            rootIssueId: null,
+            maxSteps,
+            argv,
+            command: opts.command ?? null,
+            source: opts.source ?? "api",
+        });
+    }
+    async launchResume(opts) {
+        const rootIssueId = normalizeIssueId(opts.rootIssueId);
+        if (!rootIssueId) {
+            throw new Error("run_resume_invalid_root_issue_id");
+        }
+        const maxSteps = toPositiveInt(opts.maxSteps, DEFAULT_MAX_STEPS);
+        const argv = ["mu", "resume", rootIssueId, "--max-steps", String(maxSteps), "--raw-stream"];
+        return await this.#launch({
+            mode: "run_resume",
+            prompt: null,
+            rootIssueId,
+            maxSteps,
+            argv,
+            command: opts.command ?? null,
+            source: opts.source ?? "api",
+        });
+    }
+    list(opts = {}) {
+        const limit = Math.max(1, Math.min(500, Math.trunc(opts.limit ?? 100)));
+        const filtered = this.#allJobsSorted().filter((job) => opts.status ? job.snapshot.status === opts.status : true);
+        return filtered.slice(0, limit).map((job) => this.#snapshot(job));
+    }
+    #resolveJob(idOrRoot) {
+        const trimmed = idOrRoot.trim();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        const byId = this.#jobsById.get(trimmed);
+        if (byId) {
+            return byId;
+        }
+        const root = normalizeIssueId(trimmed);
+        if (!root) {
+            return null;
+        }
+        const jobId = this.#jobIdByRootIssueId.get(root);
+        if (!jobId) {
+            return null;
+        }
+        return this.#jobsById.get(jobId) ?? null;
+    }
+    get(idOrRoot) {
+        const job = this.#resolveJob(idOrRoot);
+        return job ? this.#snapshot(job) : null;
+    }
+    async trace(idOrRoot, opts = {}) {
+        const job = this.#resolveJob(idOrRoot);
+        if (!job) {
+            return null;
+        }
+        const limit = Math.max(1, Math.min(2_000, Math.trunc(opts.limit ?? 200)));
+        const rootIssueId = job.snapshot.root_issue_id;
+        const traceFiles = [];
+        if (rootIssueId) {
+            const rootLogsDir = join(this.#repoRoot, ".mu", "logs", rootIssueId);
+            try {
+                const entries = await readdir(rootLogsDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isFile())
+                        continue;
+                    if (!entry.name.endsWith(".jsonl"))
+                        continue;
+                    traceFiles.push(relative(this.#repoRoot, join(rootLogsDir, entry.name)).replaceAll("\\", "/"));
+                }
+            }
+            catch {
+                // best effort only
+            }
+        }
+        return {
+            run: this.#snapshot(job),
+            stdout: job.stdout_lines.slice(-limit),
+            stderr: job.stderr_lines.slice(-limit),
+            log_hints: [...job.log_hints],
+            trace_files: traceFiles.sort((a, b) => a.localeCompare(b)),
+        };
+    }
+    interrupt(opts) {
+        const target = opts.jobId?.trim() || opts.rootIssueId?.trim() || "";
+        if (target.length === 0) {
+            return { ok: false, reason: "missing_target", run: null };
+        }
+        const job = this.#resolveJob(target);
+        if (!job) {
+            return { ok: false, reason: "not_found", run: null };
+        }
+        if (job.snapshot.status !== "running") {
+            return { ok: false, reason: "not_running", run: this.#snapshot(job) };
+        }
+        job.interrupt_requested = true;
+        this.#touch(job);
+        try {
+            job.process.kill("SIGINT");
+        }
+        catch {
+            // best effort
+        }
+        job.hard_kill_timer = setTimeout(() => {
+            if (job.snapshot.status !== "running") {
+                return;
+            }
+            try {
+                job.process.kill("SIGKILL");
+            }
+            catch {
+                // best effort
+            }
+        }, 5_000);
+        const root = job.snapshot.root_issue_id ?? job.snapshot.job_id;
+        this.#emit("run_interrupt_requested", job, `⚠️ Interrupt requested for ${root}.`);
+        return { ok: true, reason: null, run: this.#snapshot(job) };
+    }
+    heartbeat(opts) {
+        const target = opts.jobId?.trim() || opts.rootIssueId?.trim() || "";
+        if (target.length === 0) {
+            return { ok: false, reason: "missing_target", run: null };
+        }
+        const job = this.#resolveJob(target);
+        if (!job) {
+            return { ok: false, reason: "not_found", run: null };
+        }
+        if (job.snapshot.status !== "running") {
+            return { ok: false, reason: "not_running", run: this.#snapshot(job) };
+        }
+        const reason = opts.reason?.trim() || "manual";
+        this.#heartbeatScheduler.requestNow(job.snapshot.job_id, {
+            reason,
+            coalesceMs: 0,
+        });
+        return { ok: true, reason: null, run: this.#snapshot(job) };
+    }
+    async startFromCommand(command) {
+        switch (command.target_type) {
+            case "run start": {
+                const prompt = command.command_args.join(" ").trim();
+                if (prompt.length === 0) {
+                    throw new Error("run_start_prompt_required");
+                }
+                return await this.launchStart({ prompt, command, source: "command" });
+            }
+            case "run resume": {
+                const fallbackRoot = normalizeIssueId(command.target_id);
+                const explicitRoot = normalizeIssueId(command.command_args[0] ?? "") ?? fallbackRoot;
+                if (!explicitRoot) {
+                    throw new Error("run_resume_invalid_root_issue_id");
+                }
+                const maxSteps = toPositiveInt(command.command_args[1], DEFAULT_MAX_STEPS);
+                return await this.launchResume({
+                    rootIssueId: explicitRoot,
+                    maxSteps,
+                    command,
+                    source: "command",
+                });
+            }
+            default:
+                return null;
+        }
+    }
+    async stop() {
+        for (const job of this.#jobsById.values()) {
+            this.#heartbeatScheduler.unregister(job.snapshot.job_id);
+            if (job.hard_kill_timer) {
+                clearTimeout(job.hard_kill_timer);
+                job.hard_kill_timer = null;
+            }
+            if (job.snapshot.status === "running") {
+                try {
+                    job.process.kill("SIGTERM");
+                }
+                catch {
+                    // best effort
+                }
+            }
+        }
+        if (this.#ownsHeartbeatScheduler) {
+            this.#heartbeatScheduler.stop();
+        }
+    }
+}

package/dist/server.d.ts

@@ -3,7 +3,10 @@ import { EventLog } from "@femtomc/mu-core/node";
 import { ForumStore } from "@femtomc/mu-forum";
 import { IssueStore } from "@femtomc/mu-issue";
 import { type MuConfig } from "./config.js";
+import { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
 import { type ControlPlaneConfig, type ControlPlaneHandle } from "./control_plane.js";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+import { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
 type ControlPlaneReloader = (opts: {
     repoRoot: string;
     previous: ControlPlaneHandle | null;
@@ -15,6 +18,8 @@ export type ServerOptions = {
     repoRoot?: string;
     port?: number;
     controlPlane?: ControlPlaneHandle | null;
+    heartbeatScheduler?: ActivityHeartbeatScheduler;
+    activitySupervisor?: ControlPlaneActivitySupervisor;
     controlPlaneReloader?: ControlPlaneReloader;
     config?: MuConfig;
     configReader?: ConfigReader;
@@ -33,6 +38,8 @@ export declare function createServer(options?: ServerOptions): {
     fetch: (request: Request) => Promise<Response>;
     hostname: string;
     controlPlane: ControlPlaneHandle;
+    activitySupervisor: ControlPlaneActivitySupervisor;
+    heartbeatPrograms: HeartbeatProgramRegistry;
 };
 export type ServerWithControlPlane = {
     serverConfig: ReturnType<typeof createServer>;