@femtomc/mu-server 26.2.103 → 26.2.105

package/README.md

@@ -37,6 +37,11 @@ Use `mu store paths --pretty` to resolve `<store>` for the active repo/workspace
 
 ## API Endpoints
 
+> Security note: `mu-server` is designed for trusted local/operator environments.
+> The HTTP surface does not provide built-in authn/authz middleware for `/api/*`.
+> Do not expose this port directly to untrusted networks without an external
+> auth/reverse-proxy layer.
+
 ### Health Check
 
 - `GET /healthz` or `GET /health` - Returns 200 OK
@@ -135,6 +140,7 @@ Use `mu store paths --pretty` to resolve `<store>` for the active repo/workspace
 ### Control-plane Coordination Endpoints
 
 - Scheduling + coordination:
+  - `GET /api/heartbeats/status` (heartbeat scheduler summary: total/enabled/armed)
   - `GET|POST|PATCH|DELETE /api/heartbeats...`
   - `GET|POST|PATCH|DELETE /api/cron...`
   - Heartbeat programs support an optional free-form `prompt` field; when present it becomes the primary wake instruction sent to the operator turn path.

package/dist/api/heartbeats.js

@@ -1,5 +1,12 @@
 export async function heartbeatRoutes(request, url, deps, headers) {
     const path = url.pathname;
+    if (path === "/api/heartbeats/status") {
+        if (request.method !== "GET") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        const status = await deps.heartbeatPrograms.status();
+        return Response.json(status, { headers });
+    }
     if (path === "/api/heartbeats") {
         if (request.method !== "GET") {
             return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });

package/dist/heartbeat_programs.d.ts

@@ -15,6 +15,24 @@ export type HeartbeatProgramSnapshot = {
     last_result: "ok" | "coalesced" | "failed" | null;
     last_error: string | null;
 };
+export type HeartbeatProgramLifecycleAction = "created" | "updated" | "deleted";
+export type HeartbeatProgramLifecycleEvent = {
+    ts_ms: number;
+    action: HeartbeatProgramLifecycleAction;
+    program_id: string;
+    message: string;
+    program: HeartbeatProgramSnapshot | null;
+};
+export type HeartbeatProgramStatusSnapshot = {
+    count: number;
+    enabled_count: number;
+    armed_count: number;
+    armed: Array<{
+        program_id: string;
+        every_ms: number;
+        last_triggered_at_ms: number | null;
+    }>;
+};
 export type HeartbeatProgramOperationResult = {
     ok: boolean;
     reason: "not_found" | "missing_target" | "not_running" | "failed" | null;
@@ -52,6 +70,7 @@ export type HeartbeatProgramRegistryOpts = {
         triggeredAtMs: number;
     }) => Promise<HeartbeatProgramDispatchResult>;
     onTickEvent?: (event: HeartbeatProgramTickEvent) => void | Promise<void>;
+    onLifecycleEvent?: (event: HeartbeatProgramLifecycleEvent) => void | Promise<void>;
 };
 export declare class HeartbeatProgramRegistry {
     #private;
@@ -60,6 +79,7 @@ export declare class HeartbeatProgramRegistry {
         enabled?: boolean;
         limit?: number;
     }): Promise<HeartbeatProgramSnapshot[]>;
+    status(): Promise<HeartbeatProgramStatusSnapshot>;
     get(programId: string): Promise<HeartbeatProgramSnapshot | null>;
     create(opts: {
         title: string;

package/dist/heartbeat_programs.js

@@ -72,6 +72,7 @@ export class HeartbeatProgramRegistry {
     #heartbeatScheduler;
     #dispatchWake;
     #onTickEvent;
+    #onLifecycleEvent;
     #nowMs;
     #programs = new Map();
     #loaded = null;
@@ -79,10 +80,14 @@ export class HeartbeatProgramRegistry {
         this.#heartbeatScheduler = opts.heartbeatScheduler;
         this.#dispatchWake = opts.dispatchWake;
         this.#onTickEvent = opts.onTickEvent;
+        this.#onLifecycleEvent = opts.onLifecycleEvent;
         this.#nowMs = opts.nowMs ?? defaultNowMs;
         this.#store =
             opts.store ??
                 new FsJsonlStore(join(getStorePaths(opts.repoRoot).storeDir, HEARTBEAT_PROGRAMS_FILENAME));
+        void this.#ensureLoaded().catch(() => {
+            // Best effort eager load for startup re-arming.
+        });
     }
     #scheduleId(programId) {
         return `heartbeat-program:${programId}`;
@@ -93,6 +98,16 @@ export class HeartbeatProgramRegistry {
             metadata: { ...program.metadata },
         };
     }
+    #normalizeEveryMs(raw) {
+        if (!Number.isFinite(raw)) {
+            return 0;
+        }
+        const normalized = Math.max(0, Math.trunc(raw));
+        if (normalized <= 0) {
+            return 0;
+        }
+        return Math.max(this.#heartbeatScheduler.getMinIntervalMs(), normalized);
+    }
     async #ensureLoaded() {
         if (!this.#loaded) {
             this.#loaded = this.#load();
@@ -106,6 +121,7 @@ export class HeartbeatProgramRegistry {
             if (!normalized) {
                 continue;
             }
+            normalized.every_ms = this.#normalizeEveryMs(normalized.every_ms);
             this.#programs.set(normalized.program_id, normalized);
         }
         for (const program of this.#programs.values()) {
@@ -118,6 +134,7 @@ export class HeartbeatProgramRegistry {
     }
     #applySchedule(program) {
         const scheduleId = this.#scheduleId(program.program_id);
+        program.every_ms = this.#normalizeEveryMs(program.every_ms);
         if (!program.enabled || program.every_ms <= 0) {
             this.#heartbeatScheduler.unregister(scheduleId);
             return;
@@ -136,6 +153,12 @@ export class HeartbeatProgramRegistry {
         }
         await this.#onTickEvent(event);
     }
+    async #emitLifecycleEvent(event) {
+        if (!this.#onLifecycleEvent) {
+            return;
+        }
+        await this.#onLifecycleEvent(event);
+    }
     async #tickProgram(programId, reason) {
         const program = this.#programs.get(programId);
         if (!program) {
@@ -217,6 +240,28 @@ export class HeartbeatProgramRegistry {
             .slice(0, limit)
             .map((program) => this.#snapshot(program));
     }
+    async status() {
+        await this.#ensureLoaded();
+        const programs = sortPrograms([...this.#programs.values()]);
+        const armed = programs
+            .filter((program) => {
+            if (!program.enabled || program.every_ms <= 0) {
+                return false;
+            }
+            return this.#heartbeatScheduler.has(this.#scheduleId(program.program_id));
+        })
+            .map((program) => ({
+            program_id: program.program_id,
+            every_ms: program.every_ms,
+            last_triggered_at_ms: program.last_triggered_at_ms,
+        }));
+        return {
+            count: programs.length,
+            enabled_count: programs.filter((program) => program.enabled).length,
+            armed_count: armed.length,
+            armed,
+        };
+    }
     async get(programId) {
         await this.#ensureLoaded();
         const program = this.#programs.get(programId.trim());
@@ -235,9 +280,7 @@ export class HeartbeatProgramRegistry {
             title,
             prompt: normalizePrompt(opts.prompt),
             enabled: opts.enabled !== false,
-            every_ms: typeof opts.everyMs === "number" && Number.isFinite(opts.everyMs)
-                ? Math.max(0, Math.trunc(opts.everyMs))
-                : 15_000,
+            every_ms: this.#normalizeEveryMs(typeof opts.everyMs === "number" && Number.isFinite(opts.everyMs) ? opts.everyMs : 15_000),
             reason: opts.reason?.trim() || "scheduled",
             metadata: sanitizeMetadata(opts.metadata),
             created_at_ms: nowMs,
@@ -249,7 +292,17 @@ export class HeartbeatProgramRegistry {
         this.#programs.set(program.program_id, program);
         this.#applySchedule(program);
         await this.#persist();
-        return this.#snapshot(program);
+        const snapshot = this.#snapshot(program);
+        await this.#emitLifecycleEvent({
+            ts_ms: nowMs,
+            action: "created",
+            program_id: program.program_id,
+            message: `heartbeat program created: ${program.title}`,
+            program: snapshot,
+        }).catch(() => {
+            // best effort only
+        });
+        return snapshot;
     }
     async update(opts) {
         await this.#ensureLoaded();
@@ -268,7 +321,7 @@ export class HeartbeatProgramRegistry {
             program.prompt = normalizePrompt(opts.prompt);
         }
         if (typeof opts.everyMs === "number" && Number.isFinite(opts.everyMs)) {
-            program.every_ms = Math.max(0, Math.trunc(opts.everyMs));
+            program.every_ms = this.#normalizeEveryMs(opts.everyMs);
         }
         if (typeof opts.reason === "string") {
             program.reason = opts.reason.trim() || "scheduled";
@@ -279,10 +332,21 @@ export class HeartbeatProgramRegistry {
         if (opts.metadata) {
             program.metadata = sanitizeMetadata(opts.metadata);
         }
-        program.updated_at_ms = Math.trunc(this.#nowMs());
+        const nowMs = Math.trunc(this.#nowMs());
+        program.updated_at_ms = nowMs;
         this.#applySchedule(program);
         await this.#persist();
-        return { ok: true, reason: null, program: this.#snapshot(program) };
+        const snapshot = this.#snapshot(program);
+        await this.#emitLifecycleEvent({
+            ts_ms: nowMs,
+            action: "updated",
+            program_id: program.program_id,
+            message: `heartbeat program updated: ${program.title}`,
+            program: snapshot,
+        }).catch(() => {
+            // best effort only
+        });
+        return { ok: true, reason: null, program: snapshot };
     }
     async remove(programId) {
         await this.#ensureLoaded();
@@ -294,10 +358,20 @@ export class HeartbeatProgramRegistry {
         if (!program) {
             return { ok: false, reason: "not_found", program: null };
         }
+        const removed = this.#snapshot(program);
         this.#heartbeatScheduler.unregister(this.#scheduleId(program.program_id));
         this.#programs.delete(normalizedId);
         await this.#persist();
-        return { ok: true, reason: null, program: this.#snapshot(program) };
+        await this.#emitLifecycleEvent({
+            ts_ms: Math.trunc(this.#nowMs()),
+            action: "deleted",
+            program_id: removed.program_id,
+            message: `heartbeat program deleted: ${removed.title}`,
+            program: removed,
+        }).catch(() => {
+            // best effort only
+        });
+        return { ok: true, reason: null, program: removed };
     }
     async trigger(opts) {
         await this.#ensureLoaded();

package/dist/heartbeat_scheduler.d.ts

@@ -34,5 +34,6 @@ export declare class ActivityHeartbeatScheduler {
     unregister(activityIdRaw: string): boolean;
     has(activityIdRaw: string): boolean;
     listActivityIds(): string[];
+    getMinIntervalMs(): number;
     stop(): void;
 }

package/dist/heartbeat_scheduler.js

@@ -272,6 +272,9 @@ export class ActivityHeartbeatScheduler {
     listActivityIds() {
         return [...this.#states.keys()];
     }
+    getMinIntervalMs() {
+        return this.#minIntervalMs;
+    }
     stop() {
         for (const state of this.#states.values()) {
             this.#disposeState(state);

package/dist/server.js

@@ -10,6 +10,9 @@ import { createServerProgramCoordination } from "./server_program_coordination.j
 import { createServerRequestHandler } from "./server_routing.js";
 import { toNonNegativeInt } from "./server_types.js";
 const DEFAULT_OPERATOR_WAKE_COALESCE_MS = 2_000;
+const OPERATOR_WAKE_DEDUPE_MAP_MAX_ENTRIES = 2_048;
+const OPERATOR_WAKE_DEDUPE_MIN_RETENTION_MS = 60_000;
+const OPERATOR_WAKE_DEDUPE_PRUNE_INTERVAL_MS = 15_000;
 export { createProcessSessionLifecycle };
 function describeError(err) {
     if (err instanceof Error)
@@ -101,6 +104,30 @@ function buildWakeTurnIngressText(opts) {
         "Respond conversationally with exactly one concise operator message suitable for immediate broadcast.",
     ].join("\n");
 }
+function pruneOperatorWakeDedupeMap(opts) {
+    if (opts.map.size === 0) {
+        return opts.lastPrunedAtMs;
+    }
+    const shouldPruneByTime = opts.nowMs - opts.lastPrunedAtMs >= OPERATOR_WAKE_DEDUPE_PRUNE_INTERVAL_MS;
+    const shouldPruneBySize = opts.map.size > OPERATOR_WAKE_DEDUPE_MAP_MAX_ENTRIES;
+    if (!shouldPruneByTime && !shouldPruneBySize) {
+        return opts.lastPrunedAtMs;
+    }
+    const retentionMs = Math.max(OPERATOR_WAKE_DEDUPE_MIN_RETENTION_MS, Math.max(0, opts.coalesceMs) * 4);
+    for (const [dedupeKey, tsMs] of opts.map.entries()) {
+        if (opts.nowMs - tsMs >= retentionMs) {
+            opts.map.delete(dedupeKey);
+        }
+    }
+    while (opts.map.size > OPERATOR_WAKE_DEDUPE_MAP_MAX_ENTRIES) {
+        const oldest = opts.map.keys().next().value;
+        if (typeof oldest !== "string" || oldest.length === 0) {
+            break;
+        }
+        opts.map.delete(oldest);
+    }
+    return opts.nowMs;
+}
 export function createContext(repoRoot) {
     const paths = getStorePaths(repoRoot);
     const eventsStore = new FsJsonlStore(paths.eventsPath);
@@ -118,6 +145,7 @@ function createServer(options = {}) {
     const heartbeatScheduler = options.heartbeatScheduler ?? new ActivityHeartbeatScheduler();
     const operatorWakeCoalesceMs = toNonNegativeInt(options.operatorWakeCoalesceMs, DEFAULT_OPERATOR_WAKE_COALESCE_MS);
     const operatorWakeLastByKey = new Map();
+    let operatorWakeDedupeLastPrunedAtMs = 0;
     const sessionLifecycle = options.sessionLifecycle ?? createProcessSessionLifecycle({ repoRoot });
     const emitWakeDeliveryEvent = async (payload) => {
         await context.eventLog.emit("operator.wake.delivery", {
@@ -132,6 +160,12 @@ function createServer(options = {}) {
         }
         const nowMs = Date.now();
         const coalesceMs = Math.max(0, Math.trunc(opts.coalesceMs ?? operatorWakeCoalesceMs));
+        operatorWakeDedupeLastPrunedAtMs = pruneOperatorWakeDedupeMap({
+            nowMs,
+            coalesceMs,
+            map: operatorWakeLastByKey,
+            lastPrunedAtMs: operatorWakeDedupeLastPrunedAtMs,
+        });
         const previous = operatorWakeLastByKey.get(dedupeKey);
         if (typeof previous === "number" && nowMs - previous < coalesceMs) {
             return { status: "coalesced", reason: "coalesced_window" };

package/dist/server_program_coordination.js

@@ -33,6 +33,17 @@ export function createServerProgramCoordination(opts) {
             }
             return { status: "ok" };
         },
+        onLifecycleEvent: async (event) => {
+            await opts.eventLog.emit("heartbeat_program.lifecycle", {
+                source: "mu-server.heartbeat-programs",
+                payload: {
+                    action: event.action,
+                    program_id: event.program_id,
+                    message: event.message,
+                    program: event.program,
+                },
+            });
+        },
         onTickEvent: async (event) => {
             await opts.eventLog.emit("heartbeat_program.tick", {
                 source: "mu-server.heartbeat-programs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-server",
-  "version": "26.2.103",
+  "version": "26.2.105",
   "description": "HTTP API server for mu control-plane transport/session plus run/activity scheduling coordination.",
   "keywords": [
     "mu",
@@ -30,8 +30,8 @@
     "start": "bun run dist/cli.js"
   },
   "dependencies": {
-    "@femtomc/mu-agent": "26.2.103",
-    "@femtomc/mu-control-plane": "26.2.103",
-    "@femtomc/mu-core": "26.2.103"
+    "@femtomc/mu-agent": "26.2.105",
+    "@femtomc/mu-control-plane": "26.2.105",
+    "@femtomc/mu-core": "26.2.105"
   }
 }