om-memory-system 4.9.0 → 4.11.0-next.96

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

@@ -1,3 +1,4 @@
+import type { WebUpdate } from "./web-update.js";
 import { WebAuth } from "./web-auth.js";
 type NodeEventSource = {
     on(event: string, listener: (...args: any[]) => void): unknown;
@@ -25,6 +26,8 @@ interface WebServerConfig {
     apiToken?: string;
     /** How long a stepped-aside server waits before it may take the port back. */
     stepAsideHoldOffMs?: number;
+    /** Test seam: the retire marker's time, or null. Defaults to `~/.omms/web-retire.json`. */
+    readRetireMarker?: () => number | null;
 }
 type PowerAction = "stop" | "restart";
 export declare class WebServer {
@@ -36,7 +39,10 @@ export declare class WebServer {
     private onTakeoverCallback;
     private onPortsExhaustedCallback;
     private onStepAsideCallback;
+    /** `web update` retires waiting web apps that started before its marker. */
+    private readonly startedAt;
     private onPowerActionCallback;
+    private webUpdate;
     private powerActionRunning;
     private stepAsideTimer;
     private holdOffTimer;
@@ -59,9 +65,13 @@ export declare class WebServer {
     /** 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;
+    setOnPowerAction(callback: (action: PowerAction) => unknown): void;
+    /** Standalone web apps register this to report and install npm releases. */
+    setWebUpdate(update: Pick<WebUpdate, "status" | "requestInstall">): void;
     /** Only a local caller may stop the web app; the token alone is not enough. */
     private handlePowerAction;
+    /** Install the npm release and restart onto it. Same guards as Restart. */
+    private handleUpdate;
     /** API token routes. Only a caller on this machine with the local token manages tokens. */
     private handleTokenRoute;
     /** Profile catch-up: a preview for anyone with API access; runs only from this machine. */
@@ -77,6 +87,11 @@ export declare class WebServer {
     start(): Promise<void>;
     private _start;
     private startHealthCheckLoop;
+    /** One check of a web app that waits for the port. */
+    private waiterTick;
+    /** True when `web update` asked web apps started before this one to retire. */
+    private retiredByUpdate;
+    private ownerIsNewer;
     private stopHealthCheckLoop;
     private attemptTakeover;
     private notifyPortsExhausted;

package/dist/services/web-server.js

@@ -142,10 +142,19 @@ export function nextFallbackPort(currentPort, failedTakeovers, maxFallbackPort,
     return currentPort + 1;
 }
 const STEP_ASIDE_HOLD_OFF_MS = 60_000;
+/** What a web app without an npm check reports, such as one inside a host session. */
+const NO_UPDATE = { available: null, state: "idle", code: null, canInstall: false };
 /** Lets the 202 reply reach the caller before the server stops. */
 const STEP_ASIDE_REPLY_GRACE_MS = 100;
-/** Differs between processes, so the page can tell a restarted web app from the old one. */
-const PROCESS_INSTANCE = randomUUID();
+/**
+ * Differs between processes, so the page can tell a restarted web app from the old one.
+ * A restart names its copy's instance, so it can tell its copy from another web app.
+ */
+const PROCESS_INSTANCE = /^[0-9a-f-]{36}$/.test(process.env.OMMS_WEB_INSTANCE ?? "")
+    ? process.env.OMMS_WEB_INSTANCE
+    : randomUUID();
+// Child processes, such as an OpenCode model list, must not report the same instance.
+delete process.env.OMMS_WEB_INSTANCE;
 export class WebServer {
     server = null;
     config;
@@ -155,7 +164,10 @@ export class WebServer {
     onTakeoverCallback = null;
     onPortsExhaustedCallback = null;
     onStepAsideCallback = null;
+    /** `web update` retires waiting web apps that started before its marker. */
+    startedAt = Date.now();
     onPowerActionCallback = null;
+    webUpdate = null;
     powerActionRunning = false;
     stepAsideTimer = null;
     holdOffTimer = null;
@@ -222,6 +234,10 @@ export class WebServer {
     setOnPowerAction(callback) {
         this.onPowerActionCallback = callback;
     }
+    /** Standalone web apps register this to report and install npm releases. */
+    setWebUpdate(update) {
+        this.webUpdate = update;
+    }
     /** Only a local caller may stop the web app; the token alone is not enough. */
     handlePowerAction(action, remoteAddress) {
         const record = (outcome) => log("Web server power request", { action, outcome, ownVersion: packageVersion() });
@@ -234,6 +250,12 @@ export class WebServer {
             record("unsupported");
             return this.jsonResponse({ success: false, error: "Not supported by this web app" }, 409);
         }
+        // An update restarts through the same callback; a Stop or Restart now would cut npm off.
+        const updateState = this.webUpdate?.status().state;
+        if (updateState === "installing" || updateState === "restarting") {
+            record("refused_update_running");
+            return this.jsonResponse({ success: false, error: "An update is running" }, 409);
+        }
         // A repeated request must not start a second stop or restart while one runs.
         if (this.powerActionRunning) {
             record("already_running");
@@ -255,6 +277,24 @@ export class WebServer {
         }, STEP_ASIDE_REPLY_GRACE_MS).unref();
         return this.jsonResponse({ success: true }, 202);
     }
+    /** Install the npm release and restart onto it. Same guards as Restart. */
+    handleUpdate(remoteAddress) {
+        const record = (outcome) => log("Web server update request", { outcome, ownVersion: packageVersion() });
+        if (!isLoopbackAddress(remoteAddress)) {
+            record("refused_not_loopback");
+            return this.jsonResponse({ success: false, error: "Loopback caller required" }, 403);
+        }
+        if (this.powerActionRunning) {
+            record("refused_power_running");
+            return this.jsonResponse({ success: false, error: "A stop or restart is running" }, 409);
+        }
+        const reply = this.webUpdate?.requestInstall() ?? "cannot-install";
+        record(reply);
+        if (reply === "accepted")
+            return this.jsonResponse({ success: true }, 202);
+        const error = reply === "no-update" ? "No newer release" : "This web app cannot install";
+        return this.jsonResponse({ success: false, error }, 409);
+    }
     /** API token routes. Only a caller on this machine with the local token manages tokens. */
     async handleTokenRoute(req, path, method, remoteAddress) {
         if (!isLoopbackAddress(remoteAddress)) {
@@ -452,16 +492,19 @@ export class WebServer {
         const callerVersion = body && typeof body.version === "string"
             ? body.version.slice(0, 40)
             : "";
+        // `web update` replaces a web app of any version; other callers must be newer.
+        const replace = Boolean(body && body.replace === true);
         const record = (outcome) => log("Web server step-aside request", {
             outcome,
             ownVersion: packageVersion(),
             callerVersion,
+            replace,
         });
         if (!isLoopbackAddress(remoteAddress)) {
             record("refused_auth");
             return this.jsonResponse({ success: false, error: "Loopback caller required" }, 403);
         }
-        if (!callerVersion || !isOlderVersion(packageVersion(), callerVersion)) {
+        if (!callerVersion || (!replace && !isOlderVersion(packageVersion(), callerVersion))) {
             record("refused_not_newer");
             return this.jsonResponse({ success: false, error: "Caller is not newer" }, 409);
         }
@@ -534,13 +577,60 @@ export class WebServer {
         if (this.healthCheckInterval) {
             return;
         }
-        this.healthCheckInterval = setInterval(async () => {
-            const isAvailable = await this.checkServerAvailable();
-            if (!isAvailable) {
-                this.stopHealthCheckLoop();
-                await this.attemptTakeover();
-            }
-        }, 5000);
+        this.healthCheckInterval = setInterval(() => void this.waiterTick(), 5000);
+    }
+    /** One check of a web app that waits for the port. */
+    async waiterTick() {
+        const isAvailable = await this.checkServerAvailable();
+        if (!isAvailable) {
+            this.stopHealthCheckLoop();
+            await this.attemptTakeover();
+            return;
+        }
+        if (!this.onStepAsideCallback)
+            return;
+        // A standalone web app behind a newer one would serve old code after a restart.
+        const reason = (await this.retiredByUpdate())
+            ? "update"
+            : (await this.ownerIsNewer())
+                ? "newer-owner"
+                : null;
+        if (!reason)
+            return;
+        this.stopHealthCheckLoop();
+        log("Web server waiter retired", { ownVersion: packageVersion(), reason });
+        try {
+            await this.onStepAsideCallback();
+        }
+        catch (error) {
+            log("Step-aside callback error", { error: String(error) });
+        }
+    }
+    /** True when `web update` asked web apps started before this one to retire. */
+    async retiredByUpdate() {
+        try {
+            const read = this.config.readRetireMarker ?? (await import("./web-retire.js")).readRetireMarker;
+            const before = read();
+            return before !== null && this.startedAt < before;
+        }
+        catch {
+            return false;
+        }
+    }
+    async ownerIsNewer() {
+        try {
+            const response = await fetch(`${this.getUrl()}/api/web/status`, {
+                headers: { [AUTH_HEADER]: getOrCreateAuthToken() },
+                signal: AbortSignal.timeout(2_000),
+            });
+            if (!response.ok)
+                return false;
+            const { version } = (await response.json());
+            return typeof version === "string" && isOlderVersion(packageVersion(), version);
+        }
+        catch {
+            return false;
+        }
     }
     stopHealthCheckLoop() {
         if (this.healthCheckInterval) {
@@ -729,6 +819,8 @@ export class WebServer {
                     success: true,
                     status: "ok",
                     authEnabled: auth?.isEnabled() ?? false,
+                    // Opaque per process; a restart finds its copy by it even behind basic auth.
+                    instance: PROCESS_INSTANCE,
                 });
             }
             if (path === "/" || path === "/index.html" || path === "/settings") {
@@ -813,11 +905,15 @@ export class WebServer {
                     // Keys, tokens, and the embedder can be changed only from this machine.
                     isLocal: isLoopbackAddress(remoteAddress),
                     instance: PROCESS_INSTANCE,
+                    update: this.webUpdate?.status() ?? NO_UPDATE,
                 });
             }
             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/update" && method === "POST") {
+                return this.handleUpdate(remoteAddress);
+            }
             if (path === "/api/web/step-aside" && method === "POST") {
                 const body = await req.json().catch(() => null);
                 return this.handleStepAside(remoteAddress, body);

package/dist/services/web-update-runtime.d.ts

@@ -0,0 +1,5 @@
+import { WebUpdate, type InstallDeps } from "./web-update.js";
+/** The npm check and installer of a standalone web app, with the real process, npm, and clock. */
+export declare function startWebUpdate(restart: () => Promise<string | undefined>, canRestart: () => boolean): WebUpdate;
+/** The real npm process, shared by the update button and `web update`. */
+export declare function nodeInstallDeps(): InstallDeps;

package/dist/services/web-update-runtime.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { globalCommandVersion } from "./global-version.js";
+import { log } from "./logger.js";
+import { packageVersion } from "./package-version.js";
+import { WebUpdate } from "./web-update.js";
+/** The npm check and installer of a standalone web app, with the real process, npm, and clock. */
+export function startWebUpdate(restart, canRestart) {
+    const update = new WebUpdate({
+        version: packageVersion(),
+        enabled: process.env.OMMS_DISABLE_UPDATE_CHECK !== "1",
+        fetch,
+        setInterval: (callback, ms) => setInterval(callback, ms),
+        log,
+        ...nodeInstallDeps(),
+        exists: existsSync,
+        // npm installs beside this Node.js, so read that install, not the first command on PATH.
+        globalVersion: () => globalCommandVersion({ find: () => null }).version,
+        restart,
+        canRestart,
+        now: () => Date.now(),
+    });
+    update.start();
+    return update;
+}
+/** The real npm process, shared by the update button and `web update`. */
+export function nodeInstallDeps() {
+    return {
+        execPath: process.execPath,
+        platform: process.platform,
+        spawn: (command, args, options) => spawn(command, args, {
+            shell: options.shell,
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+        }),
+        // Resolves once npm has stopped. `taskkill /T` also stops npm under the cmd.exe
+        // wrapper that `shell: true` starts; the child's own exit confirms it.
+        killTree: (child) => new Promise((resolve) => {
+            child.on("exit", () => resolve());
+            if (process.platform === "win32" && child.pid) {
+                spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+                    stdio: "ignore",
+                    windowsHide: true,
+                }).on("error", () => child.kill("SIGKILL"));
+            }
+            else {
+                child.kill("SIGTERM");
+            }
+        }),
+        setTimeout: (callback, ms) => setTimeout(callback, ms),
+        clearTimeout: (handle) => clearTimeout(handle),
+    };
+}

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

@@ -0,0 +1,87 @@
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+/** An install that takes longer is stopped, and the web app keeps serving. */
+export declare const INSTALL_TIMEOUT_MS: number;
+export type UpdateState = "idle" | "installing" | "restarting" | "failed";
+/** The `update` field of `GET /api/web/status`. */
+export interface UpdateStatus {
+    /** The newer release on npm, or null. */
+    available: string | null;
+    state: UpdateState;
+    /** The failure code while `state` is `failed`. */
+    code: string | null;
+    /** True when this web app can install the release itself. */
+    canInstall: boolean;
+}
+export interface WebUpdateDeps {
+    /** The running version. */
+    version: string;
+    /** False when `OMMS_DISABLE_UPDATE_CHECK` is `1`. */
+    enabled: boolean;
+    fetch: typeof fetch;
+    setInterval: (callback: () => void, ms: number) => {
+        unref?: () => void;
+    };
+    log: (message: string, data: Record<string, unknown>) => void;
+    /** The runtime of this web app; npm must sit beside it. */
+    execPath: string;
+    platform: NodeJS.Platform;
+    exists: (path: string) => boolean;
+    spawn: (command: string, args: string[], options: {
+        shell: boolean;
+    }) => InstallChild;
+    /** The version of the global install after npm ran, or null. */
+    globalVersion: () => string | null;
+    /** False when no restart could serve the new copy, such as a missing launcher. Checked before npm runs. */
+    canRestart: () => boolean;
+    /** Stop npm and its children. On Windows the shell wrapper alone would leave npm running. */
+    killTree: (child: InstallChild) => Promise<void>;
+    /** Restart onto the newest copy. Returns a failure code when this web app keeps serving. */
+    restart: () => Promise<string | undefined>;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+    now: () => number;
+}
+/** The parts of a child process the install runner uses. */
+export interface InstallChild {
+    pid?: number;
+    stderr: {
+        on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    } | null;
+    on(event: "error", listener: () => void): unknown;
+    on(event: "exit", listener: (code: number | null) => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
+}
+export type InstallRequest = "accepted" | "no-update" | "cannot-install";
+/** A failure code from npm's error stream. The text itself never leaves this function. */
+export declare function npmFailureCode(errorText: string): string;
+export declare class WebUpdate {
+    private readonly deps;
+    private available;
+    private state;
+    private code;
+    private started;
+    constructor(deps: WebUpdateDeps);
+    /** Check now, then every 6 hours. A second call does nothing. */
+    start(): void;
+    /** Read npm `latest`. A failed read keeps the last result. */
+    check(): Promise<void>;
+    status(): UpdateStatus;
+    private canInstall;
+    /** Start the install and the restart. A request while one runs joins it. */
+    requestInstall(): InstallRequest;
+    private install;
+}
+/** The parts of the update deps that run npm. */
+export type InstallDeps = Pick<WebUpdateDeps, "execPath" | "platform" | "spawn" | "killTree" | "setTimeout" | "clearTimeout">;
+/** A failure code, or null when npm exited with code 0. */
+export interface InstallResult {
+    code: string | null;
+    exitCode?: number | null;
+}
+/** The npm that installs into the prefix the launcher reads. */
+export declare function npmBesideRuntime(deps: Pick<WebUpdateDeps, "execPath" | "platform">): string;
+/**
+ * Run `npm install -g om-memory-system@<target>` and stop it after 5 minutes.
+ * The web app's update button and `web update` share it.
+ */
+export declare function runGlobalInstall(deps: InstallDeps, target: string): Promise<InstallResult>;

package/dist/services/web-update.js

@@ -0,0 +1,161 @@
+import { posix, win32 } from "node:path";
+import { availableUpdate, latestNpmVersion } from "./update-check.js";
+// The web app's npm release check. It reads npm `latest` at start and then every
+// 6 hours, and keeps the result in memory for `GET /api/web/status`. It imports
+// no host adapter and no config, so tests pass every input.
+export const UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** An install that takes longer is stopped, and the web app keeps serving. */
+export const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+/** Only a plain release reaches the npm arguments; the value comes from the registry. */
+const PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
+/** Enough of npm's error stream to find a code; the rest is dropped. */
+const ERROR_TAIL_BYTES = 64 * 1024;
+/** A failure code from npm's error stream. The text itself never leaves this function. */
+export function npmFailureCode(errorText) {
+    if (/\b(EACCES|EPERM)\b/.test(errorText))
+        return "permission";
+    if (/\b(ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN)\b/.test(errorText))
+        return "network";
+    return "npm-exit";
+}
+export class WebUpdate {
+    deps;
+    available = null;
+    state = "idle";
+    code = null;
+    started = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Check now, then every 6 hours. A second call does nothing. */
+    start() {
+        if (this.started || !this.deps.enabled)
+            return;
+        this.started = true;
+        void this.check();
+        this.deps.setInterval(() => void this.check(), UPDATE_CHECK_INTERVAL_MS).unref?.();
+    }
+    /** Read npm `latest`. A failed read keeps the last result. */
+    async check() {
+        if (!this.deps.enabled)
+            return;
+        const latest = await latestNpmVersion(this.deps.fetch);
+        if (latest === null) {
+            this.deps.log("Web app update check failed", { code: "unreachable" });
+            return;
+        }
+        this.available = availableUpdate(this.deps.version, latest);
+    }
+    status() {
+        return {
+            available: this.available,
+            state: this.state,
+            code: this.code,
+            canInstall: this.canInstall(),
+        };
+    }
+    canInstall() {
+        return this.deps.exists(npmBesideRuntime(this.deps)) && this.deps.canRestart();
+    }
+    /** Start the install and the restart. A request while one runs joins it. */
+    requestInstall() {
+        if (this.state === "installing" || this.state === "restarting")
+            return "accepted";
+        if (!this.available)
+            return "no-update";
+        if (!this.canInstall())
+            return "cannot-install";
+        this.state = "installing";
+        this.code = null;
+        void this.install(this.available);
+        return "accepted";
+    }
+    async install(target) {
+        const began = this.deps.now();
+        const record = (outcome, code, exitCode) => this.deps.log("Web app update", {
+            outcome,
+            code,
+            from: this.deps.version,
+            to: target,
+            exitCode,
+            durationMs: this.deps.now() - began,
+        });
+        const fail = (code, exitCode) => {
+            this.state = "failed";
+            this.code = code;
+            record("failed", code, exitCode);
+        };
+        const { code, exitCode } = await runGlobalInstall(this.deps, target);
+        if (code)
+            return fail(code, exitCode);
+        if (this.deps.globalVersion() !== target)
+            return fail("version-mismatch", exitCode);
+        this.state = "restarting";
+        record("installed", null, exitCode);
+        const restartCode = await this.deps.restart();
+        // The restart exits this process on success, so a return means it kept serving.
+        if (restartCode)
+            fail(restartCode);
+        else
+            this.state = "idle";
+    }
+}
+/** The npm that installs into the prefix the launcher reads. */
+export function npmBesideRuntime(deps) {
+    // Path rules follow the target platform, not the machine that runs this code.
+    const path = deps.platform === "win32" ? win32 : posix;
+    const name = deps.platform === "win32" ? "npm.cmd" : "npm";
+    return path.join(path.dirname(deps.execPath), name);
+}
+/**
+ * Run `npm install -g om-memory-system@<target>` and stop it after 5 minutes.
+ * The web app's update button and `web update` share it.
+ */
+export function runGlobalInstall(deps, target) {
+    if (!PLAIN_VERSION.test(target))
+        return Promise.resolve({ code: "bad-version" });
+    return new Promise((resolve) => {
+        let child;
+        try {
+            // Windows runs `npm.cmd` only through a shell, which splits an unquoted path at a
+            // space (`C:\\Program Files`). The arguments are fixed and the version is checked.
+            const windows = deps.platform === "win32";
+            const command = windows ? `"${npmBesideRuntime(deps)}"` : npmBesideRuntime(deps);
+            child = deps.spawn(command, ["install", "-g", `om-memory-system@${target}`], {
+                shell: windows,
+            });
+        }
+        catch {
+            resolve({ code: "spawn-error" });
+            return;
+        }
+        let errorText = "";
+        let done = false;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            deps.clearTimeout(timer);
+            resolve(result);
+        };
+        let timedOut = false;
+        const timer = deps.setTimeout(() => {
+            timedOut = true;
+            // Keep the update running until npm has stopped, so nothing else touches the install.
+            void deps
+                .killTree(child)
+                .catch(() => undefined)
+                .then(() => finish({ code: "timeout" }));
+        }, INSTALL_TIMEOUT_MS);
+        child.stderr?.on("data", (chunk) => {
+            errorText = (errorText + String(chunk)).slice(-ERROR_TAIL_BYTES);
+        });
+        child.on("error", () => finish({ code: "spawn-error" }));
+        child.on("exit", (exitCode) => {
+            // After a timeout the tree is still stopping; the timeout path reports it.
+            if (timedOut)
+                return;
+            finish({ code: exitCode === 0 ? null : npmFailureCode(errorText), exitCode });
+        });
+    });
+}