@femtomc/mu-server 26.2.90 → 26.2.91

package/dist/control_plane_run_queue_coordinator.js

@@ -1,266 +0,0 @@
-import { reconcileRunQueue, runSnapshotFromQueueSnapshot, } from "./run_queue.js";
-const DEFAULT_RUN_MAX_STEPS = 20;
-const MAX_RECONCILE_TURNS = 256;
-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 Math.max(1, Math.trunc(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();
-}
-/**
- * Queue/reconcile adapter for control-plane run lifecycle operations.
- *
- * Keeps inter-root queue execution concerns out of `control_plane.ts` while preserving
- * queue-first semantics:
- * - enqueue intents durably
- * - reconcile/claim/launch deterministically
- * - mirror runtime events back into durable queue state
- */
-export class ControlPlaneRunQueueCoordinator {
-    #runQueue;
-    #interRootQueuePolicy;
-    #getRunSupervisor;
-    #defaultRunMaxSteps;
-    #queuedCommandById = new Map();
-    #queueReconcileCounter = 0;
-    #queueReconcileTail = Promise.resolve();
-    constructor(opts) {
-        this.#runQueue = opts.runQueue;
-        this.#interRootQueuePolicy = opts.interRootQueuePolicy;
-        this.#getRunSupervisor = opts.getRunSupervisor;
-        this.#defaultRunMaxSteps = toPositiveInt(opts.defaultRunMaxSteps, DEFAULT_RUN_MAX_STEPS);
-    }
-    runtimeSnapshotsByJobId() {
-        const map = new Map();
-        for (const run of this.#getRunSupervisor()?.list({ limit: 500 }) ?? []) {
-            map.set(run.job_id, run);
-        }
-        return map;
-    }
-    async #launchQueueEntry(row, opPrefix) {
-        const runSupervisor = this.#getRunSupervisor();
-        if (!runSupervisor) {
-            throw new Error("run_supervisor_unavailable");
-        }
-        const command = row.command_id ? (this.#queuedCommandById.get(row.command_id) ?? null) : null;
-        try {
-            const launched = row.mode === "run_start"
-                ? await runSupervisor.launchStart({
-                    prompt: row.prompt ?? "",
-                    maxSteps: row.max_steps,
-                    command,
-                    commandId: row.command_id,
-                    source: row.source,
-                })
-                : await runSupervisor.launchResume({
-                    rootIssueId: row.root_issue_id ?? "",
-                    maxSteps: row.max_steps,
-                    command,
-                    commandId: row.command_id,
-                    source: row.source,
-                });
-            if (command?.command_id) {
-                this.#queuedCommandById.delete(command.command_id);
-            }
-            const latestSnapshot = runSupervisor.get(launched.job_id) ?? launched;
-            await this.#runQueue.bindRunSnapshot({
-                queueId: row.queue_id,
-                run: latestSnapshot,
-                operationId: `${opPrefix}:bind:${row.queue_id}:${launched.job_id}`,
-            });
-        }
-        catch {
-            if (command?.command_id) {
-                this.#queuedCommandById.delete(command.command_id);
-            }
-            await this.#runQueue.transition({
-                queueId: row.queue_id,
-                toState: "failed",
-                operationId: `${opPrefix}:failed:${row.queue_id}`,
-            });
-        }
-    }
-    async #reconcileQueuedRunsNow(reason) {
-        const runSupervisor = this.#getRunSupervisor();
-        if (!runSupervisor) {
-            return;
-        }
-        for (let turn = 0; turn < MAX_RECONCILE_TURNS; turn += 1) {
-            const rows = await this.#runQueue.list({ limit: 500 });
-            const plan = reconcileRunQueue(rows, this.#interRootQueuePolicy);
-            if (plan.activate_queue_ids.length === 0 && plan.launch_queue_ids.length === 0) {
-                return;
-            }
-            if (plan.activate_queue_ids.length > 0) {
-                for (const queueId of plan.activate_queue_ids) {
-                    await this.#runQueue.claim({
-                        queueId,
-                        operationId: `reconcile:${reason}:activate:${queueId}:${turn}`,
-                    });
-                }
-                continue;
-            }
-            for (const queueId of plan.launch_queue_ids) {
-                const row = await this.#runQueue.get(queueId);
-                if (!row || row.state !== "active") {
-                    continue;
-                }
-                if (row.job_id) {
-                    const existing = runSupervisor.get(row.job_id);
-                    if (existing) {
-                        await this.#runQueue.applyRunSnapshot({
-                            queueId: row.queue_id,
-                            run: existing,
-                            operationId: `reconcile:${reason}:existing:${row.queue_id}:${existing.updated_at_ms}`,
-                        });
-                        continue;
-                    }
-                }
-                await this.#launchQueueEntry(row, `reconcile:${reason}:launch:${turn}`);
-            }
-        }
-    }
-    async scheduleReconcile(reason) {
-        const token = `${++this.#queueReconcileCounter}:${reason}`;
-        this.#queueReconcileTail = this.#queueReconcileTail.then(async () => await this.#reconcileQueuedRunsNow(token), async () => await this.#reconcileQueuedRunsNow(token));
-        return await this.#queueReconcileTail;
-    }
-    async launchQueuedRun(launchOpts) {
-        const runSupervisor = this.#getRunSupervisor();
-        if (!runSupervisor) {
-            throw new Error("run_supervisor_unavailable");
-        }
-        const dedupeKey = launchOpts.dedupeKey.trim();
-        if (!dedupeKey) {
-            throw new Error("run_queue_dedupe_key_required");
-        }
-        const maxSteps = toPositiveInt(launchOpts.maxSteps, this.#defaultRunMaxSteps);
-        const queued = await this.#runQueue.enqueue({
-            mode: launchOpts.mode,
-            prompt: launchOpts.mode === "run_start" ? (launchOpts.prompt ?? null) : null,
-            rootIssueId: launchOpts.mode === "run_resume" ? (launchOpts.rootIssueId ?? null) : null,
-            maxSteps,
-            commandId: launchOpts.command?.command_id ?? null,
-            source: launchOpts.source,
-            dedupeKey,
-            operationId: `enqueue:${dedupeKey}`,
-        });
-        if (launchOpts.command?.command_id) {
-            this.#queuedCommandById.set(launchOpts.command.command_id, launchOpts.command);
-        }
-        await this.scheduleReconcile(`enqueue:${queued.queue_id}`);
-        const refreshed = (await this.#runQueue.get(queued.queue_id)) ?? queued;
-        const runtime = refreshed.job_id ? (runSupervisor.get(refreshed.job_id) ?? null) : null;
-        return runSnapshotFromQueueSnapshot(refreshed, runtime);
-    }
-    async launchQueuedRunFromCommand(record) {
-        if (record.target_type === "run start") {
-            const prompt = record.command_args.join(" ").trim();
-            if (!prompt) {
-                throw new Error("run_start_prompt_required");
-            }
-            return await this.launchQueuedRun({
-                mode: "run_start",
-                prompt,
-                source: "command",
-                command: record,
-                dedupeKey: `command:${record.command_id}`,
-            });
-        }
-        if (record.target_type === "run resume") {
-            const fallbackRoot = normalizeIssueId(record.target_id);
-            const explicitRoot = normalizeIssueId(record.command_args[0] ?? "") ?? fallbackRoot;
-            if (!explicitRoot) {
-                throw new Error("run_resume_invalid_root_issue_id");
-            }
-            const maxSteps = toPositiveInt(record.command_args[1], this.#defaultRunMaxSteps);
-            return await this.launchQueuedRun({
-                mode: "run_resume",
-                rootIssueId: explicitRoot,
-                maxSteps,
-                source: "command",
-                command: record,
-                dedupeKey: `command:${record.command_id}`,
-            });
-        }
-        throw new Error("run_queue_invalid_command_target");
-    }
-    async interruptQueuedRun(opts) {
-        const runSupervisor = this.#getRunSupervisor();
-        const result = runSupervisor?.interrupt(opts) ?? { ok: false, reason: "not_found", run: null };
-        if (result.run) {
-            await this.#runQueue
-                .applyRunSnapshot({
-                run: result.run,
-                operationId: `interrupt-sync:${result.run.job_id}:${result.run.updated_at_ms}`,
-                createIfMissing: true,
-            })
-                .catch(() => {
-                // Best effort only.
-            });
-        }
-        if (result.ok) {
-            return result;
-        }
-        const target = opts.jobId?.trim() || opts.rootIssueId?.trim() || "";
-        if (!target) {
-            return result;
-        }
-        const queued = await this.#runQueue.get(target);
-        if (!queued) {
-            return result;
-        }
-        if (queued.state === "queued" ||
-            queued.state === "active" ||
-            queued.state === "waiting_review" ||
-            queued.state === "refining") {
-            const cancelled = await this.#runQueue.transition({
-                queueId: queued.queue_id,
-                toState: "cancelled",
-                operationId: `interrupt-cancel:${target}`,
-            });
-            await this.scheduleReconcile(`interrupt:${queued.queue_id}`);
-            return {
-                ok: true,
-                reason: null,
-                run: runSnapshotFromQueueSnapshot(cancelled),
-            };
-        }
-        return {
-            ok: false,
-            reason: "not_running",
-            run: runSnapshotFromQueueSnapshot(queued),
-        };
-    }
-    async onRunEvent(event) {
-        await this.#runQueue
-            .applyRunSnapshot({
-            run: event.run,
-            operationId: `run-event:${event.seq}:${event.kind}`,
-            createIfMissing: false,
-        })
-            .catch(() => {
-            // Best effort queue reconciliation from runtime events.
-            return null;
-        });
-        if (event.kind === "run_completed" || event.kind === "run_failed" || event.kind === "run_cancelled") {
-            await this.scheduleReconcile(`terminal:${event.kind}:${event.run.job_id}`);
-        }
-    }
-    stop() {
-        this.#queuedCommandById.clear();
-    }
-}

package/dist/orchestration_queue.d.ts

@@ -1,44 +0,0 @@
-export type OrchestrationQueueState = "queued" | "active" | "waiting_review" | "refining" | "done" | "failed" | "cancelled";
-/**
- * Inter-root scheduler policy knob for durable queue drain.
- * - sequential: exactly one active root (`max_active_roots=1`)
- * - parallel: bounded fanout (`max_active_roots>=1`)
- */
-export type InterRootQueuePolicy = {
-    mode: "sequential";
-    max_active_roots: 1;
-} | {
-    mode: "parallel";
-    max_active_roots: number;
-};
-export declare const DEFAULT_INTER_ROOT_QUEUE_POLICY: InterRootQueuePolicy;
-export declare function normalizeInterRootQueuePolicy(policy: InterRootQueuePolicy | null | undefined): InterRootQueuePolicy;
-/**
- * Allowed queue transitions. Queue tests should enforce this table exactly.
- */
-export declare const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS: Record<OrchestrationQueueState, readonly OrchestrationQueueState[]>;
-export declare const ORCHESTRATION_QUEUE_INVARIANTS: readonly ["ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.", "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.", "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.", "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).", "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.", "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots."];
-export type InterRootQueueSnapshot = {
-    queue_id: string;
-    root_issue_id: string | null;
-    state: OrchestrationQueueState;
-    job_id: string | null;
-    created_at_ms: number;
-};
-export type InterRootQueueReconcilePlan = {
-    policy: InterRootQueuePolicy;
-    max_active_roots: number;
-    active_root_count: number;
-    available_root_slots: number;
-    activate_queue_ids: string[];
-    launch_queue_ids: string[];
-};
-export declare const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS: readonly ["ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.", "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.", "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.", "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot."];
-/**
- * Deterministic inter-root queue reconcile primitive.
- *
- * Computes queue activation/launch intentions from durable queue state and policy. The caller is
- * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
- * against refreshed queue/runtime snapshots.
- */
-export declare function reconcileInterRootQueue<Row extends InterRootQueueSnapshot>(rows: readonly Row[], policy: InterRootQueuePolicy): InterRootQueueReconcilePlan;

package/dist/orchestration_queue.js

@@ -1,111 +0,0 @@
-export const DEFAULT_INTER_ROOT_QUEUE_POLICY = {
-    mode: "sequential",
-    max_active_roots: 1,
-};
-export function normalizeInterRootQueuePolicy(policy) {
-    if (!policy) {
-        return DEFAULT_INTER_ROOT_QUEUE_POLICY;
-    }
-    if (policy.mode === "parallel") {
-        return {
-            mode: "parallel",
-            max_active_roots: Math.max(1, Math.trunc(policy.max_active_roots)),
-        };
-    }
-    return DEFAULT_INTER_ROOT_QUEUE_POLICY;
-}
-/**
- * Allowed queue transitions. Queue tests should enforce this table exactly.
- */
-export const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS = {
-    queued: ["active", "cancelled"],
-    active: ["waiting_review", "done", "failed", "cancelled"],
-    waiting_review: ["refining", "done", "failed", "cancelled"],
-    refining: ["queued", "failed", "cancelled"],
-    done: [],
-    failed: [],
-    cancelled: [],
-};
-export const ORCHESTRATION_QUEUE_INVARIANTS = [
-    "ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.",
-    "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.",
-    "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.",
-    "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).",
-    "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.",
-    "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots.",
-];
-const INTER_ROOT_OCCUPIED_STATES = new Set(["active", "waiting_review", "refining"]);
-export const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS = [
-    "ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.",
-    "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.",
-    "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.",
-    "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot.",
-];
-function stableCompare(a, b) {
-    if (a.created_at_ms !== b.created_at_ms) {
-        return a.created_at_ms - b.created_at_ms;
-    }
-    return a.queue_id.localeCompare(b.queue_id);
-}
-function normalizeMaxActiveRoots(policy) {
-    if (policy.mode === "parallel") {
-        return Math.max(1, Math.trunc(policy.max_active_roots));
-    }
-    return 1;
-}
-function queueRootSlotKey(row) {
-    return row.root_issue_id ? `root:${row.root_issue_id}` : `queue:${row.queue_id}`;
-}
-/**
- * Deterministic inter-root queue reconcile primitive.
- *
- * Computes queue activation/launch intentions from durable queue state and policy. The caller is
- * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
- * against refreshed queue/runtime snapshots.
- */
-export function reconcileInterRootQueue(rows, policy) {
-    const sorted = [...rows].sort(stableCompare);
-    const maxActiveRoots = normalizeMaxActiveRoots(policy);
-    const occupiedRoots = new Set();
-    const launchRoots = new Set();
-    const launchQueueIds = [];
-    for (const row of sorted) {
-        if (!INTER_ROOT_OCCUPIED_STATES.has(row.state)) {
-            continue;
-        }
-        const slotKey = queueRootSlotKey(row);
-        occupiedRoots.add(slotKey);
-        if (row.state !== "active" || row.job_id != null || launchRoots.has(slotKey)) {
-            continue;
-        }
-        launchRoots.add(slotKey);
-        launchQueueIds.push(row.queue_id);
-    }
-    const availableRootSlots = Math.max(0, maxActiveRoots - occupiedRoots.size);
-    const claimedRoots = new Set();
-    const activateQueueIds = [];
-    if (availableRootSlots > 0) {
-        for (const row of sorted) {
-            if (row.state !== "queued") {
-                continue;
-            }
-            const slotKey = queueRootSlotKey(row);
-            if (occupiedRoots.has(slotKey) || claimedRoots.has(slotKey)) {
-                continue;
-            }
-            claimedRoots.add(slotKey);
-            activateQueueIds.push(row.queue_id);
-            if (activateQueueIds.length >= availableRootSlots) {
-                break;
-            }
-        }
-    }
-    return {
-        policy,
-        max_active_roots: maxActiveRoots,
-        active_root_count: occupiedRoots.size,
-        available_root_slots: availableRootSlots,
-        activate_queue_ids: activateQueueIds,
-        launch_queue_ids: launchQueueIds,
-    };
-}

package/dist/run_queue.d.ts

@@ -1,95 +0,0 @@
-import type { JsonlStore } from "@femtomc/mu-core";
-import { type InterRootQueuePolicy, type InterRootQueueReconcilePlan, type OrchestrationQueueState } from "./orchestration_queue.js";
-import type { ControlPlaneRunMode, ControlPlaneRunSnapshot, ControlPlaneRunStatus } from "./run_supervisor.js";
-export type DurableRunQueueState = OrchestrationQueueState;
-export type DurableRunQueueSnapshot = {
-    v: 1;
-    queue_id: string;
-    dedupe_key: string;
-    mode: ControlPlaneRunMode;
-    state: DurableRunQueueState;
-    prompt: string | null;
-    root_issue_id: string | null;
-    max_steps: number;
-    command_id: string | null;
-    source: "command" | "api";
-    job_id: string | null;
-    started_at_ms: number | null;
-    updated_at_ms: number;
-    finished_at_ms: number | null;
-    exit_code: number | null;
-    pid: number | null;
-    last_progress: string | null;
-    created_at_ms: number;
-    revision: number;
-    applied_operation_ids: string[];
-};
-export type DurableRunQueueOpts = {
-    repoRoot: string;
-    nowMs?: () => number;
-    store?: JsonlStore<unknown>;
-    maxOperationIds?: number;
-};
-export type DurableRunQueueEnqueueOpts = {
-    mode: ControlPlaneRunMode;
-    prompt: string | null;
-    rootIssueId: string | null;
-    maxSteps?: number;
-    commandId?: string | null;
-    source: "command" | "api";
-    dedupeKey: string;
-    operationId?: string | null;
-    nowMs?: number;
-};
-export type DurableRunQueueTransitionOpts = {
-    queueId: string;
-    toState: DurableRunQueueState;
-    operationId?: string | null;
-    nowMs?: number;
-};
-export type DurableRunQueueClaimOpts = {
-    queueId?: string | null;
-    operationId?: string | null;
-    nowMs?: number;
-};
-export declare function runStatusFromQueueState(state: DurableRunQueueState): ControlPlaneRunStatus;
-export declare function queueStatesForRunStatusFilter(status: string | null | undefined): DurableRunQueueState[] | null;
-export type RunQueueReconcilePlan = InterRootQueueReconcilePlan;
-export declare const RUN_QUEUE_RECONCILE_INVARIANTS: readonly ["ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.", "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.", "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.", "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot."];
-/**
- * Server adapter wrapper around the orchestrator-owned inter-root planner.
- */
-export declare function reconcileRunQueue(rows: readonly DurableRunQueueSnapshot[], policy: InterRootQueuePolicy): RunQueueReconcilePlan;
-export declare function runQueuePath(repoRoot: string): string;
-export declare function runSnapshotFromQueueSnapshot(queue: DurableRunQueueSnapshot, runtime?: ControlPlaneRunSnapshot | null): ControlPlaneRunSnapshot;
-export declare class DurableRunQueue {
-    #private;
-    constructor(opts: DurableRunQueueOpts);
-    enqueue(opts: DurableRunQueueEnqueueOpts): Promise<DurableRunQueueSnapshot>;
-    claim(opts?: DurableRunQueueClaimOpts): Promise<DurableRunQueueSnapshot | null>;
-    activate(opts: DurableRunQueueClaimOpts): Promise<DurableRunQueueSnapshot | null>;
-    transition(opts: DurableRunQueueTransitionOpts): Promise<DurableRunQueueSnapshot>;
-    bindRunSnapshot(opts: {
-        queueId: string;
-        run: ControlPlaneRunSnapshot;
-        operationId?: string | null;
-        nowMs?: number;
-    }): Promise<DurableRunQueueSnapshot>;
-    applyRunSnapshot(opts: {
-        run: ControlPlaneRunSnapshot;
-        queueId?: string | null;
-        operationId?: string | null;
-        nowMs?: number;
-        createIfMissing?: boolean;
-    }): Promise<DurableRunQueueSnapshot | null>;
-    get(idOrRoot: string): Promise<DurableRunQueueSnapshot | null>;
-    list(opts?: {
-        states?: readonly DurableRunQueueState[];
-        limit?: number;
-    }): Promise<DurableRunQueueSnapshot[]>;
-    listRunSnapshots(opts?: {
-        status?: string;
-        limit?: number;
-        runtimeByJobId?: Map<string, ControlPlaneRunSnapshot>;
-    }): Promise<ControlPlaneRunSnapshot[]>;
-}