@femtomc/mu-server 26.2.69 → 26.2.71

package/dist/control_plane_bootstrap_helpers.d.ts

@@ -0,0 +1,16 @@
+import { type MessagingOperatorBackend, MessagingOperatorRuntime } from "@femtomc/mu-agent";
+import { ControlPlaneOutbox, type OutboxDeliveryHandlerResult, type OutboxDispatchOutcome, type OutboxRecord } from "@femtomc/mu-control-plane";
+import type { ControlPlaneConfig } from "./control_plane_contract.js";
+export declare function buildMessagingOperatorRuntime(opts: {
+    repoRoot: string;
+    config: ControlPlaneConfig;
+    backend?: MessagingOperatorBackend;
+}): MessagingOperatorRuntime | null;
+export declare function createOutboxDrainLoop(opts: {
+    outbox: ControlPlaneOutbox;
+    deliver: (record: OutboxRecord) => Promise<undefined | OutboxDeliveryHandlerResult>;
+    onOutcome?: (outcome: OutboxDispatchOutcome) => void | Promise<void>;
+}): {
+    scheduleOutboxDrain: () => void;
+    stop: () => void;
+};

package/dist/control_plane_bootstrap_helpers.js

@@ -0,0 +1,85 @@
+import { ApprovedCommandBroker, CommandContextResolver, MessagingOperatorRuntime, operatorExtensionPaths, PiMessagingOperatorBackend, } from "@femtomc/mu-agent";
+import { ControlPlaneOutboxDispatcher, } from "@femtomc/mu-control-plane";
+const OUTBOX_DRAIN_INTERVAL_MS = 500;
+export function buildMessagingOperatorRuntime(opts) {
+    if (!opts.config.operator.enabled) {
+        return null;
+    }
+    const backend = opts.backend ??
+        new PiMessagingOperatorBackend({
+            provider: opts.config.operator.provider ?? undefined,
+            model: opts.config.operator.model ?? undefined,
+            extensionPaths: operatorExtensionPaths,
+        });
+    return new MessagingOperatorRuntime({
+        backend,
+        broker: new ApprovedCommandBroker({
+            runTriggersEnabled: opts.config.operator.run_triggers_enabled,
+            contextResolver: new CommandContextResolver({ allowedRepoRoots: [opts.repoRoot] }),
+        }),
+        enabled: true,
+    });
+}
+export function createOutboxDrainLoop(opts) {
+    const dispatcher = new ControlPlaneOutboxDispatcher({
+        outbox: opts.outbox,
+        deliver: opts.deliver,
+    });
+    let drainingOutbox = false;
+    let drainRequested = false;
+    let stopped = false;
+    const drainOutboxNow = async () => {
+        if (stopped) {
+            return;
+        }
+        if (drainingOutbox) {
+            drainRequested = true;
+            return;
+        }
+        drainingOutbox = true;
+        try {
+            do {
+                drainRequested = false;
+                const outcomes = await dispatcher.drainDue();
+                if (opts.onOutcome) {
+                    for (const outcome of outcomes) {
+                        try {
+                            await opts.onOutcome(outcome);
+                        }
+                        catch {
+                            // Keep telemetry callbacks non-fatal.
+                        }
+                    }
+                }
+            } while (drainRequested && !stopped);
+        }
+        catch {
+            // Swallow errors — dispatcher handles retry progression internally.
+        }
+        finally {
+            drainingOutbox = false;
+        }
+    };
+    const scheduleOutboxDrain = () => {
+        if (stopped) {
+            return;
+        }
+        queueMicrotask(() => {
+            void drainOutboxNow();
+        });
+    };
+    const interval = setInterval(() => {
+        scheduleOutboxDrain();
+    }, OUTBOX_DRAIN_INTERVAL_MS);
+    scheduleOutboxDrain();
+    return {
+        scheduleOutboxDrain,
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(interval);
+        },
+    };
+}

package/dist/control_plane_contract.d.ts

@@ -0,0 +1,176 @@
+import type { Channel, CommandPipelineResult, ReloadableGenerationIdentity } from "@femtomc/mu-control-plane";
+import type { ControlPlaneRunHeartbeatResult, ControlPlaneRunInterruptResult, ControlPlaneRunSnapshot, ControlPlaneRunTrace } from "./run_supervisor.js";
+import type { MuConfig } from "./config.js";
+/**
+ * Boundary contracts for server/control-plane composition.
+ *
+ * Dependency direction:
+ * - Domain/application code should depend on these contracts.
+ * - Interface adapters in `control_plane.ts` implement these seams.
+ */
+export type ControlPlaneConfig = MuConfig["control_plane"];
+/**
+ * Durable orchestration queue contract (default-on path).
+ *
+ * Scheduler policy/state-machine primitives are owned by `@femtomc/mu-orchestrator` and
+ * re-exported here so existing server/control-plane callers keep a stable import surface.
+ */
+export type { InterRootQueuePolicy, OrchestrationQueueState } from "@femtomc/mu-orchestrator";
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, } from "@femtomc/mu-orchestrator";
+export type ActiveAdapter = {
+    name: Channel;
+    route: string;
+};
+export type TelegramGenerationRollbackTrigger = "manual" | "warmup_failed" | "health_gate_failed" | "cutover_failed" | "post_cutover_health_failed" | "rollback_unavailable" | "rollback_failed";
+export type TelegramGenerationReloadResult = {
+    handled: boolean;
+    ok: boolean;
+    reason: string;
+    route: string;
+    from_generation: ReloadableGenerationIdentity | null;
+    to_generation: ReloadableGenerationIdentity | null;
+    active_generation: ReloadableGenerationIdentity | null;
+    warmup: {
+        ok: boolean;
+        elapsed_ms: number;
+        error?: string;
+    } | null;
+    cutover: {
+        ok: boolean;
+        elapsed_ms: number;
+        error?: string;
+    } | null;
+    drain: {
+        ok: boolean;
+        elapsed_ms: number;
+        timed_out: boolean;
+        forced_stop: boolean;
+        error?: string;
+    } | null;
+    rollback: {
+        requested: boolean;
+        trigger: TelegramGenerationRollbackTrigger | null;
+        attempted: boolean;
+        ok: boolean;
+        error?: string;
+    };
+    error?: string;
+};
+export type ControlPlaneGenerationContext = ReloadableGenerationIdentity;
+export type TelegramGenerationSwapHooks = {
+    onWarmup?: (ctx: {
+        generation: ReloadableGenerationIdentity;
+        reason: string;
+    }) => void | Promise<void>;
+    onCutover?: (ctx: {
+        from_generation: ReloadableGenerationIdentity | null;
+        to_generation: ReloadableGenerationIdentity;
+        reason: string;
+    }) => void | Promise<void>;
+    onDrain?: (ctx: {
+        generation: ReloadableGenerationIdentity;
+        reason: string;
+        timeout_ms: number;
+    }) => void | Promise<void>;
+};
+export type ControlPlaneSessionMutationAction = "reload" | "update";
+export type ControlPlaneSessionMutationResult = {
+    ok: boolean;
+    action: ControlPlaneSessionMutationAction;
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type ControlPlaneSessionLifecycle = {
+    reload: () => Promise<ControlPlaneSessionMutationResult>;
+    update: () => Promise<ControlPlaneSessionMutationResult>;
+};
+export type WakeDeliveryState = "queued" | "duplicate" | "skipped" | "delivered" | "retried" | "dead_letter";
+export type WakeNotifyDecision = {
+    state: "queued" | "duplicate" | "skipped";
+    reason_code: string;
+    binding_id: string;
+    channel: Channel;
+    dedupe_key: string;
+    outbox_id: string | null;
+};
+export type WakeNotifyContext = {
+    wakeId: string;
+    wakeSource?: string | null;
+    programId?: string | null;
+    sourceTsMs?: number | null;
+};
+export type NotifyOperatorsOpts = {
+    message: string;
+    dedupeKey: string;
+    wake?: WakeNotifyContext | null;
+    metadata?: Record<string, unknown>;
+};
+export type NotifyOperatorsResult = {
+    queued: number;
+    duplicate: number;
+    skipped: number;
+    decisions: WakeNotifyDecision[];
+};
+export type WakeDeliveryEvent = {
+    state: "delivered" | "retried" | "dead_letter";
+    reason_code: string;
+    wake_id: string;
+    dedupe_key: string;
+    binding_id: string;
+    channel: Channel;
+    outbox_id: string;
+    outbox_dedupe_key: string;
+    attempt_count: number;
+};
+export type WakeDeliveryObserver = (event: WakeDeliveryEvent) => void | Promise<void>;
+export type ControlPlaneHandle = {
+    activeAdapters: ActiveAdapter[];
+    handleWebhook(path: string, req: Request): Promise<Response | null>;
+    notifyOperators?(opts: NotifyOperatorsOpts): Promise<NotifyOperatorsResult>;
+    setWakeDeliveryObserver?(observer: WakeDeliveryObserver | null): void;
+    reloadTelegramGeneration?(opts: {
+        config: ControlPlaneConfig;
+        reason: string;
+    }): Promise<TelegramGenerationReloadResult>;
+    listRuns?(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<ControlPlaneRunSnapshot[]>;
+    getRun?(idOrRoot: string): Promise<ControlPlaneRunSnapshot | null>;
+    /**
+     * Run lifecycle boundary: accepts start intent into the default queue/reconcile path.
+     * Compatibility adapters may dispatch immediately after enqueue, but must preserve queue invariants.
+     */
+    startRun?(opts: {
+        prompt: string;
+        maxSteps?: number;
+    }): Promise<ControlPlaneRunSnapshot>;
+    /**
+     * Run lifecycle boundary: accepts resume intent into the default queue/reconcile path.
+     * No flag-based alternate path is allowed.
+     */
+    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;
+        wakeMode?: string | null;
+    }): Promise<ControlPlaneRunHeartbeatResult>;
+    traceRun?(opts: {
+        idOrRoot: string;
+        limit?: number;
+    }): Promise<ControlPlaneRunTrace | null>;
+    submitTerminalCommand?(opts: {
+        commandText: string;
+        repoRoot: string;
+        requestId?: string;
+    }): Promise<CommandPipelineResult>;
+    stop(): Promise<void>;
+};

package/dist/control_plane_contract.js

@@ -0,0 +1 @@
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, } from "@femtomc/mu-orchestrator";

package/dist/control_plane_reload.d.ts

@@ -0,0 +1,63 @@
+import { GenerationTelemetryRecorder, type ReloadableGenerationIdentity, type ReloadLifecycleReason } from "@femtomc/mu-control-plane";
+import type { ControlPlaneConfig, ControlPlaneHandle, TelegramGenerationReloadResult } from "./control_plane_contract.js";
+import { ControlPlaneGenerationSupervisor } from "./generation_supervisor.js";
+export type ControlPlaneSummary = {
+    active: boolean;
+    adapters: string[];
+    routes: Array<{
+        name: string;
+        route: string;
+    }>;
+};
+export type ControlPlaneReloadResult = {
+    ok: boolean;
+    reason: string;
+    previous_control_plane: ControlPlaneSummary;
+    control_plane: ControlPlaneSummary;
+    generation: {
+        attempt_id: string;
+        coalesced: boolean;
+        from_generation: ReloadableGenerationIdentity | null;
+        to_generation: ReloadableGenerationIdentity;
+        active_generation: ReloadableGenerationIdentity | null;
+        outcome: "success" | "failure";
+    };
+    telegram_generation?: TelegramGenerationReloadResult;
+    error?: string;
+};
+export type ControlPlaneReloader = (opts: {
+    repoRoot: string;
+    previous: ControlPlaneHandle | null;
+    config: ControlPlaneConfig;
+    generation: ReloadableGenerationIdentity;
+}) => Promise<ControlPlaneHandle | null>;
+export type ConfigReader = (repoRoot: string) => Promise<import("./config.js").MuConfig>;
+export type ConfigWriter = (repoRoot: string, config: import("./config.js").MuConfig) => Promise<string>;
+export declare function summarizeControlPlane(handle: ControlPlaneHandle | null): ControlPlaneSummary;
+export type ReloadManagerDeps = {
+    repoRoot: string;
+    initialControlPlane: ControlPlaneHandle | null;
+    controlPlaneReloader: ControlPlaneReloader;
+    generationTelemetry: GenerationTelemetryRecorder;
+    loadConfigFromDisk: () => Promise<import("./config.js").MuConfig>;
+};
+export type ReloadManager = {
+    reloadControlPlane: (reason: ReloadLifecycleReason) => Promise<ControlPlaneReloadResult>;
+    getControlPlaneStatus: () => {
+        active: boolean;
+        adapters: string[];
+        routes: Array<{
+            name: string;
+            route: string;
+        }>;
+        generation: import("@femtomc/mu-control-plane").GenerationSupervisorSnapshot;
+        observability: {
+            counters: ReturnType<GenerationTelemetryRecorder["counters"]>;
+        };
+    };
+    getControlPlaneCurrent: () => ControlPlaneHandle | null;
+    setControlPlaneCurrent: (handle: ControlPlaneHandle | null) => void;
+    generationSupervisor: ControlPlaneGenerationSupervisor;
+    generationTelemetry: GenerationTelemetryRecorder;
+};
+export declare function createReloadManager(deps: ReloadManagerDeps): ReloadManager;