om-memory-system 3.6.0-next.39 → 3.6.0-next.40

package/dist/services/web-ensure.d.ts

@@ -0,0 +1,59 @@
+export type EnsureResult = "running" | "started" | "disabled" | "port-busy" | "no-runtime" | "start-timeout";
+/** Port and switch of the web app, as the caller read them from `CONFIG`. */
+export interface EnsureSettings {
+    enabled: boolean;
+    baseUrl: string;
+}
+interface SpawnedChild {
+    unref(): void;
+    on(event: "error", listener: (error: Error) => void): unknown;
+}
+type SpawnFn = (command: string, args: string[], options: {
+    detached: true;
+    stdio: "ignore";
+    cwd: string;
+    windowsHide: true;
+}) => SpawnedChild;
+/** The three file operations the start lock needs. */
+export interface LockFs {
+    /** Create the file only when it does not exist. Returns false when it does. */
+    createExclusive(path: string, text: string): boolean;
+    read(path: string): string | null;
+    remove(path: string): void;
+}
+export interface EnsureDeps {
+    fetch: typeof fetch;
+    spawn: SpawnFn;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    resolveRuntime: () => Promise<string | null> | string | null;
+    /** The `om-memory-system` script that `web` is run from. */
+    cliScript: string;
+    lockPath: string;
+    lockFs: LockFs;
+    pidAlive: (pid: number) => boolean;
+    /** The pid written into the lock. */
+    pid: number;
+    log: (message: string, data: Record<string, unknown>) => void | Promise<void>;
+}
+export interface EnsureOptions {
+    settings: EnsureSettings;
+    /** How long the caller may wait for the web app to answer. */
+    budgetMs: number;
+    /** `false` starts the web app and returns at once (session starts). Default `true`. */
+    wait?: boolean;
+    deps?: Partial<EnsureDeps>;
+}
+/** A lock older than this is stale. Also the longest a background start holds it. */
+export declare const START_LOCK_STALE_MS = 20000;
+/** Path of the start lock; the standalone command writes it for a restart copy. */
+export declare function startLockPath(home?: string): string;
+export declare const nodeLockFs: LockFs;
+/** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */
+export declare function removeStartLockFor(pid: number, path?: string, lockFs?: LockFs): void;
+/**
+ * Use a running OMMS web app, or start one detached `om-memory-system web`.
+ * Never throws; a failed check must not block or fail the host session.
+ */
+export declare function ensureWebApp(options: EnsureOptions): Promise<EnsureResult>;
+export {};

package/dist/services/web-ensure.js

@@ -0,0 +1,214 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const HEALTH_PROBE_MS = 1_000;
+const POLL_INTERVAL_MS = 250;
+/** A lock older than this is stale. Also the longest a background start holds it. */
+export const START_LOCK_STALE_MS = 20_000;
+/** Path of the start lock; the standalone command writes it for a restart copy. */
+export function startLockPath(home = homedir()) {
+    return join(home, ".omms", "web-start.lock");
+}
+export const nodeLockFs = {
+    createExclusive(path, text) {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        try {
+            writeFileSync(path, text, { flag: "wx", mode: 0o600 });
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    },
+    read(path) {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+};
+/** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */
+export function removeStartLockFor(pid, path = startLockPath(), lockFs = nodeLockFs) {
+    try {
+        const held = JSON.parse(lockFs.read(path) ?? "null");
+        if (held?.pid === pid)
+            lockFs.remove(path);
+    }
+    catch {
+        /* An unreadable lock is stale and the next caller replaces it. */
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to someone else.
+        return error.code === "EPERM";
+    }
+}
+function productionDefaults() {
+    return {
+        fetch: globalThis.fetch,
+        spawn: nodeSpawn,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        resolveRuntime: async () => (await import("./web-autostart.js")).resolveWebRuntime(),
+        // From dist/services/ to the CLI entry point.
+        cliScript: fileURLToPath(new URL("../cli/index.js", import.meta.url)),
+        lockPath: startLockPath(),
+        lockFs: nodeLockFs,
+        pidAlive: processAlive,
+        pid: process.pid,
+        log: async (message, data) => (await import("./logger.js")).log(message, data),
+    };
+}
+/** An OMMS reply is `{ success: true, status: "ok" }`; another local service must not count. */
+async function probe(baseUrl, timeoutMs, deps) {
+    try {
+        const response = await deps.fetch(`${baseUrl}/api/health`, {
+            method: "GET",
+            signal: AbortSignal.timeout(Math.max(1, timeoutMs)),
+        });
+        if (!response.ok)
+            return "other";
+        const body = (await response.json());
+        return body.success === true && body.status === "ok" ? "omms" : "other";
+    }
+    catch (error) {
+        // A reply that is not JSON came from a program that answered; a refused or
+        // timed out connection means nothing answers.
+        return error instanceof SyntaxError ? "other" : "none";
+    }
+}
+function lockIsStale(text, deps) {
+    if (text === null)
+        return true;
+    try {
+        const { pid, at } = JSON.parse(text);
+        if (typeof pid !== "number" || typeof at !== "number")
+            return true;
+        return !deps.pidAlive(pid) || deps.now() - at > START_LOCK_STALE_MS;
+    }
+    catch {
+        return true;
+    }
+}
+/** Take the start lock. A stale lock is removed and taken once more. */
+function takeLock(deps) {
+    const mine = JSON.stringify({ pid: deps.pid, at: deps.now() });
+    if (deps.lockFs.createExclusive(deps.lockPath, mine))
+        return true;
+    const seen = deps.lockFs.read(deps.lockPath);
+    if (!lockIsStale(seen, deps))
+        return false;
+    // Another caller may have replaced the stale lock since it was read.
+    if (deps.lockFs.read(deps.lockPath) !== seen)
+        return false;
+    deps.lockFs.remove(deps.lockPath);
+    return deps.lockFs.createExclusive(deps.lockPath, mine);
+}
+/**
+ * Use a running OMMS web app, or start one detached `om-memory-system web`.
+ * Never throws; a failed check must not block or fail the host session.
+ */
+export async function ensureWebApp(options) {
+    const { settings, budgetMs, wait = true } = options;
+    if (!settings.enabled)
+        return "disabled";
+    const deps = { ...productionDefaults(), ...options.deps };
+    const began = deps.now();
+    const remaining = () => budgetMs - (deps.now() - began);
+    const probeMs = () => budgetMs > 0 ? Math.min(HEALTH_PROBE_MS, Math.max(1, remaining())) : HEALTH_PROBE_MS;
+    const logCode = async (code) => {
+        try {
+            await deps.log("Web app ensure", { code });
+        }
+        catch {
+            /* A failed log line must not break the host. */
+        }
+    };
+    let held = false;
+    try {
+        const first = await probe(settings.baseUrl, probeMs(), deps);
+        if (first === "omms")
+            return "running";
+        if (first === "other") {
+            await logCode("port-busy");
+            return "port-busy";
+        }
+        const runtime = await deps.resolveRuntime();
+        if (!runtime) {
+            await logCode("no-runtime");
+            return "no-runtime";
+        }
+        held = takeLock(deps);
+        if (!held)
+            return await waitForOther(settings.baseUrl, wait, remaining, deps);
+        // Another caller may have finished its start before this one took the lock.
+        const second = await probe(settings.baseUrl, probeMs(), deps);
+        if (second === "omms")
+            return "running";
+        if (second === "other") {
+            await logCode("port-busy");
+            return "port-busy";
+        }
+        const child = deps.spawn(runtime, [deps.cliScript, "web"], {
+            detached: true,
+            stdio: "ignore",
+            cwd: homedir(),
+            windowsHide: true,
+        });
+        // A missing runtime reports through this event; polling then runs out.
+        child.on("error", () => undefined);
+        child.unref();
+        if (!wait) {
+            // Keep the lock until the web app answers, so a second host waits for it.
+            const releaseWhenUp = pollUntilUp(settings.baseUrl, START_LOCK_STALE_MS, deps)
+                .catch(() => false)
+                .finally(() => removeStartLockFor(deps.pid, deps.lockPath, deps.lockFs));
+            void releaseWhenUp;
+            held = false;
+            return "started";
+        }
+        const up = await pollUntilUp(settings.baseUrl, remaining(), deps);
+        return up ? "started" : "start-timeout";
+    }
+    catch {
+        await logCode("error");
+        return "start-timeout";
+    }
+    finally {
+        if (held)
+            removeStartLockFor(deps.pid, deps.lockPath, deps.lockFs);
+    }
+}
+/** A caller without the lock never spawns. It waits for the caller that holds it. */
+async function waitForOther(baseUrl, wait, remaining, deps) {
+    if (!wait)
+        return "started";
+    return (await pollUntilUp(baseUrl, remaining(), deps)) ? "running" : "start-timeout";
+}
+/** Poll health every 250 ms until an OMMS web app answers or the budget ends. */
+async function pollUntilUp(baseUrl, budgetMs, deps) {
+    const began = deps.now();
+    const remaining = () => budgetMs - (deps.now() - began);
+    while (remaining() > 0) {
+        await deps.sleep(Math.min(POLL_INTERVAL_MS, remaining()));
+        if (remaining() <= 0)
+            break;
+        if ((await probe(baseUrl, Math.min(HEALTH_PROBE_MS, remaining()), deps)) === "omms")
+            return true;
+    }
+    return false;
+}

package/dist/services/web-server.d.ts

@@ -26,6 +26,7 @@ interface WebServerConfig {
     /** How long a stepped-aside server waits before it may take the port back. */
     stepAsideHoldOffMs?: number;
 }
+type PowerAction = "stop" | "restart";
 export declare class WebServer {
     private server;
     private config;
@@ -35,6 +36,8 @@ export declare class WebServer {
     private onTakeoverCallback;
     private onPortsExhaustedCallback;
     private onStepAsideCallback;
+    private onPowerActionCallback;
+    private powerActionRunning;
     private stepAsideTimer;
     private holdOffTimer;
     private portsExhaustedNotified;
@@ -53,6 +56,9 @@ export declare class WebServer {
     setOnPortsExhaustedCallback(callback: () => void): void;
     /** Standalone web apps register this to exit when a newer OMMS asks them to step aside. */
     setOnStepAside(callback: () => void | Promise<void>): void;
+    /** Standalone web apps register this to stop or restart from the page. */
+    setOnPowerAction(callback: (action: PowerAction) => void | Promise<void>): void;
+    private handlePowerAction;
     private scheduleStepAside;
     private handleStepAside;
     start(): Promise<void>;

package/dist/services/web-server.js

@@ -152,6 +152,8 @@ export class WebServer {
     onTakeoverCallback = null;
     onPortsExhaustedCallback = null;
     onStepAsideCallback = null;
+    onPowerActionCallback = null;
+    powerActionRunning = false;
     stepAsideTimer = null;
     holdOffTimer = null;
     portsExhaustedNotified = false;
@@ -211,6 +213,42 @@ export class WebServer {
     setOnStepAside(callback) {
         this.onStepAsideCallback = callback;
     }
+    /** Standalone web apps register this to stop or restart from the page. */
+    setOnPowerAction(callback) {
+        this.onPowerActionCallback = callback;
+    }
+    handlePowerAction(action, remoteAddress) {
+        const record = (outcome) => log("Web server power request", { action, outcome, ownVersion: packageVersion() });
+        if (!isLoopbackAddress(remoteAddress)) {
+            record("refused_not_loopback");
+            return this.jsonResponse({ success: false, error: "Loopback caller required" }, 403);
+        }
+        const callback = this.onPowerActionCallback;
+        if (!callback) {
+            record("unsupported");
+            return this.jsonResponse({ success: false, error: "Not supported by this web app" }, 409);
+        }
+        // A repeated request must not start a second stop or restart while one runs.
+        if (this.powerActionRunning) {
+            record("already_running");
+            return this.jsonResponse({ success: true }, 202);
+        }
+        this.powerActionRunning = true;
+        record(action === "stop" ? "stopping" : "restarting");
+        // Let the 202 reply reach the caller before the web app goes down.
+        setTimeout(async () => {
+            try {
+                await callback(action);
+            }
+            catch (error) {
+                log("Power action callback error", { action, error: String(error) });
+            }
+            finally {
+                this.powerActionRunning = false;
+            }
+        }, STEP_ASIDE_REPLY_GRACE_MS).unref();
+        return this.jsonResponse({ success: true }, 202);
+    }
     scheduleStepAside() {
         if (this.stepAsideTimer)
             return;
@@ -281,6 +319,10 @@ export class WebServer {
                 fetch: this.handleRequest.bind(this),
             });
             this.isOwner = true;
+            // A restart copy is named in the start lock until it owns the port.
+            void import("./web-ensure.js")
+                .then(({ removeStartLockFor }) => removeStartLockFor(process.pid))
+                .catch(() => { });
             // This process serves the Claude Code hooks, so it also retries their failed captures.
             void import("../importer/claude-hook-api.js")
                 .then(({ startClaudeCodeWorker }) => startClaudeCodeWorker())
@@ -477,6 +519,13 @@ export class WebServer {
                         callerVersion: "",
                     });
                 }
+                if (method === "POST" && (path === "/api/web/stop" || path === "/api/web/restart")) {
+                    log("Web server power request", {
+                        action: path === "/api/web/stop" ? "stop" : "restart",
+                        outcome: "refused_auth",
+                        ownVersion: packageVersion(),
+                    });
+                }
                 return (configuredTokenFailure ??
                     this.jsonResponse({ success: false, error: "Unauthorized" }, 401));
             }
@@ -542,6 +591,15 @@ export class WebServer {
                         ? controls.resume(host, cwd)
                         : controls.runNow(host, cwd));
             }
+            if (path === "/api/web/status" && method === "GET") {
+                return this.jsonResponse({
+                    version: packageVersion(),
+                    canControl: isLoopbackAddress(remoteAddress) && this.onPowerActionCallback !== null,
+                });
+            }
+            if ((path === "/api/web/stop" || path === "/api/web/restart") && method === "POST") {
+                return this.handlePowerAction(path === "/api/web/stop" ? "stop" : "restart", remoteAddress);
+            }
             if (path === "/api/web/step-aside" && method === "POST") {
                 const body = await req.json().catch(() => null);
                 return this.handleStepAside(remoteAddress, body);