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

package/dist/cli/web-command.d.ts

@@ -1,3 +1,10 @@
 import type { WebAutostartOptions } from "../services/web-autostart.js";
+/** Test seams for the handover in `web install`. */
+export interface WebHandoverDeps {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** The version this command runs as. */
+    version?: string;
+}
 /** Run the standalone web app or manage its per-user login item. */
-export declare function runWebCommand(args: string[], options?: WebAutostartOptions, online?: () => Promise<boolean>): Promise<number>;
+export declare function runWebCommand(args: string[], options?: WebAutostartOptions, online?: () => Promise<boolean>, handover?: WebHandoverDeps): Promise<number>;

package/dist/cli/web-command.js

@@ -1,6 +1,95 @@
 import { homedir } from "node:os";
+const POLL_MS = 250;
+const POLL_LIMIT = 40;
+const REQUEST_TIMEOUT_MS = 2_000;
+/** The version an OMMS web app reports on `url`, or null when none answers with one. */
+async function readWebVersion(fetchFn, url, headers) {
+    try {
+        const response = await fetchFn(`${url}/api/settings/version`, {
+            headers,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.running === "string" ? body.running : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function portAnswers(fetchFn, url) {
+    try {
+        await fetchFn(`${url}/api/health`, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Ask an older OMMS web app on the configured port to step aside, and wait for the port. */
+async function negotiateOwner(ctx) {
+    const { compareVersions } = await import("../services/version-compare.js");
+    const owner = await readWebVersion(ctx.fetchFn, ctx.url, ctx.headers);
+    const order = owner === null ? null : compareVersions(owner, ctx.version);
+    // A version that cannot be placed is never stopped.
+    if (owner === null || order === null)
+        return { kind: "none" };
+    if (order === 0)
+        return { kind: "same", owner };
+    if (order > 0)
+        return { kind: "newer", owner };
+    try {
+        const reply = await ctx.fetchFn(`${ctx.url}/api/web/step-aside`, {
+            method: "POST",
+            headers: { ...ctx.headers, "content-type": "application/json" },
+            body: JSON.stringify({ version: ctx.version }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (reply.status !== 202)
+            return { kind: "stuck", owner };
+    }
+    catch {
+        return { kind: "stuck", owner };
+    }
+    // If the old app is slow to stop, the login item still takes the port later.
+    for (let i = 0; i < POLL_LIMIT && (await portAnswers(ctx.fetchFn, ctx.url)); i++) {
+        await ctx.sleep(POLL_MS);
+    }
+    return { kind: "handed" };
+}
+/** Print which version serves the port after `web install`. */
+async function announceHandover(ctx, handover) {
+    const { url, port, version } = ctx;
+    if (handover.kind === "stuck") {
+        console.log(`OMMS ${handover.owner} holds port ${port} and cannot hand it over. Stop the web app (Ctrl+C in its terminal, or quit the session that runs it), then run om-memory-system web install again.`);
+    }
+    else if (handover.kind === "newer") {
+        console.log(`OMMS ${handover.owner} already serves port ${port}. It is newer than this command (${version}). Update the global command: npm i -g om-memory-system`);
+    }
+    else if (handover.kind === "same") {
+        console.log(`OMMS web app: ${url} (version ${handover.owner})`);
+    }
+    else if (handover.kind === "none") {
+        console.log(`OMMS web app: ${url}`);
+    }
+    else {
+        let serving = null;
+        for (let i = 0; i < POLL_LIMIT && !serving; i++) {
+            serving = await readWebVersion(ctx.fetchFn, url, ctx.headers);
+            if (!serving)
+                await ctx.sleep(POLL_MS);
+        }
+        if (!serving)
+            console.log(`OMMS web app: ${url}`);
+        else if (serving === version)
+            console.log(`OMMS web app: ${url} (version ${serving})`);
+        else
+            console.log(`OMMS web app: ${url} (version ${serving}). This is not the version of this command (${version}).`);
+    }
+}
 /** Run the standalone web app or manage its per-user login item. */
-export async function runWebCommand(args, options = {}, online) {
+export async function runWebCommand(args, options = {}, online, handover = {}) {
     const home = options.home ?? homedir();
     const config = await import("../config.js");
     config.initConfig(home);
@@ -21,12 +110,33 @@ export async function runWebCommand(args, options = {}, online) {
         const { readGlobalConfigRevision, writeGlobalConfigKeys } = await import("../services/global-config-writer.js");
         await writeGlobalConfigKeys({ webServerAutoStart: action === "install" }, readGlobalConfigRevision());
         config.initConfig(home);
+        let context;
+        let outcome = { kind: "none" };
+        if (action === "install") {
+            const [{ getOrCreateAuthToken, AUTH_HEADER }, { packageVersion }] = await Promise.all([
+                import("../services/auth-token.js"),
+                import("../services/package-version.js"),
+            ]);
+            const apiToken = config.CONFIG.webServerApiToken;
+            context = {
+                fetchFn: handover.fetch ?? fetch,
+                sleep: handover.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+                url,
+                port: config.CONFIG.webServerPort,
+                headers: {
+                    [AUTH_HEADER]: getOrCreateAuthToken(),
+                    ...(apiToken ? { authorization: `Bearer ${apiToken}` } : {}),
+                },
+                version: handover.version ?? packageVersion(),
+            };
+            outcome = await negotiateOwner(context);
+        }
         const result = action === "install"
             ? installWebAutostart({ ...options, start: true })
             : removeWebAutostart({ ...options, start: true });
         console.log(`OMMS login item: ${result.state}`);
-        if (action === "install" && result.state === "installed")
-            console.log(`OMMS web app: ${url}`);
+        if (context && result.state === "installed")
+            await announceHandover(context, outcome);
         return action === "install" && result.state !== "installed" ? 1 : 0;
     }
     if (action === "status") {
@@ -72,5 +182,11 @@ export async function runWebCommand(args, options = {}, online) {
     };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    // A newer `web install` asked this web app to give up the port.
+    server.setOnStepAside(async () => {
+        clearInterval(keeper);
+        await server.stop();
+        process.exit(0);
+    });
     return 0;
 }

package/dist/services/version-compare.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compare two versions in SemVer order. Returns a negative number when `a` is older,
+ * a positive number when `a` is newer, `0` when equal, and `null` when either
+ * version cannot be parsed, such as `unknown`.
+ */
+export declare function compareVersions(a: string, b: string): number | null;
+/** True only when `a` is provably older than `b`. An unplaceable version is never older. */
+export declare function isOlderVersion(a: string, b: string): boolean;

package/dist/services/version-compare.js

@@ -0,0 +1,58 @@
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function parse(version) {
+    const match = SEMVER.exec(version.trim());
+    if (!match)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        pre: match[4] ? match[4].split(".") : [],
+    };
+}
+function comparePart(a, b) {
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric)
+        return Math.sign(Number(a) - Number(b));
+    // A numeric part is older than a text part.
+    if (aNumeric)
+        return -1;
+    if (bNumeric)
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Compare two versions in SemVer order. Returns a negative number when `a` is older,
+ * a positive number when `a` is newer, `0` when equal, and `null` when either
+ * version cannot be parsed, such as `unknown`.
+ */
+export function compareVersions(a, b) {
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        const diff = left.core[i] - right.core[i];
+        if (diff)
+            return Math.sign(diff);
+    }
+    // A release is newer than any of its prereleases.
+    if (!left.pre.length || !right.pre.length)
+        return right.pre.length - left.pre.length;
+    for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+        const l = left.pre[i];
+        const r = right.pre[i];
+        if (l === undefined)
+            return -1;
+        if (r === undefined)
+            return 1;
+        const diff = comparePart(l, r);
+        if (diff)
+            return diff;
+    }
+    return 0;
+}
+/** True only when `a` is provably older than `b`. An unplaceable version is never older. */
+export function isOlderVersion(a, b) {
+    const order = compareVersions(a, b);
+    return order !== null && order < 0;
+}

package/dist/services/web-api-auth.d.ts

@@ -1,4 +1,6 @@
 export declare function isLoopbackHost(host: string): boolean;
+/** True for a peer socket address on this machine: 127.x.x.x, ::1, or an IPv4-mapped 127.x.x.x. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
 /** A URL needs brackets around an IPv6 literal such as ::1. */
 export declare function webServerUrl(host: string, port: number): string;
 export declare function assertWebServerNetworkAuth(host: string, apiToken?: string, basicAuthEnabled?: boolean): void;

package/dist/services/web-api-auth.js

@@ -3,6 +3,16 @@ const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]", "0:0:0
 export function isLoopbackHost(host) {
     return LOOPBACK_HOSTS.has(host.trim().toLowerCase());
 }
+/** True for a peer socket address on this machine: 127.x.x.x, ::1, or an IPv4-mapped 127.x.x.x. */
+export function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    const value = address
+        .trim()
+        .toLowerCase()
+        .replace(/^::ffff:/, "");
+    return value === "::1" || /^127(?:\.\d{1,3}){3}$/.test(value);
+}
 /** A URL needs brackets around an IPv6 literal such as ::1. */
 export function webServerUrl(host, port) {
     const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;

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

@@ -23,6 +23,8 @@ interface WebServerConfig {
     enabled: boolean;
     auth?: WebAuth;
     apiToken?: string;
+    /** How long a stepped-aside server waits before it may take the port back. */
+    stepAsideHoldOffMs?: number;
 }
 export declare class WebServer {
     private server;
@@ -32,6 +34,9 @@ export declare class WebServer {
     private healthCheckInterval;
     private onTakeoverCallback;
     private onPortsExhaustedCallback;
+    private onStepAsideCallback;
+    private stepAsideTimer;
+    private holdOffTimer;
     private portsExhaustedNotified;
     private takeoverFailures;
     private readonly maxFallbackPort;
@@ -46,6 +51,10 @@ export declare class WebServer {
     constructor(config: WebServerConfig);
     setOnTakeoverCallback(callback: () => Promise<void>): void;
     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;
+    private scheduleStepAside;
+    private handleStepAside;
     start(): Promise<void>;
     private _start;
     private startHealthCheckLoop;

package/dist/services/web-server.js

@@ -5,7 +5,9 @@ import { join, dirname, extname, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { log } from "./logger.js";
 import { corsPreflightResponse, disallowedCorsResponse, isAllowedBrowserOrigin } from "./cors.js";
-import { assertWebServerNetworkAuth, authorizeApiRequest, isLoopbackHost, webServerUrl, } from "./web-api-auth.js";
+import { assertWebServerNetworkAuth, authorizeApiRequest, isLoopbackAddress, isLoopbackHost, webServerUrl, } from "./web-api-auth.js";
+import { packageVersion } from "./package-version.js";
+import { isOlderVersion } from "./version-compare.js";
 import { getOrCreateAuthToken, isAuthorizedApiRequest } from "./auth-token.js";
 import { WebAuth } from "./web-auth.js";
 import { NODE_HTTP_IDLE_TIMEOUT_MS } from "./request-timeouts.js";
@@ -34,7 +36,7 @@ function serveFetch(opts) {
         const bunHandle = globalThis.Bun.serve({
             port: opts.port,
             hostname: opts.hostname,
-            fetch: opts.fetch,
+            fetch: (req, server) => opts.fetch(req, server.requestIP(req)?.address),
         });
         return Promise.resolve({ stop: () => bunHandle.stop() });
     }
@@ -67,7 +69,7 @@ function serveFetch(opts) {
                 signal: abortController.signal,
                 ...(hasBody ? { duplex: "half" } : {}),
             });
-            const webRes = await opts.fetch(webReq);
+            const webRes = await opts.fetch(webReq, req.socket.remoteAddress);
             if (destroyed)
                 return;
             res.statusCode = webRes.status;
@@ -138,6 +140,9 @@ export function nextFallbackPort(currentPort, failedTakeovers, maxFallbackPort,
     }
     return currentPort + 1;
 }
+const STEP_ASIDE_HOLD_OFF_MS = 60_000;
+/** Lets the 202 reply reach the caller before the server stops. */
+const STEP_ASIDE_REPLY_GRACE_MS = 100;
 export class WebServer {
     server = null;
     config;
@@ -146,6 +151,9 @@ export class WebServer {
     healthCheckInterval = null;
     onTakeoverCallback = null;
     onPortsExhaustedCallback = null;
+    onStepAsideCallback = null;
+    stepAsideTimer = null;
+    holdOffTimer = null;
     portsExhaustedNotified = false;
     takeoverFailures = 0;
     maxFallbackPort;
@@ -199,6 +207,57 @@ export class WebServer {
     setOnPortsExhaustedCallback(callback) {
         this.onPortsExhaustedCallback = callback;
     }
+    /** Standalone web apps register this to exit when a newer OMMS asks them to step aside. */
+    setOnStepAside(callback) {
+        this.onStepAsideCallback = callback;
+    }
+    scheduleStepAside() {
+        if (this.stepAsideTimer)
+            return;
+        this.stepAsideTimer = setTimeout(async () => {
+            this.stepAsideTimer = null;
+            if (this.onStepAsideCallback) {
+                try {
+                    await this.onStepAsideCallback();
+                }
+                catch (error) {
+                    log("Step-aside callback error", { error: String(error) });
+                }
+                return;
+            }
+            // Inside a host session: stop serving, keep the session alive, and let the
+            // newer web app bind the port before the takeover loop can run again.
+            await this.stop();
+            this.startPromise = null;
+            this.holdOffTimer = setTimeout(() => {
+                this.holdOffTimer = null;
+                this.startHealthCheckLoop();
+            }, this.config.stepAsideHoldOffMs ?? STEP_ASIDE_HOLD_OFF_MS);
+            this.holdOffTimer.unref();
+        }, STEP_ASIDE_REPLY_GRACE_MS);
+        this.stepAsideTimer.unref();
+    }
+    handleStepAside(remoteAddress, body) {
+        const callerVersion = body && typeof body.version === "string"
+            ? body.version.slice(0, 40)
+            : "";
+        const record = (outcome) => log("Web server step-aside request", {
+            outcome,
+            ownVersion: packageVersion(),
+            callerVersion,
+        });
+        if (!isLoopbackAddress(remoteAddress)) {
+            record("refused_auth");
+            return this.jsonResponse({ success: false, error: "Loopback caller required" }, 403);
+        }
+        if (!callerVersion || !isOlderVersion(packageVersion(), callerVersion)) {
+            record("refused_not_newer");
+            return this.jsonResponse({ success: false, error: "Caller is not newer" }, 409);
+        }
+        record("stepped_aside");
+        this.scheduleStepAside();
+        return this.jsonResponse({ success: true }, 202);
+    }
     async start() {
         if (this.startPromise) {
             return this.startPromise;
@@ -334,6 +393,11 @@ export class WebServer {
     }
     async stop() {
         this.stopHealthCheckLoop();
+        for (const timer of [this.stepAsideTimer, this.holdOffTimer])
+            if (timer)
+                clearTimeout(timer);
+        this.stepAsideTimer = null;
+        this.holdOffTimer = null;
         if (!this.isOwner || !this.server) {
             return;
         }
@@ -380,7 +444,7 @@ export class WebServer {
         }
     }
     // --- HTTP request handling ---
-    async handleRequest(req) {
+    async handleRequest(req, remoteAddress) {
         const url = new URL(req.url);
         const path = url.pathname;
         const method = req.method;
@@ -406,6 +470,13 @@ export class WebServer {
                 ? authorizeApiRequest(req, this.config.apiToken)
                 : null;
             if (!this.config.apiToken || configuredTokenFailure) {
+                if (path === "/api/web/step-aside") {
+                    log("Web server step-aside request", {
+                        outcome: "refused_auth",
+                        ownVersion: packageVersion(),
+                        callerVersion: "",
+                    });
+                }
                 return (configuredTokenFailure ??
                     this.jsonResponse({ success: false, error: "Unauthorized" }, 401));
             }
@@ -471,6 +542,10 @@ export class WebServer {
                         ? controls.resume(host, cwd)
                         : controls.runNow(host, cwd));
             }
+            if (path === "/api/web/step-aside" && method === "POST") {
+                const body = await req.json().catch(() => null);
+                return this.handleStepAside(remoteAddress, body);
+            }
             if (path === "/api/settings/version" && method === "GET") {
                 const [{ packageVersion }, { globalCommandVersion }] = await Promise.all([
                     import("./package-version.js"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "om-memory-system",
-  "version": "3.6.0-next.38",
+  "version": "3.6.0-next.39",
   "description": "Opinionated modular memory system for coding agents (OpenCode + Pi)",
   "type": "module",
   "main": "dist/plugin.js",