agentroam 0.2.0-preview.8 → 0.2.0-preview.9

package/README.md

@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.8.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.8.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.8.tgz \
-  ./agentroam-0.2.0-preview.8.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.9.tgz \
+  ./agentroam-runtime-darwin-arm64-0.2.0-preview.9.tgz \
+  ./agentroam-tui-darwin-arm64-0.2.0-preview.9.tgz \
+  ./agentroam-0.2.0-preview.9.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.8.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.8.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.8.tgz `
-  ./agentroam-0.2.0-preview.8.tgz
+npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.9.tgz `
+  ./agentroam-runtime-win32-x64-0.2.0-preview.9.tgz `
+  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.9.tgz `
+  ./agentroam-0.2.0-preview.9.tgz
 npx agentroam
 ```
 
@@ -53,6 +53,40 @@ agentroam version
 agent-tui                 # start the bundled terminal Agent UI
 ```
 
+## Install and run in the background
+
+Run the versioned Shell installer on macOS or PowerShell installer on Windows
+from the project directory AgentRoam should expose. The installer verifies or
+installs Node 22 and the matching CLI, registers the current-user service, starts
+it, checks readiness, and prints the access URL. Set `AGENTROAM_ROOT` to select a
+different root explicitly. An implicit root equal to the home directory is
+rejected.
+
+The service keeps running after the terminal closes, restarts after failure, and
+starts again when the user logs in. macOS uses a user LaunchAgent; Windows uses a
+current-user Task Scheduler task. Neither requires administrator privileges.
+
+```bash
+agentroam service status
+agentroam service start
+agentroam service stop
+agentroam service url
+agentroam service logs
+agentroam service restart
+agentroam service uninstall
+```
+
+The current phone URL is stored privately at `~/.agentroam/tunnel.url`.
+Cloudflared keeps the same Quick Tunnel hostname while its process reconnects;
+a full service or computer restart creates a new random hostname. Re-run the
+versioned installer after moving or replacing Node/npm so the service receives
+the new absolute executable paths.
+
+Both foreground `agentroam start` and the background service prevent idle system
+sleep for as long as they run. The display can still dim and turn off normally.
+Stopping AgentRoam releases the assertion. Lid close, explicit sleep,
+hibernation, shutdown, and low-battery forced sleep remain controlled by the OS.
+
 ## Options
 
 | Flag | Description |

package/bin/agentroam.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
-import("../dist/cli.js").then(({ main }) => main(process.argv.slice(2))).catch((error) => {
+import("./node-preflight.mjs").then(async ({ runNodePreflight }) => {
+  const result = await runNodePreflight();
+  if (result.handled) {
+    if (result.signal) process.kill(process.pid, result.signal);
+    else process.exitCode = result.exitCode ?? 1;
+    return;
+  }
+  const { main } = await import("../dist/cli.js");
+  await main(process.argv.slice(2));
+}).catch((error) => {
   console.error(`agentroam: ${error?.message ?? error}`);
   process.exitCode = error?.exitCode ?? 1;
 });

package/bin/node-preflight.mjs

@@ -0,0 +1,138 @@
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const MANAGED_NODE_VERSION = "22.22.0";
+const RELEASE_VERSION = "0.2.0-preview.9";
+const RELEASE_BASE_URL = `https://gitee.com/caoqu/team-agent/releases/download/v${RELEASE_VERSION}`;
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+export async function runNodePreflight(options = {}) {
+  const argv = options.argv ?? process.argv.slice(2);
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const launcherPath = options.launcherPath ?? fileURLToPath(new URL("./agentroam.mjs", import.meta.url));
+  const environment = options.environment ?? process.env;
+  const processHost = options.processHost ?? process;
+  const major = Number(nodeVersion.split(".")[0]);
+
+  if (major === 22) return { handled: false };
+  if (environment.AGENTROAM_MANAGED_NODE) {
+    throw cliError(
+      `managed Node.js re-entry failed: expected 22, got ${nodeVersion} (${environment.AGENTROAM_MANAGED_NODE})`,
+    );
+  }
+  if (!Number.isFinite(major) || major < 18) {
+    throw cliError(standaloneInstallerMessage(platform));
+  }
+
+  const target = detectManagedTarget(platform, arch);
+  const dataDir = parsePreflightDataDir(argv, environment, options.homeDir ?? homedir());
+  const findSystemNode22 = options.findSystemNode22 ?? defaultFindSystemNode22;
+  const systemNode = await findSystemNode22(environment, platform, options.currentExecutable ?? process.execPath);
+  let executable = systemNode;
+
+  if (!executable) {
+    const ensureNode = options.ensureNode ?? (async (installOptions) => {
+      const { ensureManagedNode } = await import("../dist/node-runtime-manager.js");
+      return ensureManagedNode(installOptions);
+    });
+    const resolution = await ensureNode({
+      dataDir,
+      target,
+      platform,
+      arch,
+      onProgress: options.onProgress ?? ((message) => processHost.stderr.write(`${message}\n`)),
+    });
+    executable = resolution.executable;
+  }
+
+  const spawnChild = options.spawnChild ?? defaultSpawnChild;
+  const child = spawnChild(executable, [launcherPath, ...argv], {
+    stdio: "inherit",
+    env: { ...environment, AGENTROAM_MANAGED_NODE: MANAGED_NODE_VERSION },
+  });
+  const result = await waitForChild(child, processHost);
+  return { handled: true, ...result };
+}
+
+export function parsePreflightDataDir(argv, environment = process.env, homeDir = homedir()) {
+  const index = argv.indexOf("--data-dir");
+  if (index >= 0) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw cliError("missing value for --data-dir");
+    return resolve(value);
+  }
+  return resolve(environment.AGENTROAM_DATA_DIR?.trim() || homeDir, environment.AGENTROAM_DATA_DIR?.trim() ? "" : ".agentroam");
+}
+
+function detectManagedTarget(platform, arch) {
+  if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+  if (platform === "win32" && arch === "x64") return "windows-amd64";
+  throw cliError(`managed Node.js is unsupported on ${platform}-${arch}`);
+}
+
+async function defaultFindSystemNode22(environment, platform, currentExecutable) {
+  const executableName = platform === "win32" ? "node.exe" : "node";
+  const pathDelimiter = platform === "win32" ? ";" : delimiter;
+  const currentDirectory = dirname(currentExecutable);
+  for (const directory of (environment.PATH ?? "").split(pathDelimiter).filter(Boolean)) {
+    if (resolve(directory) === resolve(currentDirectory)) continue;
+    const candidate = resolve(directory, executableName);
+    try {
+      await access(candidate);
+      const { stdout } = await execFileAsync(candidate, ["-p", "process.versions.node"], {
+        encoding: "utf8",
+        timeout: 5_000,
+        windowsHide: true,
+      });
+      if (Number(stdout.trim().split(".")[0]) === 22) return candidate;
+    } catch {
+      // Ignore broken or incompatible PATH entries and continue to the private runtime.
+    }
+  }
+  return null;
+}
+
+async function defaultSpawnChild(executable, args, options) {
+  const { spawn } = await import("node:child_process");
+  return spawn(executable, args, options);
+}
+
+function waitForChild(childPromise, processHost) {
+  return Promise.resolve(childPromise).then((child) => new Promise((resolveChild, rejectChild) => {
+    const listeners = new Map();
+    const cleanup = () => {
+      for (const [signal, listener] of listeners) processHost.off(signal, listener);
+    };
+    for (const signal of FORWARDED_SIGNALS) {
+      const listener = () => child.kill(signal);
+      listeners.set(signal, listener);
+      processHost.on(signal, listener);
+    }
+    child.once("error", (error) => {
+      cleanup();
+      rejectChild(error);
+    });
+    child.once("exit", (exitCode, signal) => {
+      cleanup();
+      resolveChild({ exitCode, signal });
+    });
+  }));
+}
+
+function standaloneInstallerMessage(platform) {
+  if (platform === "win32") {
+    return `Node.js 18+ is required for automatic bootstrap. Run: irm ${RELEASE_BASE_URL}/install-agentroam.ps1 | iex`;
+  }
+  return `Node.js 18+ is required for automatic bootstrap. Run: curl -fsSL ${RELEASE_BASE_URL}/install-agentroam.sh | sh`;
+}
+
+function cliError(message) {
+  return Object.assign(new Error(message), { exitCode: 2 });
+}

package/dist/args.js

@@ -3,10 +3,23 @@ import { resolve } from "node:path";
 export function parseArgs(argv) {
     const values = [...argv];
     let command = "start";
-    if (values[0] && ["start", "doctor", "version"].includes(values[0]))
+    if (values[0] && ["start", "doctor", "version", "service"].includes(values[0])) {
         command = values.shift();
+    }
+    let serviceAction = null;
+    if (command === "service") {
+        const action = values.shift();
+        if (!action || !["install", "start", "stop", "status", "url", "logs", "restart", "uninstall"].includes(action)) {
+            throw cliError("service requires install, start, stop, status, url, logs, restart, or uninstall");
+        }
+        serviceAction = action;
+        if (serviceAction !== "install" && values.length > 0) {
+            throw cliError(`service ${serviceAction} does not accept options`);
+        }
+    }
     const options = {
         command,
+        serviceAction,
         roots: [],
         port: null,
         relay: "auto",

package/dist/args.test.js

@@ -1,9 +1,11 @@
+import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
 import { parseArgs } from "./args.js";
 describe("parseArgs", () => {
     it("uses auto relay and the current directory by default", () => {
         const value = parseArgs([]);
         expect(value.command).toBe("start");
+        expect(value.serviceAction).toBeNull();
         expect(value.roots).toEqual([process.cwd()]);
         expect(value.relay).toBe("auto");
     });
@@ -24,4 +26,29 @@ describe("parseArgs", () => {
         expect(() => parseArgs(["--port", "70000"])).toThrow();
         expect(() => parseArgs(["--relay", "unknown"])).toThrow("relay must be auto");
     });
+    it("parses every service action", () => {
+        for (const action of ["install", "start", "stop", "status", "url", "logs", "restart", "uninstall"]) {
+            const value = parseArgs(["service", action]);
+            expect(value.command).toBe("service");
+            expect(value.serviceAction).toBe(action);
+        }
+    });
+    it("parses service install using the existing start options", () => {
+        const value = parseArgs([
+            "service", "install", "--root", ".", "--root", "..", "--port", "3210", "--relay", "cloudflare",
+            "--data-dir", "./service-data", "--no-qr",
+        ]);
+        expect(value.roots).toHaveLength(2);
+        expect(value.port).toBe(3210);
+        expect(value.relay).toBe("cloudflare");
+        expect(value.dataDir).toBe(resolve(process.cwd(), "service-data"));
+        expect(value.qr).toBe(false);
+    });
+    it("rejects missing service actions and options on non-install actions", () => {
+        expect(() => parseArgs(["service"])).toThrow("service requires");
+        expect(() => parseArgs(["service", "unknown"])).toThrow("service requires");
+        expect(() => parseArgs(["service", "status", "--root", "."])).toThrow("does not accept options");
+        expect(() => parseArgs(["service", "start", "--port", "3000"])).toThrow("does not accept options");
+        expect(() => parseArgs(["service", "stop", "--local-only"])).toThrow("does not accept options");
+    });
 });

package/dist/cli.js

@@ -1,17 +1,31 @@
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { ensureCloudflared } from "./cloudflared/installer.js";
+import { resolveCodexRuntime } from "./codex-runtime-manager.js";
 import { repairNativeRuntimePermissions } from "./native-runtime.js";
 import { findLanUrl } from "./network.js";
 import { createPairingSecret } from "./pairing.js";
 import { detectPlatform } from "./platform.js";
 import { AGENTROAM_VERSION, resolvePlatformRuntime, resolvePlatformTui } from "./platform-packages.js";
+import { acquireSleepInhibitor } from "./power/sleep-inhibitor.js";
 import { renderQr } from "./qr.js";
 import { RuntimeManager } from "./runtime-manager.js";
+import { ServiceRuntimeReporter } from "./service/runtime-state.js";
+import { runServiceCommand } from "./service/service-command.js";
+import { resolveServicePaths } from "./service/service-files.js";
 import { selectRelay } from "./tunnel/relay-orchestrator.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     const options = parseArgs(argv);
+    if (options.command === "service") {
+        await runServiceCommand(options, {
+            nodePath: process.execPath,
+            cliPath: fileURLToPath(new URL("../bin/agentroam.mjs", import.meta.url)),
+            version: VERSION,
+        });
+        return;
+    }
     const target = detectPlatform();
     if (options.command === "version") {
         console.log(`agentroam ${VERSION}`);
@@ -22,11 +36,15 @@ export async function main(argv) {
         return;
     }
     console.log(`AgentRoam ${VERSION}\n✓ Node ${process.versions.node} · ${target}`);
+    const sleepInhibitor = await acquireSleepInhibitor();
     const pairing = createPairingSecret();
     const controller = new AbortController();
     let runtime = null;
     let relay = null;
     let closing = false;
+    const serviceReporter = process.env.AGENTROAM_SERVICE === "1"
+        ? new ServiceRuntimeReporter(resolveServicePaths(undefined, options.dataDir), VERSION)
+        : null;
     const close = async () => {
         if (closing)
             return;
@@ -39,6 +57,7 @@ export async function main(argv) {
     process.once("SIGINT", requestClose);
     process.once("SIGTERM", requestClose);
     try {
+        await serviceReporter?.starting();
         runtime = await new RuntimeManager().start(options, pairing, target);
         console.log(`✓ Local server: ${runtime.localUrl}/web`);
         const lanUrl = findLanUrl(runtime.port) ?? runtime.localUrl;
@@ -52,6 +71,7 @@ export async function main(argv) {
             log: (line) => process.stderr.write(`${line}\n`),
             onAttempt: (provider) => console.log(`▲ Trying ${providerDisplayName(provider)} relay...`),
             onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} unavailable: ${message}`),
+            allowLanFallback: serviceReporter === null,
         });
         if (controller.signal.aborted)
             return;
@@ -69,18 +89,39 @@ export async function main(argv) {
             console.log("  The phone browser may show a one-time Pinggy security confirmation before pairing.");
         }
         const accessUrl = `${relay.publicUrl}/web${runtime.needsSetup ? `?pair=${encodeURIComponent(pairing.token)}` : ""}`;
-        console.log(`\nOpen: ${accessUrl}`);
-        if (options.qr)
-            console.log(`\n${await renderQr(accessUrl)}`);
-        if (runtime.needsSetup)
-            console.log("First pairing link expires in 5 minutes.");
-        console.log("Ctrl+C stops the tunnel and local server.");
-        await Promise.race([runtime.exited, relay.tunnel?.exited ?? new Promise(() => { })]);
+        await serviceReporter?.ready({
+            localUrl: runtime.localUrl,
+            publicUrl: relay.publicUrl,
+            accessUrl,
+            provider: relay.provider,
+        });
+        if (serviceReporter) {
+            console.log("✓ Background service URL written to the private state file.");
+        }
+        else {
+            console.log(`\nOpen: ${accessUrl}`);
+            if (options.qr)
+                console.log(`\n${await renderQr(accessUrl)}`);
+            if (runtime.needsSetup)
+                console.log("First pairing link expires in 5 minutes.");
+            console.log("Ctrl+C stops the tunnel and local server.");
+        }
+        await Promise.race([
+            runtime.exited,
+            relay.tunnel?.exited ?? new Promise(() => { }),
+            sleepInhibitor.lost.then(async (error) => {
+                await new Promise((resolveTurn) => setImmediate(resolveTurn));
+                if (!closing)
+                    throw error;
+            }),
+        ]);
     }
     finally {
         process.removeListener("SIGINT", requestClose);
         process.removeListener("SIGTERM", requestClose);
         await close();
+        await serviceReporter?.stopped().catch(() => { });
+        await sleepInhibitor.release();
     }
 }
 async function doctor(target, dataDir) {
@@ -111,6 +152,17 @@ async function doctor(target, dataDir) {
     catch (error) {
         reportDoctorFailure(error, "agent-tui: ");
     }
+    try {
+        const codex = await resolveCodexRuntime({
+            dataDir,
+            target,
+            onProgress: (message) => console.log(`… ${message}`),
+        });
+        console.log(`✓ Codex ${codex.version} (${codex.source}) ${codex.executable}`);
+    }
+    catch (error) {
+        reportDoctorFailure(error, "Codex: ");
+    }
     try {
         const executable = await ensureCloudflared(target, dataDir);
         console.log(`✓ cloudflared ${executable}`);

package/dist/cloudflared/bundled-asset.test.js

@@ -10,7 +10,7 @@ describe("resolveBundledCloudflared", () => {
         const archivePath = resolve(root, "cloudflared.tgz");
         await writeFile(archivePath, "archive");
         await writeFile(manifestPath, JSON.stringify({
-            packageVersion: "0.2.0-preview.8",
+            packageVersion: "0.2.0-preview.9",
             upstreamVersion: "2026.8.2",
             target: "darwin-arm64",
             assetFormat: "tgz",
@@ -51,7 +51,7 @@ describe("resolveBundledCloudflared", () => {
         const assetPath = resolve(root, "cloudflared.exe");
         await writeFile(assetPath, "binary");
         await writeFile(manifestPath, JSON.stringify({
-            packageVersion: "0.2.0-preview.8",
+            packageVersion: "0.2.0-preview.9",
             upstreamVersion: "2026.8.2",
             target: "windows-amd64",
             assetFormat: "executable",