agentroam 0.2.0-preview.7 → 0.2.0-preview.9

package/dist/service/macos-launch-agent.js

@@ -0,0 +1,250 @@
+import { constants } from "node:fs";
+import { access, chmod, mkdir, readFile, rename, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { SERVICE_LABEL, ensurePrivateDirectory, ensurePrivateFile, readServiceConfig, readServiceState, removeIfExists, resolveServicePaths, writePrivateJson, } from "./service-files.js";
+import { buildStartArguments, runCommand, } from "./service-controller.js";
+export { buildStartArguments } from "./service-controller.js";
+export class MacLaunchAgent {
+    homeDir;
+    uid;
+    runner;
+    processExists;
+    now;
+    readyTimeoutMs;
+    stopTimeoutMs;
+    pollIntervalMs;
+    constructor(options = {}) {
+        this.homeDir = options.homeDir;
+        this.uid = options.uid ?? process.getuid?.() ?? 0;
+        this.runner = options.runner ?? runCommand;
+        this.processExists = options.processExists ?? isProcessRunning;
+        this.now = options.now ?? (() => new Date());
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 120_000;
+        this.stopTimeoutMs = options.stopTimeoutMs ?? 15_000;
+        this.pollIntervalMs = options.pollIntervalMs ?? 250;
+    }
+    async install(config) {
+        await this.validateConfig(config);
+        const paths = resolveServicePaths(this.homeDir, config.dataDir);
+        await Promise.all([
+            mkdir(paths.launchAgentsDir, { recursive: true }),
+            ensurePrivateDirectory(paths.controlDir),
+            ensurePrivateDirectory(paths.logsDir),
+        ]);
+        await Promise.all([ensurePrivateFile(paths.stdoutPath), ensurePrivateFile(paths.stderrPath)]);
+        const jsonPath = resolve(paths.controlDir, "launch-agent.json.tmp");
+        const plistTempPath = resolve(paths.controlDir, "launch-agent.plist.tmp");
+        await removeIfExists(plistTempPath);
+        await writePrivateJson(jsonPath, buildLaunchAgentPlist(config, paths));
+        try {
+            await this.runRequired("plutil", ["-convert", "xml1", "-o", plistTempPath, jsonPath]);
+            await this.runRequired("plutil", ["-lint", plistTempPath]);
+            await chmod(plistTempPath, 0o600);
+            if ((await this.inspectJob()).loaded)
+                await this.runRequired("launchctl", ["bootout", this.serviceTarget]);
+            await rename(plistTempPath, paths.plistPath);
+            await chmod(paths.plistPath, 0o600);
+            await writePrivateJson(paths.configPath, config);
+            await Promise.all([removeIfExists(paths.statePath), removeIfExists(paths.urlPath)]);
+            await this.runRequired("launchctl", ["bootstrap", this.domainTarget, paths.plistPath]);
+        }
+        finally {
+            await Promise.all([removeIfExists(jsonPath), removeIfExists(plistTempPath)]);
+        }
+        return { paths, state: await this.waitForReady(paths), definition: paths.plistPath };
+    }
+    async start() {
+        const status = await this.status();
+        if (!status.installed)
+            throw new Error("AgentRoam service is not installed");
+        if (status.running)
+            return status.state;
+        if (status.loaded)
+            await this.runRequired("launchctl", ["kickstart", this.serviceTarget]);
+        else
+            await this.runRequired("launchctl", ["bootstrap", this.domainTarget, status.definition]);
+        const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
+        return this.waitForReady(paths, status.state?.pid);
+    }
+    async stop() {
+        const status = await this.status();
+        if (!status.installed)
+            throw new Error("AgentRoam service is not installed");
+        if (!status.loaded)
+            return;
+        await this.runRequired("launchctl", ["bootout", this.serviceTarget]);
+        if (status.state?.pid)
+            await this.waitForProcessExit(status.state.pid);
+    }
+    async status() {
+        const basePaths = resolveServicePaths(this.homeDir);
+        const config = await readServiceConfig(basePaths);
+        const paths = resolveServicePaths(this.homeDir, config?.dataDir);
+        const installed = await pathExists(paths.plistPath);
+        const job = installed ? await this.inspectJob() : { loaded: false, running: false };
+        return {
+            installed,
+            loaded: job.loaded,
+            running: job.running,
+            config,
+            state: await readServiceState(paths),
+            definition: paths.plistPath,
+        };
+    }
+    async url() {
+        const status = await this.status();
+        if (!status.installed)
+            throw new Error("AgentRoam service is not installed");
+        if (!status.running)
+            throw new Error("AgentRoam service is installed but not running");
+        if (status.state?.status !== "ready" || !status.state.accessUrl) {
+            throw new Error("AgentRoam service is still starting; try again shortly");
+        }
+        const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
+        const value = (await readFile(paths.urlPath, "utf8")).trim();
+        if (!value || value !== status.state.accessUrl)
+            throw new Error("AgentRoam service URL is unavailable or stale");
+        return value;
+    }
+    async logs(maxBytes = 64 * 1024) {
+        const basePaths = resolveServicePaths(this.homeDir);
+        const config = await readServiceConfig(basePaths);
+        const paths = resolveServicePaths(this.homeDir, config?.dataDir);
+        const [stdout, stderr] = await Promise.all([
+            readTail(paths.stdoutPath, maxBytes),
+            readTail(paths.stderrPath, maxBytes),
+        ]);
+        return { stdoutPath: paths.stdoutPath, stderrPath: paths.stderrPath, stdout, stderr };
+    }
+    async restart() {
+        const status = await this.status();
+        if (!status.installed)
+            throw new Error("AgentRoam service is not installed");
+        if (status.loaded)
+            await this.runRequired("launchctl", ["kickstart", "-k", this.serviceTarget]);
+        else
+            await this.runRequired("launchctl", ["bootstrap", this.domainTarget, status.definition]);
+        const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
+        return this.waitForReady(paths, status.state?.pid);
+    }
+    async uninstall() {
+        const basePaths = resolveServicePaths(this.homeDir);
+        const config = await readServiceConfig(basePaths);
+        const paths = resolveServicePaths(this.homeDir, config?.dataDir);
+        const installed = await pathExists(paths.plistPath);
+        const state = await readServiceState(paths);
+        if ((await this.inspectJob()).loaded) {
+            await this.runRequired("launchctl", ["bootout", this.serviceTarget]);
+            if (state?.pid)
+                await this.waitForProcessExit(state.pid);
+        }
+        await Promise.all([
+            removeIfExists(paths.plistPath),
+            removeIfExists(paths.configPath),
+            removeIfExists(paths.statePath),
+            removeIfExists(paths.urlPath),
+        ]);
+        return { removed: installed || Boolean(config), preservedDataDir: paths.dataDir };
+    }
+    get domainTarget() {
+        return `gui/${this.uid}`;
+    }
+    get serviceTarget() {
+        return `${this.domainTarget}/${SERVICE_LABEL}`;
+    }
+    async inspectJob() {
+        const result = await this.runner("launchctl", ["print", this.serviceTarget]);
+        return {
+            loaded: result.code === 0,
+            running: result.code === 0 && /\bstate\s*=\s*running\b/.test(result.stdout),
+        };
+    }
+    async runRequired(command, args) {
+        const result = await this.runner(command, args);
+        if (result.code !== 0) {
+            const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`;
+            throw new Error(`${command} ${args[0] ?? ""} failed: ${detail}`);
+        }
+        return result;
+    }
+    async validateConfig(config) {
+        if (!config.nodePath.startsWith("/") || !config.cliPath.startsWith("/")) {
+            throw new Error("AgentRoam service requires absolute Node and CLI paths");
+        }
+        if (config.cliPath.split("/").includes("_npx")) {
+            throw new Error("service install cannot use an npx temporary package; install AgentRoam with npm install -g first");
+        }
+        await Promise.all([
+            access(config.nodePath, constants.X_OK),
+            access(config.cliPath, constants.R_OK),
+            ...config.roots.map(async (root) => {
+                if (!(await stat(root)).isDirectory())
+                    throw new Error(`service root is not a directory: ${root}`);
+            }),
+        ]);
+    }
+    async waitForReady(paths, previousPid) {
+        const deadline = Date.now() + this.readyTimeoutMs;
+        do {
+            const state = await readServiceState(paths);
+            if (state?.status === "ready" && (!previousPid || state.pid !== previousPid))
+                return state;
+            if (Date.now() >= deadline)
+                return state;
+            await delay(this.pollIntervalMs);
+        } while (true);
+    }
+    async waitForProcessExit(pid) {
+        const deadline = Date.now() + this.stopTimeoutMs;
+        while (this.processExists(pid)) {
+            if (Date.now() >= deadline)
+                throw new Error(`service process ${pid} did not stop after launchctl bootout`);
+            await delay(this.pollIntervalMs);
+        }
+    }
+}
+export function buildLaunchAgentPlist(config, paths) {
+    return {
+        Label: SERVICE_LABEL,
+        ProgramArguments: buildStartArguments(config),
+        WorkingDirectory: config.roots[0],
+        EnvironmentVariables: { AGENTROAM_SERVICE: "1" },
+        RunAtLoad: true,
+        KeepAlive: true,
+        ThrottleInterval: 5,
+        StandardOutPath: paths.stdoutPath,
+        StandardErrorPath: paths.stderrPath,
+    };
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function readTail(path, maxBytes) {
+    try {
+        const value = await readFile(path);
+        return value.subarray(Math.max(0, value.length - maxBytes)).toString("utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+function delay(timeoutMs) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, timeoutMs));
+}

package/dist/service/macos-launch-agent.test.js

@@ -0,0 +1,197 @@
+import { chmod, mkdtemp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { MacLaunchAgent, buildLaunchAgentPlist, buildStartArguments, } from "./macos-launch-agent.js";
+import { resolveServicePaths, writePrivateJson, writePrivateText } from "./service-files.js";
+describe("MacLaunchAgent", () => {
+    it("builds one launchd job with separate absolute arguments", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-plist-"));
+        const paths = resolveServicePaths(home, resolve(home, "data with spaces"));
+        const value = config(home, paths.dataDir);
+        expect(buildStartArguments(value)).toEqual([
+            value.nodePath, value.cliPath, "start", "--root", value.roots[0], "--root", value.roots[1],
+            "--port", "3001", "--relay", "custom", "--tunnel-command", "relay --port {port}",
+            "--data-dir", paths.dataDir, "--no-qr",
+        ]);
+        expect(buildLaunchAgentPlist(value, paths)).toMatchObject({
+            Label: "com.agentroam.service",
+            WorkingDirectory: value.roots[0],
+            RunAtLoad: true,
+            KeepAlive: true,
+            ThrottleInterval: 5,
+            EnvironmentVariables: { AGENTROAM_SERVICE: "1" },
+        });
+    });
+    it("installs, reloads, and waits for a ready service", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-install-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await createConfigFiles(value);
+        const calls = [];
+        let printCount = 0;
+        const runner = async (command, args) => {
+            calls.push([command, ...args]);
+            if (command === "plutil" && args[0] === "-convert") {
+                await writeFile(args[3], "<?xml version=\"1.0\"?><plist version=\"1.0\"><dict/></plist>");
+            }
+            if (command === "launchctl" && args[0] === "print") {
+                printCount++;
+                return { code: printCount === 1 ? 0 : 1, stdout: "state = exited", stderr: "" };
+            }
+            if (command === "launchctl" && args[0] === "bootstrap") {
+                await writePrivateJson(paths.statePath, {
+                    status: "ready", pid: 777, version: value.version, startedAt: value.installedAt,
+                    updatedAt: value.installedAt, accessUrl: "https://ready.example/web",
+                });
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const result = await new MacLaunchAgent({ homeDir: home, uid: 501, runner, readyTimeoutMs: 10 }).install(value);
+        expect(result.state).toMatchObject({ status: "ready", pid: 777 });
+        expect(calls).toContainEqual(["launchctl", "bootout", "gui/501/com.agentroam.service"]);
+        expect(calls).toContainEqual(["launchctl", "bootstrap", "gui/501", paths.plistPath]);
+        expect((await stat(paths.plistPath)).mode & 0o777).toBe(0o600);
+        expect(JSON.parse(await readFile(paths.configPath, "utf8"))).toMatchObject({ roots: value.roots });
+    });
+    it("reports ready URLs only while the installed job is running", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-url-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await mkdir(paths.launchAgentsDir, { recursive: true });
+        await writeFile(paths.plistPath, "plist");
+        await writePrivateJson(paths.configPath, value);
+        await writePrivateJson(paths.statePath, {
+            status: "ready", pid: 777, version: value.version, startedAt: value.installedAt,
+            updatedAt: value.installedAt, accessUrl: "https://ready.example/web",
+        });
+        await writePrivateText(paths.urlPath, "https://ready.example/web\n");
+        const running = async () => ({ code: 0, stdout: "state = running", stderr: "" });
+        expect(await new MacLaunchAgent({ homeDir: home, uid: 501, runner: running }).url())
+            .toBe("https://ready.example/web");
+        await writePrivateText(paths.urlPath, "https://stale.example/web\n");
+        await expect(new MacLaunchAgent({ homeDir: home, uid: 501, runner: running }).url()).rejects.toThrow("stale");
+    });
+    it("starts and stops an installed service while preserving registration", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-start-stop-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await mkdir(paths.launchAgentsDir, { recursive: true });
+        await writeFile(paths.plistPath, "plist");
+        await writePrivateJson(paths.configPath, value);
+        await writePrivateJson(paths.statePath, {
+            status: "stopped", pid: 700, version: value.version, startedAt: "x", updatedAt: "x",
+        });
+        let loaded = false;
+        let processRunning = false;
+        const calls = [];
+        const runner = async (command, args) => {
+            calls.push([command, ...args]);
+            if (command === "launchctl" && args[0] === "print") {
+                return { code: loaded ? 0 : 1, stdout: loaded ? "state = running" : "", stderr: "" };
+            }
+            if (command === "launchctl" && args[0] === "bootstrap") {
+                loaded = true;
+                processRunning = true;
+                await writePrivateJson(paths.statePath, {
+                    status: "ready", pid: 701, version: value.version, startedAt: "y", updatedAt: "y",
+                    accessUrl: "https://ready.example/web",
+                });
+            }
+            if (command === "launchctl" && args[0] === "bootout") {
+                loaded = false;
+                processRunning = false;
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const launchAgent = new MacLaunchAgent({
+            homeDir: home,
+            uid: 501,
+            runner,
+            processExists: () => processRunning,
+            readyTimeoutMs: 50,
+            stopTimeoutMs: 50,
+            pollIntervalMs: 1,
+        });
+        const state = await launchAgent.start();
+        expect(state).toMatchObject({ status: "ready", pid: 701 });
+        expect((await launchAgent.status()).definition).toBe(paths.plistPath);
+        await launchAgent.stop();
+        expect(calls).toContainEqual(["launchctl", "bootstrap", "gui/501", paths.plistPath]);
+        expect(calls).toContainEqual(["launchctl", "bootout", "gui/501/com.agentroam.service"]);
+        expect(await readFile(paths.plistPath, "utf8")).toBe("plist");
+        expect(JSON.parse(await readFile(paths.configPath, "utf8"))).toMatchObject({ version: value.version });
+    });
+    it("uninstalls service control files but preserves application data and logs", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-uninstall-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await mkdir(paths.launchAgentsDir, { recursive: true });
+        await writeFile(paths.plistPath, "plist");
+        await writePrivateJson(paths.configPath, value);
+        await writePrivateJson(paths.statePath, { status: "starting", pid: 1, version: value.version, startedAt: "x", updatedAt: "x" });
+        await writePrivateText(paths.urlPath, "url\n");
+        await writePrivateText(resolve(paths.dataDir, "data/keep.txt"), "keep");
+        await writePrivateText(paths.stdoutPath, "keep logs");
+        const calls = [];
+        let processRunning = true;
+        let exitWrite = null;
+        const runner = async (command, args) => {
+            calls.push([command, ...args]);
+            if (command === "launchctl" && args[0] === "bootout") {
+                exitWrite = writePrivateJson(paths.statePath, {
+                    status: "stopped", pid: 1, version: value.version, startedAt: "x", updatedAt: "x",
+                }).then(() => { processRunning = false; });
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const processExists = vi.fn(() => processRunning);
+        const result = await new MacLaunchAgent({
+            homeDir: home,
+            uid: 501,
+            runner,
+            processExists,
+            pollIntervalMs: 1,
+            stopTimeoutMs: 100,
+        }).uninstall();
+        await exitWrite;
+        expect(result).toEqual({ removed: true, preservedDataDir: paths.dataDir });
+        expect(calls).toContainEqual(["launchctl", "bootout", "gui/501/com.agentroam.service"]);
+        expect(processExists).toHaveBeenCalled();
+        await expect(readFile(paths.configPath)).rejects.toMatchObject({ code: "ENOENT" });
+        await expect(readFile(paths.statePath)).rejects.toMatchObject({ code: "ENOENT" });
+        expect(await readFile(resolve(paths.dataDir, "data/keep.txt"), "utf8")).toBe("keep");
+        expect(await readFile(paths.stdoutPath, "utf8")).toBe("keep logs");
+    });
+    it("rejects an npx cache entrypoint", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-npx-"));
+        const value = config(home, resolve(home, ".agentroam"));
+        value.cliPath = resolve(home, ".npm/_npx/hash/node_modules/agentroam/bin/agentroam.mjs");
+        await expect(new MacLaunchAgent({ homeDir: home }).install(value)).rejects.toThrow("npm install -g");
+    });
+});
+function config(home, dataDir) {
+    const nodePath = resolve(home, "bin/node");
+    const cliPath = resolve(home, "lib/agentroam/bin/agentroam.mjs");
+    const roots = [resolve(home, "workspace one"), resolve(home, "workspace-two")];
+    return {
+        version: "0.2.0-preview.9",
+        nodePath,
+        cliPath,
+        roots,
+        port: 3001,
+        relay: "custom",
+        tunnelCommand: "relay --port {port}",
+        localOnly: false,
+        dataDir,
+        installedAt: "2026-09-03T00:00:00.000Z",
+    };
+}
+async function createConfigFiles(value) {
+    await Promise.all([
+        writePrivateText(value.nodePath, "node"),
+        writePrivateText(value.cliPath, "cli"),
+        ...value.roots.map((root) => mkdir(root, { recursive: true })),
+    ]);
+    await chmod(value.nodePath, 0o700);
+}

package/dist/service/runtime-state.js

@@ -0,0 +1,40 @@
+import { readServiceState, removeIfExists, writePrivateJson, writePrivateText, } from "./service-files.js";
+export class ServiceRuntimeReporter {
+    paths;
+    version;
+    pid;
+    now;
+    startedAt;
+    constructor(paths, version, pid = process.pid, now = () => new Date()) {
+        this.paths = paths;
+        this.version = version;
+        this.pid = pid;
+        this.now = now;
+        this.startedAt = this.now().toISOString();
+    }
+    async starting() {
+        await removeIfExists(this.paths.urlPath);
+        await this.write({ status: "starting" });
+    }
+    async ready(ready) {
+        await this.write({ status: "ready", ...ready });
+        await writePrivateText(this.paths.urlPath, `${ready.accessUrl}\n`);
+    }
+    async stopped() {
+        const current = await readServiceState(this.paths);
+        if (!current || current.pid !== this.pid)
+            return false;
+        await this.write({ status: "stopped" });
+        await removeIfExists(this.paths.urlPath);
+        return true;
+    }
+    async write(details) {
+        await writePrivateJson(this.paths.statePath, {
+            pid: this.pid,
+            version: this.version,
+            startedAt: this.startedAt,
+            updatedAt: this.now().toISOString(),
+            ...details,
+        });
+    }
+}

package/dist/service/runtime-state.test.js

@@ -0,0 +1,43 @@
+import { access, mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ServiceRuntimeReporter } from "./runtime-state.js";
+import { readServiceState, resolveServicePaths, writePrivateJson } from "./service-files.js";
+describe("ServiceRuntimeReporter", () => {
+    it("publishes starting, ready, and stopped state without leaving a stale URL", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-service-state-"));
+        const paths = resolveServicePaths(home);
+        let tick = 0;
+        const reporter = new ServiceRuntimeReporter(paths, "0.2.0-preview.9", 123, () => new Date(1_000 + tick++));
+        await reporter.starting();
+        expect(await readServiceState(paths)).toMatchObject({ status: "starting", pid: 123, version: "0.2.0-preview.9" });
+        await expect(access(paths.urlPath)).rejects.toMatchObject({ code: "ENOENT" });
+        await reporter.ready({
+            localUrl: "http://127.0.0.1:3000",
+            publicUrl: "https://example.trycloudflare.com",
+            accessUrl: "https://example.trycloudflare.com/web?pair=secret",
+            provider: "cloudflare",
+        });
+        expect(await readServiceState(paths)).toMatchObject({ status: "ready", provider: "cloudflare" });
+        expect(await readFile(paths.urlPath, "utf8")).toBe("https://example.trycloudflare.com/web?pair=secret\n");
+        expect(await reporter.stopped()).toBe(true);
+        expect(await readServiceState(paths)).toMatchObject({ status: "stopped", pid: 123 });
+        await expect(access(paths.urlPath)).rejects.toMatchObject({ code: "ENOENT" });
+    });
+    it("does not let an older process clear a newer process state", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-service-state-race-"));
+        const paths = resolveServicePaths(home);
+        const reporter = new ServiceRuntimeReporter(paths, "old", 123);
+        await writePrivateJson(paths.statePath, {
+            status: "ready",
+            pid: 456,
+            version: "new",
+            startedAt: "2026-09-03T00:00:00.000Z",
+            updatedAt: "2026-09-03T00:00:01.000Z",
+            accessUrl: "https://new.example/web",
+        });
+        expect(await reporter.stopped()).toBe(false);
+        expect(await readServiceState(paths)).toMatchObject({ status: "ready", pid: 456 });
+    });
+});

package/dist/service/service-command.js

@@ -0,0 +1,100 @@
+import { MacLaunchAgent } from "./macos-launch-agent.js";
+import { WindowsTaskService } from "./windows-task-service.js";
+export async function runServiceCommand(options, context) {
+    const platform = context.platform ?? process.platform;
+    const log = context.log ?? console.log;
+    const controller = context.controller ?? context.launchAgent ?? createController(platform, context.homeDir);
+    switch (options.serviceAction) {
+        case "install": {
+            const nodeVersion = context.nodeVersion ?? process.versions.node;
+            if (Number(nodeVersion.split(".")[0]) !== 22) {
+                throw cliError(`Node.js 22 is required to install the service (current ${nodeVersion})`);
+            }
+            const now = context.now?.() ?? new Date();
+            const config = {
+                version: context.version,
+                nodePath: context.nodePath,
+                cliPath: context.cliPath,
+                roots: options.roots,
+                port: options.port,
+                relay: options.relay,
+                tunnelCommand: options.tunnelCommand,
+                localOnly: options.localOnly,
+                dataDir: options.dataDir,
+                installedAt: now.toISOString(),
+            };
+            const { definition, state } = await controller.install(config);
+            log(`✓ AgentRoam service installed: ${definition}`);
+            if (state?.status === "ready" && state.accessUrl)
+                log(`Open: ${state.accessUrl}`);
+            else
+                log("Service is starting. Run `agentroam service url` shortly.");
+            return;
+        }
+        case "start": {
+            const state = await controller.start();
+            log("✓ AgentRoam service started");
+            if (state?.status === "ready" && state.accessUrl)
+                log(`Open: ${state.accessUrl}`);
+            return;
+        }
+        case "stop":
+            await controller.stop();
+            log("✓ AgentRoam service stopped");
+            return;
+        case "status": {
+            const status = await controller.status();
+            if (!status.installed) {
+                log("AgentRoam service: not installed");
+                return;
+            }
+            log(`AgentRoam service: ${status.running ? "running" : "installed but stopped"}`);
+            if (status.config) {
+                log(`Version: ${status.config.version}`);
+                log(`Root: ${status.config.roots.join(", ")}`);
+            }
+            if (status.running && status.state?.status === "ready" && status.state.accessUrl) {
+                log(`Open: ${status.state.accessUrl}`);
+            }
+            return;
+        }
+        case "url":
+            log(await controller.url());
+            return;
+        case "logs": {
+            const logs = await controller.logs();
+            log(`stdout: ${logs.stdoutPath}`);
+            if (logs.stdout)
+                log(logs.stdout.trimEnd());
+            log(`stderr: ${logs.stderrPath}`);
+            if (logs.stderr)
+                log(logs.stderr.trimEnd());
+            return;
+        }
+        case "restart": {
+            const state = await controller.restart();
+            log("✓ AgentRoam service restarted");
+            if (state?.status === "ready" && state.accessUrl)
+                log(`Open: ${state.accessUrl}`);
+            return;
+        }
+        case "uninstall": {
+            const result = await controller.uninstall();
+            log(result.removed ? "✓ AgentRoam service uninstalled" : "AgentRoam service was not installed");
+            log(`Application data preserved: ${result.preservedDataDir}`);
+            return;
+        }
+        default:
+            throw cliError("service action is required");
+    }
+}
+function createController(platform, homeDir) {
+    if (platform === "darwin")
+        return new MacLaunchAgent({ homeDir });
+    if (platform === "win32")
+        return new WindowsTaskService({ homeDir });
+    throw cliError(`agentroam service is unavailable on ${platform}; supported platforms are macOS and Windows`);
+}
+function cliError(message) {
+    return Object.assign(new Error(message), { exitCode: 2 });
+}