@femtomc/mu-server 26.2.55 → 26.2.56

package/README.md

@@ -34,7 +34,7 @@ Bun.serve(server);
 
 ### Status
 
-- `GET /api/status` - Returns repository status
+- `GET /api/status` - Returns repository + control-plane runtime status
   ```json
   {
     "repo_root": "/path/to/repo",
@@ -43,7 +43,32 @@ Bun.serve(server);
     "control_plane": {
       "active": true,
       "adapters": ["slack"],
-      "routes": [{ "name": "slack", "route": "/webhooks/slack" }]
+      "routes": [{ "name": "slack", "route": "/webhooks/slack" }],
+      "generation": {
+        "supervisor_id": "control-plane",
+        "active_generation": { "generation_id": "control-plane-gen-3", "generation_seq": 3 },
+        "pending_reload": null,
+        "last_reload": {
+          "attempt_id": "control-plane-reload-4",
+          "reason": "mu_setup_apply_slack",
+          "state": "completed",
+          "requested_at_ms": 0,
+          "swapped_at_ms": 0,
+          "finished_at_ms": 0,
+          "from_generation": { "generation_id": "control-plane-gen-2", "generation_seq": 2 },
+          "to_generation": { "generation_id": "control-plane-gen-3", "generation_seq": 3 }
+        }
+      },
+      "observability": {
+        "counters": {
+          "reload_success_total": 4,
+          "reload_failure_total": 0,
+          "reload_drain_duration_ms_total": 73,
+          "reload_drain_duration_samples_total": 4,
+          "duplicate_signal_total": 0,
+          "drop_signal_total": 0
+        }
+      }
     }
   }
   ```
@@ -64,12 +89,15 @@ Bun.serve(server);
     }
   }
   ```
-- `POST /api/control-plane/reload` - Re-bootstrap control-plane adapters in-process
-  - Re-reads current config from `.mu/config.json` and re-mounts adapters without restarting
+- `POST /api/control-plane/reload` - Trigger generation-scoped control-plane hot reload
+  - Re-reads current config from `.mu/config.json` and executes warmup/cutover/drain/rollback flow
+  - Coalesces concurrent requests onto a single in-flight attempt
   - Body (optional):
   ```json
   { "reason": "mu_setup_apply" }
   ```
+  - Response includes generation metadata and, when telegram generation handling runs, `telegram_generation` lifecycle detail.
+- `POST /api/control-plane/rollback` - Explicit rollback trigger (same pipeline, reason=`rollback`)
 
 ### Issues
 
@@ -169,6 +197,7 @@ The server uses:
 - IssueStore and ForumStore from mu packages
 - Bun's built-in HTTP server
 - Simple REST-style JSON API
+- Generation-supervised control-plane hot reload lifecycle (see `docs/adr-0001-control-plane-hot-reload.md`)
 
 All data is persisted to `.mu/` directory:
 - `.mu/issues.jsonl` - Issue data

package/dist/control_plane.d.ts

@@ -1,15 +1,54 @@
 import { type MessagingOperatorBackend, MessagingOperatorRuntime } from "@femtomc/mu-agent";
-import { type Channel } from "@femtomc/mu-control-plane";
+import { type Channel, type GenerationTelemetryRecorder, type ReloadableGenerationIdentity } 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";
+import { type ControlPlaneRunHeartbeatResult, type ControlPlaneRunInterruptResult, type ControlPlaneRunSnapshot, type ControlPlaneRunTrace } from "./run_supervisor.js";
 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 ControlPlaneHandle = {
     activeAdapters: ActiveAdapter[];
     handleWebhook(path: string, req: Request): Promise<Response | null>;
+    reloadTelegramGeneration?(opts: {
+        config: ControlPlaneConfig;
+        reason: string;
+    }): Promise<TelegramGenerationReloadResult>;
     listRuns?(opts?: {
         status?: string;
         limit?: number;
@@ -39,6 +78,23 @@ export type ControlPlaneHandle = {
     stop(): Promise<void>;
 };
 export type ControlPlaneConfig = MuConfig["control_plane"];
+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>;
+};
 type DetectedAdapter = {
     name: "slack";
     signingSecret: string;
@@ -76,6 +132,9 @@ export type BootstrapControlPlaneOpts = {
     operatorRuntime?: MessagingOperatorRuntime | null;
     operatorBackend?: MessagingOperatorBackend;
     heartbeatScheduler?: ActivityHeartbeatScheduler;
+    generation?: ControlPlaneGenerationContext;
+    telemetry?: GenerationTelemetryRecorder | null;
+    telegramGenerationHooks?: TelegramGenerationSwapHooks;
 };
 export declare function bootstrapControlPlane(opts: BootstrapControlPlaneOpts): Promise<ControlPlaneHandle | null>;
 export {};