@femtomc/mu-server 26.2.69 → 26.2.71

package/dist/server_program_orchestration.d.ts

@@ -0,0 +1,38 @@
+import type { EventLog } from "@femtomc/mu-core/node";
+import type { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
+import type { ControlPlaneHandle } from "./control_plane_contract.js";
+import { CronProgramRegistry } from "./cron_programs.js";
+import { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+import type { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+export type AutoHeartbeatRunSnapshot = {
+    job_id: string;
+    root_issue_id: string | null;
+    status: string;
+    source: "command" | "api";
+    mode: string;
+};
+type OperatorWakeEmitter = (opts: {
+    dedupeKey: string;
+    message: string;
+    payload: Record<string, unknown>;
+    coalesceMs?: number;
+}) => Promise<boolean>;
+export declare function createServerProgramOrchestration(opts: {
+    repoRoot: string;
+    heartbeatScheduler: ActivityHeartbeatScheduler;
+    controlPlaneProxy: ControlPlaneHandle;
+    activitySupervisor: ControlPlaneActivitySupervisor;
+    eventLog: EventLog;
+    autoRunHeartbeatEveryMs: number;
+    emitOperatorWake: OperatorWakeEmitter;
+}): {
+    heartbeatPrograms: HeartbeatProgramRegistry;
+    cronPrograms: CronProgramRegistry;
+    registerAutoRunHeartbeatProgram: (run: AutoHeartbeatRunSnapshot) => Promise<void>;
+    disableAutoRunHeartbeatProgram: (opts: {
+        jobId: string;
+        status: string;
+        reason: string;
+    }) => Promise<void>;
+};
+export {};

package/dist/server_program_orchestration.js

@@ -0,0 +1,254 @@
+import { CronProgramRegistry } from "./cron_programs.js";
+import { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+const AUTO_RUN_HEARTBEAT_REASON = "auto-run-heartbeat";
+export function createServerProgramOrchestration(opts) {
+    const autoRunHeartbeatProgramByJobId = new Map();
+    const heartbeatPrograms = new HeartbeatProgramRegistry({
+        repoRoot: opts.repoRoot,
+        heartbeatScheduler: opts.heartbeatScheduler,
+        runHeartbeat: async (runOpts) => {
+            const result = await opts.controlPlaneProxy.heartbeatRun?.({
+                jobId: runOpts.jobId ?? null,
+                rootIssueId: runOpts.rootIssueId ?? null,
+                reason: runOpts.reason ?? null,
+                wakeMode: runOpts.wakeMode,
+            });
+            return result ?? { ok: false, reason: "not_found" };
+        },
+        activityHeartbeat: async (activityOpts) => {
+            return opts.activitySupervisor.heartbeat({
+                activityId: activityOpts.activityId ?? null,
+                reason: activityOpts.reason ?? null,
+            });
+        },
+        onTickEvent: async (event) => {
+            await opts.eventLog.emit("heartbeat_program.tick", {
+                source: "mu-server.heartbeat-programs",
+                payload: {
+                    program_id: event.program_id,
+                    status: event.status,
+                    reason: event.reason,
+                    message: event.message,
+                    program: event.program,
+                },
+            });
+            await opts.emitOperatorWake({
+                dedupeKey: `heartbeat-program:${event.program_id}`,
+                message: event.message,
+                payload: {
+                    wake_source: "heartbeat_program",
+                    source_ts_ms: event.ts_ms,
+                    program_id: event.program_id,
+                    status: event.status,
+                    reason: event.reason,
+                    wake_mode: event.program.wake_mode,
+                    target_kind: event.program.target.kind,
+                    target: event.program.target.kind === "run"
+                        ? {
+                            job_id: event.program.target.job_id,
+                            root_issue_id: event.program.target.root_issue_id,
+                        }
+                        : { activity_id: event.program.target.activity_id },
+                },
+            });
+        },
+    });
+    const cronPrograms = new CronProgramRegistry({
+        repoRoot: opts.repoRoot,
+        heartbeatScheduler: opts.heartbeatScheduler,
+        runHeartbeat: async (runOpts) => {
+            const result = await opts.controlPlaneProxy.heartbeatRun?.({
+                jobId: runOpts.jobId ?? null,
+                rootIssueId: runOpts.rootIssueId ?? null,
+                reason: runOpts.reason ?? null,
+                wakeMode: runOpts.wakeMode,
+            });
+            return result ?? { ok: false, reason: "not_found" };
+        },
+        activityHeartbeat: async (activityOpts) => {
+            return opts.activitySupervisor.heartbeat({
+                activityId: activityOpts.activityId ?? null,
+                reason: activityOpts.reason ?? null,
+            });
+        },
+        onLifecycleEvent: async (event) => {
+            await opts.eventLog.emit("cron_program.lifecycle", {
+                source: "mu-server.cron-programs",
+                payload: {
+                    action: event.action,
+                    program_id: event.program_id,
+                    message: event.message,
+                    program: event.program,
+                },
+            });
+        },
+        onTickEvent: async (event) => {
+            await opts.eventLog.emit("cron_program.tick", {
+                source: "mu-server.cron-programs",
+                payload: {
+                    program_id: event.program_id,
+                    status: event.status,
+                    reason: event.reason,
+                    message: event.message,
+                    program: event.program,
+                },
+            });
+            await opts.emitOperatorWake({
+                dedupeKey: `cron-program:${event.program_id}`,
+                message: event.message,
+                payload: {
+                    wake_source: "cron_program",
+                    source_ts_ms: event.ts_ms,
+                    program_id: event.program_id,
+                    status: event.status,
+                    reason: event.reason,
+                    wake_mode: event.program.wake_mode,
+                    target_kind: event.program.target.kind,
+                    target: event.program.target.kind === "run"
+                        ? {
+                            job_id: event.program.target.job_id,
+                            root_issue_id: event.program.target.root_issue_id,
+                        }
+                        : { activity_id: event.program.target.activity_id },
+                },
+            });
+        },
+    });
+    const findAutoRunHeartbeatProgram = async (jobId) => {
+        const normalizedJobId = jobId.trim();
+        if (!normalizedJobId) {
+            return null;
+        }
+        const knownProgramId = autoRunHeartbeatProgramByJobId.get(normalizedJobId);
+        if (knownProgramId) {
+            const knownProgram = await heartbeatPrograms.get(knownProgramId);
+            if (knownProgram) {
+                return knownProgram;
+            }
+            autoRunHeartbeatProgramByJobId.delete(normalizedJobId);
+        }
+        const programs = await heartbeatPrograms.list({ targetKind: "run", limit: 500 });
+        for (const program of programs) {
+            if (program.metadata.auto_run_job_id !== normalizedJobId) {
+                continue;
+            }
+            autoRunHeartbeatProgramByJobId.set(normalizedJobId, program.program_id);
+            return program;
+        }
+        return null;
+    };
+    const registerAutoRunHeartbeatProgram = async (run) => {
+        if (run.source === "command") {
+            return;
+        }
+        const jobId = run.job_id.trim();
+        if (!jobId || run.status !== "running") {
+            return;
+        }
+        const rootIssueId = typeof run.root_issue_id === "string" ? run.root_issue_id.trim() : "";
+        const metadata = {
+            auto_run_heartbeat: true,
+            auto_run_job_id: jobId,
+            auto_run_root_issue_id: rootIssueId || null,
+            auto_disable_on_terminal: true,
+            run_mode: run.mode,
+            run_source: run.source,
+        };
+        const existing = await findAutoRunHeartbeatProgram(jobId);
+        if (existing) {
+            const result = await heartbeatPrograms.update({
+                programId: existing.program_id,
+                title: `Run heartbeat: ${rootIssueId || jobId}`,
+                target: {
+                    kind: "run",
+                    job_id: jobId,
+                    root_issue_id: rootIssueId || null,
+                },
+                enabled: true,
+                everyMs: opts.autoRunHeartbeatEveryMs,
+                reason: AUTO_RUN_HEARTBEAT_REASON,
+                wakeMode: "next_heartbeat",
+                metadata,
+            });
+            if (result.ok && result.program) {
+                autoRunHeartbeatProgramByJobId.set(jobId, result.program.program_id);
+                await opts.eventLog.emit("run.auto_heartbeat.lifecycle", {
+                    source: "mu-server.runs",
+                    payload: {
+                        action: "updated",
+                        run_job_id: jobId,
+                        run_root_issue_id: rootIssueId || null,
+                        program_id: result.program.program_id,
+                        program: result.program,
+                    },
+                });
+            }
+            return;
+        }
+        const created = await heartbeatPrograms.create({
+            title: `Run heartbeat: ${rootIssueId || jobId}`,
+            target: {
+                kind: "run",
+                job_id: jobId,
+                root_issue_id: rootIssueId || null,
+            },
+            everyMs: opts.autoRunHeartbeatEveryMs,
+            reason: AUTO_RUN_HEARTBEAT_REASON,
+            wakeMode: "next_heartbeat",
+            metadata,
+            enabled: true,
+        });
+        autoRunHeartbeatProgramByJobId.set(jobId, created.program_id);
+        await opts.eventLog.emit("run.auto_heartbeat.lifecycle", {
+            source: "mu-server.runs",
+            payload: {
+                action: "registered",
+                run_job_id: jobId,
+                run_root_issue_id: rootIssueId || null,
+                program_id: created.program_id,
+                program: created,
+            },
+        });
+    };
+    const disableAutoRunHeartbeatProgram = async (disableOpts) => {
+        const program = await findAutoRunHeartbeatProgram(disableOpts.jobId);
+        if (!program) {
+            return;
+        }
+        const metadata = {
+            ...program.metadata,
+            auto_disabled_from_status: disableOpts.status,
+            auto_disabled_reason: disableOpts.reason,
+            auto_disabled_at_ms: Date.now(),
+        };
+        const result = await heartbeatPrograms.update({
+            programId: program.program_id,
+            enabled: false,
+            everyMs: 0,
+            reason: AUTO_RUN_HEARTBEAT_REASON,
+            wakeMode: program.wake_mode,
+            metadata,
+        });
+        autoRunHeartbeatProgramByJobId.delete(disableOpts.jobId.trim());
+        if (!result.ok || !result.program) {
+            return;
+        }
+        await opts.eventLog.emit("run.auto_heartbeat.lifecycle", {
+            source: "mu-server.runs",
+            payload: {
+                action: "disabled",
+                run_job_id: disableOpts.jobId,
+                status: disableOpts.status,
+                reason: disableOpts.reason,
+                program_id: result.program.program_id,
+                program: result.program,
+            },
+        });
+    };
+    return {
+        heartbeatPrograms,
+        cronPrograms,
+        registerAutoRunHeartbeatProgram,
+        disableAutoRunHeartbeatProgram,
+    };
+}

package/dist/server_routing.d.ts

@@ -0,0 +1,31 @@
+import type { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
+import type { MuConfig } from "./config.js";
+import type { ControlPlaneHandle } from "./control_plane_contract.js";
+import type { CronProgramRegistry } from "./cron_programs.js";
+import type { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+import type { AutoHeartbeatRunSnapshot } from "./server_program_orchestration.js";
+import type { ServerContext } from "./server.js";
+export type ServerRoutingDependencies = {
+    context: ServerContext;
+    controlPlaneProxy: ControlPlaneHandle;
+    activitySupervisor: ControlPlaneActivitySupervisor;
+    heartbeatPrograms: HeartbeatProgramRegistry;
+    cronPrograms: CronProgramRegistry;
+    loadConfigFromDisk: () => Promise<MuConfig>;
+    writeConfig: (repoRoot: string, config: MuConfig) => Promise<string>;
+    reloadControlPlane: (reason: string) => Promise<{
+        ok: boolean;
+    }>;
+    getControlPlaneStatus: () => unknown;
+    registerAutoRunHeartbeatProgram: (run: AutoHeartbeatRunSnapshot) => Promise<void>;
+    disableAutoRunHeartbeatProgram: (opts: {
+        jobId: string;
+        status: string;
+        reason: string;
+    }) => Promise<void>;
+    describeError: (error: unknown) => string;
+    initiateShutdown?: () => Promise<void>;
+    publicDir?: string;
+    mimeTypes?: Record<string, string>;
+};
+export declare function createServerRequestHandler(deps: ServerRoutingDependencies): (request: Request) => Promise<Response>;

package/dist/server_routing.js

@@ -0,0 +1,230 @@
+import { extname, join, resolve } from "node:path";
+import { activityRoutes } from "./api/activities.js";
+import { configRoutes } from "./api/config.js";
+import { controlPlaneRoutes } from "./api/control_plane.js";
+import { cronRoutes } from "./api/cron.js";
+import { eventRoutes } from "./api/events.js";
+import { forumRoutes } from "./api/forum.js";
+import { heartbeatRoutes } from "./api/heartbeats.js";
+import { identityRoutes } from "./api/identities.js";
+import { issueRoutes } from "./api/issues.js";
+import { runRoutes } from "./api/runs.js";
+const DEFAULT_MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+const DEFAULT_PUBLIC_DIR = join(new URL(".", import.meta.url).pathname, "..", "public");
+export function createServerRequestHandler(deps) {
+    const publicDir = deps.publicDir ?? DEFAULT_PUBLIC_DIR;
+    const mimeTypes = deps.mimeTypes ?? DEFAULT_MIME_TYPES;
+    return async (request) => {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        const headers = new Headers({
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type",
+        });
+        if (request.method === "OPTIONS") {
+            return new Response(null, { status: 204, headers });
+        }
+        if (path === "/healthz" || path === "/health") {
+            return new Response("ok", { status: 200, headers });
+        }
+        if (path === "/api/server/shutdown") {
+            if (request.method !== "POST") {
+                return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+            }
+            if (!deps.initiateShutdown) {
+                return Response.json({ error: "shutdown not supported" }, { status: 501, headers });
+            }
+            const shutdown = deps.initiateShutdown;
+            // Respond before shutting down so the client receives the response.
+            setTimeout(() => { void shutdown(); }, 100);
+            return Response.json({ ok: true, message: "shutdown initiated" }, { headers });
+        }
+        if (path === "/api/config") {
+            return configRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/control-plane/reload" || path === "/api/control-plane/rollback") {
+            return controlPlaneRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/status") {
+            const issues = await deps.context.issueStore.list();
+            const openIssues = issues.filter((i) => i.status === "open");
+            const readyIssues = await deps.context.issueStore.ready();
+            const controlPlane = deps.getControlPlaneStatus();
+            return Response.json({
+                repo_root: deps.context.repoRoot,
+                open_count: openIssues.length,
+                ready_count: readyIssues.length,
+                control_plane: controlPlane,
+            }, { headers });
+        }
+        if (path === "/api/commands/submit") {
+            if (request.method !== "POST") {
+                return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+            }
+            let body;
+            try {
+                body = (await request.json());
+            }
+            catch {
+                return Response.json({ error: "invalid json body" }, { status: 400, headers });
+            }
+            const kind = typeof body.kind === "string" ? body.kind.trim() : "";
+            if (!kind) {
+                return Response.json({ error: "kind is required" }, { status: 400, headers });
+            }
+            let commandText;
+            switch (kind) {
+                case "run_start": {
+                    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+                    if (!prompt) {
+                        return Response.json({ error: "prompt is required for run_start" }, { status: 400, headers });
+                    }
+                    const maxStepsSuffix = typeof body.max_steps === "number" && Number.isFinite(body.max_steps)
+                        ? ` --max-steps ${Math.max(1, Math.trunc(body.max_steps))}`
+                        : "";
+                    commandText = `mu! run start ${prompt}${maxStepsSuffix}`;
+                    break;
+                }
+                case "run_resume": {
+                    const rootId = typeof body.root_issue_id === "string" ? body.root_issue_id.trim() : "";
+                    const maxSteps = typeof body.max_steps === "number" && Number.isFinite(body.max_steps)
+                        ? ` ${Math.max(1, Math.trunc(body.max_steps))}`
+                        : "";
+                    commandText = `mu! run resume${rootId ? ` ${rootId}` : ""}${maxSteps}`;
+                    break;
+                }
+                case "run_interrupt": {
+                    const rootId = typeof body.root_issue_id === "string" ? body.root_issue_id.trim() : "";
+                    commandText = `mu! run interrupt${rootId ? ` ${rootId}` : ""}`;
+                    break;
+                }
+                case "reload":
+                    commandText = "/mu reload";
+                    break;
+                case "update":
+                    commandText = "/mu update";
+                    break;
+                case "status":
+                    commandText = "/mu status";
+                    break;
+                case "issue_list":
+                    commandText = "/mu issue list";
+                    break;
+                case "issue_get": {
+                    const issueId = typeof body.issue_id === "string" ? body.issue_id.trim() : "";
+                    commandText = `/mu issue get${issueId ? ` ${issueId}` : ""}`;
+                    break;
+                }
+                case "forum_read": {
+                    const topic = typeof body.topic === "string" ? body.topic.trim() : "";
+                    const limit = typeof body.limit === "number" && Number.isFinite(body.limit)
+                        ? ` ${Math.max(1, Math.trunc(body.limit))}`
+                        : "";
+                    commandText = `/mu forum read${topic ? ` ${topic}` : ""}${limit}`;
+                    break;
+                }
+                case "run_list":
+                    commandText = "/mu run list";
+                    break;
+                case "run_status": {
+                    const rootId = typeof body.root_issue_id === "string" ? body.root_issue_id.trim() : "";
+                    commandText = `/mu run status${rootId ? ` ${rootId}` : ""}`;
+                    break;
+                }
+                case "ready":
+                    commandText = "/mu ready";
+                    break;
+                default:
+                    return Response.json({ error: `unknown command kind: ${kind}` }, { status: 400, headers });
+            }
+            try {
+                if (!deps.controlPlaneProxy.submitTerminalCommand) {
+                    return Response.json({ error: "control plane not available" }, { status: 503, headers });
+                }
+                const result = await deps.controlPlaneProxy.submitTerminalCommand({
+                    commandText,
+                    repoRoot: deps.context.repoRoot,
+                });
+                return Response.json({ ok: true, result }, { headers });
+            }
+            catch (err) {
+                return Response.json({ error: `command failed: ${deps.describeError(err)}` }, { status: 500, headers });
+            }
+        }
+        if (path === "/api/runs" || path.startsWith("/api/runs/")) {
+            return runRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/cron" || path.startsWith("/api/cron/")) {
+            return cronRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/heartbeats" || path.startsWith("/api/heartbeats/")) {
+            return heartbeatRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/activities" || path.startsWith("/api/activities/")) {
+            return activityRoutes(request, url, deps, headers);
+        }
+        if (path === "/api/identities" || path === "/api/identities/link" || path === "/api/identities/unlink") {
+            return identityRoutes(request, url, deps, headers);
+        }
+        if (path.startsWith("/api/issues")) {
+            const response = await issueRoutes(request, deps.context);
+            headers.forEach((value, key) => {
+                response.headers.set(key, value);
+            });
+            return response;
+        }
+        if (path.startsWith("/api/forum")) {
+            const response = await forumRoutes(request, deps.context);
+            headers.forEach((value, key) => {
+                response.headers.set(key, value);
+            });
+            return response;
+        }
+        if (path.startsWith("/api/events")) {
+            const response = await eventRoutes(request, deps.context);
+            headers.forEach((value, key) => {
+                response.headers.set(key, value);
+            });
+            return response;
+        }
+        if (path.startsWith("/webhooks/")) {
+            const response = await deps.controlPlaneProxy.handleWebhook(path, request);
+            if (response) {
+                headers.forEach((value, key) => {
+                    response.headers.set(key, value);
+                });
+                return response;
+            }
+        }
+        const filePath = resolve(publicDir, `.${path === "/" ? "/index.html" : path}`);
+        if (!filePath.startsWith(publicDir)) {
+            return new Response("Forbidden", { status: 403, headers });
+        }
+        const file = Bun.file(filePath);
+        if (await file.exists()) {
+            const ext = extname(filePath);
+            const mime = mimeTypes[ext] ?? "application/octet-stream";
+            headers.set("Content-Type", mime);
+            return new Response(await file.arrayBuffer(), { status: 200, headers });
+        }
+        const indexPath = join(publicDir, "index.html");
+        const indexFile = Bun.file(indexPath);
+        if (await indexFile.exists()) {
+            headers.set("Content-Type", "text/html; charset=utf-8");
+            return new Response(await indexFile.arrayBuffer(), { status: 200, headers });
+        }
+        return new Response("Not Found", { status: 404, headers });
+    };
+}

package/dist/server_runtime.d.ts

@@ -0,0 +1,30 @@
+import { GenerationTelemetryRecorder } from "@femtomc/mu-control-plane";
+import type { MuConfig } from "./config.js";
+import type { ControlPlaneHandle, ControlPlaneSessionLifecycle, ControlPlaneSessionMutationAction } from "./control_plane_contract.js";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+type ConfigReader = (repoRoot: string) => Promise<MuConfig>;
+export type ServerRuntimeOptions = {
+    repoRoot?: string;
+    controlPlane?: ControlPlaneHandle | null;
+    heartbeatScheduler?: ActivityHeartbeatScheduler;
+    generationTelemetry?: GenerationTelemetryRecorder;
+    config?: MuConfig;
+    configReader?: ConfigReader;
+    sessionLifecycle?: ControlPlaneSessionLifecycle;
+};
+export type ServerRuntimeCapabilities = {
+    session_lifecycle_actions: readonly ControlPlaneSessionMutationAction[];
+    control_plane_bootstrapped: boolean;
+    control_plane_adapters: string[];
+};
+export type ServerRuntime = {
+    repoRoot: string;
+    config: MuConfig;
+    heartbeatScheduler: ActivityHeartbeatScheduler;
+    generationTelemetry: GenerationTelemetryRecorder;
+    sessionLifecycle: ControlPlaneSessionLifecycle;
+    controlPlane: ControlPlaneHandle | null;
+    capabilities: ServerRuntimeCapabilities;
+};
+export declare function composeServerRuntime(options?: ServerRuntimeOptions): Promise<ServerRuntime>;
+export {};

package/dist/server_runtime.js

@@ -0,0 +1,43 @@
+import { GenerationTelemetryRecorder } from "@femtomc/mu-control-plane";
+import { readMuConfigFile } from "./config.js";
+import { bootstrapControlPlane } from "./control_plane.js";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+import { createProcessSessionLifecycle } from "./session_lifecycle.js";
+function computeServerRuntimeCapabilities(controlPlane) {
+    return {
+        session_lifecycle_actions: ["reload", "update"],
+        control_plane_bootstrapped: controlPlane !== null,
+        control_plane_adapters: controlPlane?.activeAdapters.map((adapter) => adapter.name) ?? [],
+    };
+}
+export async function composeServerRuntime(options = {}) {
+    const repoRoot = options.repoRoot || process.cwd();
+    const readConfig = options.configReader ?? readMuConfigFile;
+    const config = options.config ?? (await readConfig(repoRoot));
+    const heartbeatScheduler = options.heartbeatScheduler ?? new ActivityHeartbeatScheduler();
+    const generationTelemetry = options.generationTelemetry ?? new GenerationTelemetryRecorder();
+    const sessionLifecycle = options.sessionLifecycle ?? createProcessSessionLifecycle({ repoRoot });
+    const controlPlane = options.controlPlane !== undefined
+        ? options.controlPlane
+        : await bootstrapControlPlane({
+            repoRoot,
+            config: config.control_plane,
+            heartbeatScheduler,
+            generation: {
+                generation_id: "control-plane-gen-0",
+                generation_seq: 0,
+            },
+            telemetry: generationTelemetry,
+            sessionLifecycle,
+            terminalEnabled: true,
+        });
+    return {
+        repoRoot,
+        config,
+        heartbeatScheduler,
+        generationTelemetry,
+        sessionLifecycle,
+        controlPlane,
+        capabilities: computeServerRuntimeCapabilities(controlPlane),
+    };
+}

package/dist/server_types.d.ts

@@ -0,0 +1,3 @@
+export type ProgramWakeMode = "immediate" | "next_heartbeat";
+export declare function normalizeWakeMode(value: unknown): ProgramWakeMode;
+export declare function toNonNegativeInt(value: unknown, fallback: number): number;

package/dist/server_types.js

@@ -0,0 +1,16 @@
+export function normalizeWakeMode(value) {
+    if (typeof value !== "string") {
+        return "immediate";
+    }
+    const normalized = value.trim().toLowerCase().replaceAll("-", "_");
+    return normalized === "next_heartbeat" ? "next_heartbeat" : "immediate";
+}
+export function toNonNegativeInt(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, 10));
+    }
+    return Math.max(0, Math.trunc(fallback));
+}

package/dist/session_lifecycle.d.ts

@@ -0,0 +1,11 @@
+import type { ControlPlaneSessionLifecycle } from "./control_plane_contract.js";
+export type ShellCommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type ShellCommandRunner = (command: string) => Promise<ShellCommandResult>;
+export declare function createProcessSessionLifecycle(opts: {
+    repoRoot: string;
+    runShellCommand?: ShellCommandRunner;
+}): ControlPlaneSessionLifecycle;