agentroam 0.2.0-preview.2 → 0.2.0-preview.4

package/README.md

@@ -7,7 +7,7 @@ Zero-install mobile remote terminal and file console. **No desktop app, no VPN**
 - **Node.js 22** (required)
 - macOS arm64
 
-> Preview status: `0.2.0-preview.2` is intentionally limited to macOS arm64.
+> Preview status: `0.2.0-preview.3` is intentionally limited to macOS arm64.
 > macOS x64 and Windows x64 remain future formal-release targets.
 
 ## Quick start
@@ -19,13 +19,13 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-0.2.0-preview.2.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.3.tgz ./agentroam-0.2.0-preview.3.tgz
 npx agentroam
 ```
 
 On first run:
 
-1. A **Cloudflare Quick Tunnel** exposes your local server (HTTPS, no account needed).
+1. AgentRoam tries a bundled **Cloudflare Quick Tunnel**, then a **Pinggy HTTPS tunnel** over SSH port 443.
 2. A **QR code** prints in the terminal — scan it on your phone.
 3. Complete **one-time pairing** (5-minute token) and create the admin account.
 4. Use the web terminal + file tree remotely.
@@ -44,19 +44,21 @@ agentroam version
 |------|-------------|
 | `--root <path>` | Workspace root (repeatable). Default: cwd |
 | `--local-only` | Skip tunnel; LAN/localhost only |
-| `--relay cloudflare` | Quick Tunnel (default) |
+| `--relay auto` | Cloudflare, then Pinggy, then LAN (default) |
+| `--relay cloudflare` | Cloudflare only, then LAN |
+| `--relay pinggy` | Pinggy only, then LAN |
 | `--relay custom --tunnel-command "<cmd>"` | Your own tunnel command |
 | `--no-qr` | Don't print QR code |
 | `--port <n>` | Fixed local port |
 | `--data-dir <path>` | State directory (default: `~/.agentroam`) |
 
-If Cloudflare or GitHub is blocked on your network, AgentRoam reuses a `cloudflared` executable already on `PATH`; otherwise use the LAN QR code, `--local-only`, or `--relay custom`.
+The macOS arm64 cloudflared binary is installed from npm as a verified platform package, so startup does not download from GitHub. If Cloudflare cannot connect, automatic mode tries Pinggy over outbound SSH port 443. Pinggy free tunnels last up to 60 minutes and may show a one-time security confirmation in the phone browser. If neither public relay works, the QR code uses a LAN address and the phone must be on the same local network.
 
 ## What's included
 
 - Next.js **standalone** web gateway + WebSocket PTY server
 - `@agent/core` bundled runtime
-- Optional **cloudflared** download (verified SHA-256)
+- Optional platform **cloudflared** package (verified size + SHA-256 before execution)
 - **Pairing token** + secure cookies behind HTTPS tunnel
 
 Not included: Electron desktop app, SDK, dev `.env`, session caches.
@@ -64,11 +66,10 @@ Not included: Electron desktop app, SDK, dev `.env`, session caches.
 ## Release verification (maintainers)
 
 ```bash
-bun run build:cli
-cd packages/cli && npm pack
-node ../../scripts/audit-cli-tarball.mjs agentroam-0.2.0-preview.2.tgz
-node ../../scripts/verify-cli-install.mjs --node /opt/homebrew/opt/node@22/bin/node
-node ../../scripts/verify-cli-tunnel.mjs --node /opt/homebrew/opt/node@22/bin/node
+npm run fetch:cloudflared
+npm run pack:cli
+node scripts/verify-cli-install.mjs --node /path/to/node22
+node scripts/verify-cli-tunnel.mjs --node /path/to/node22 --provider auto
 ```
 
 Windows ConPTY remains a formal-release target and is not included in this preview.

package/dist/args.js

@@ -5,11 +5,24 @@ export function parseArgs(argv) {
     let command = "start";
     if (values[0] && ["start", "doctor", "version"].includes(values[0]))
         command = values.shift();
-    const options = { command, roots: [], port: null, relay: "cloudflare", tunnelCommand: null, localOnly: false, qr: true, dataDir: resolve(homedir(), ".agentroam") };
-    for (let i = 0; i < values.length; i++) {
-        const arg = values[i];
-        const next = () => { const value = values[++i]; if (!value)
-            throw cliError(`missing value for ${arg}`); return value; };
+    const options = {
+        command,
+        roots: [],
+        port: null,
+        relay: "auto",
+        tunnelCommand: null,
+        localOnly: false,
+        qr: true,
+        dataDir: resolve(homedir(), ".agentroam"),
+    };
+    for (let index = 0; index < values.length; index++) {
+        const arg = values[index];
+        const next = () => {
+            const value = values[++index];
+            if (!value)
+                throw cliError(`missing value for ${arg}`);
+            return value;
+        };
         if (arg === "--root")
             options.roots.push(resolve(next()));
         else if (arg === "--port") {
@@ -20,8 +33,9 @@ export function parseArgs(argv) {
         }
         else if (arg === "--relay") {
             const relay = next();
-            if (relay !== "cloudflare" && relay !== "custom")
-                throw cliError("relay must be cloudflare or custom");
+            if (!["auto", "cloudflare", "pinggy", "custom"].includes(relay)) {
+                throw cliError("relay must be auto, cloudflare, pinggy, or custom");
+            }
             options.relay = relay;
         }
         else if (arg === "--tunnel-command")
@@ -43,4 +57,6 @@ export function parseArgs(argv) {
         throw cliError("--relay custom requires --tunnel-command");
     return options;
 }
-function cliError(message) { return Object.assign(new Error(message), { exitCode: 2 }); }
+function cliError(message) {
+    return Object.assign(new Error(message), { exitCode: 2 });
+}

package/dist/args.test.js

@@ -1,3 +1,27 @@
 import { describe, expect, it } from "vitest";
 import { parseArgs } from "./args.js";
-describe("parseArgs", () => { it("uses safe defaults", () => { const value = parseArgs([]); expect(value.command).toBe("start"); expect(value.roots).toEqual([process.cwd()]); expect(value.relay).toBe("cloudflare"); }); it("parses repeatable roots and custom relay", () => { const value = parseArgs(["start", "--root", ".", "--root", "..", "--relay", "custom", "--tunnel-command", "relay {port}", "--no-qr"]); expect(value.roots).toHaveLength(2); expect(value.tunnelCommand).toContain("{port}"); expect(value.qr).toBe(false); }); it("rejects invalid ports", () => expect(() => parseArgs(["--port", "70000"])).toThrow()); });
+describe("parseArgs", () => {
+    it("uses auto relay and the current directory by default", () => {
+        const value = parseArgs([]);
+        expect(value.command).toBe("start");
+        expect(value.roots).toEqual([process.cwd()]);
+        expect(value.relay).toBe("auto");
+    });
+    it("parses every supported relay", () => {
+        expect(parseArgs(["--relay", "cloudflare"]).relay).toBe("cloudflare");
+        expect(parseArgs(["--relay", "pinggy"]).relay).toBe("pinggy");
+        expect(parseArgs(["--relay", "custom", "--tunnel-command", "relay {port}"]).relay).toBe("custom");
+    });
+    it("parses repeatable roots and custom relay options", () => {
+        const value = parseArgs([
+            "start", "--root", ".", "--root", "..", "--relay", "custom", "--tunnel-command", "relay {port}", "--no-qr",
+        ]);
+        expect(value.roots).toHaveLength(2);
+        expect(value.tunnelCommand).toContain("{port}");
+        expect(value.qr).toBe(false);
+    });
+    it("rejects invalid ports and relay names", () => {
+        expect(() => parseArgs(["--port", "70000"])).toThrow();
+        expect(() => parseArgs(["--relay", "unknown"])).toThrow("relay must be auto");
+    });
+});

package/dist/cli.js

@@ -1,66 +1,126 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
-import { detectPlatform } from "./platform.js";
-import { RuntimeManager } from "./runtime-manager.js";
-import { createPairingSecret } from "./pairing.js";
-import { renderQr } from "./qr.js";
 import { ensureCloudflared } from "./cloudflared/installer.js";
-import { CloudflareTunnelProvider } from "./tunnel/cloudflare-provider.js";
-import { CustomCommandTunnelProvider } from "./tunnel/custom-command-provider.js";
-import { findLanUrl } from "./network.js";
 import { repairNativeRuntimePermissions } from "./native-runtime.js";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-export async function main(argv) { const options = parseArgs(argv); const target = detectPlatform(); if (options.command === "version") {
-    console.log("agentroam 0.2.0-preview.2");
-    return;
-} if (options.command === "doctor") {
-    await doctor(target, options.dataDir);
-    return;
-} console.log(`AgentRoam 0.2.0-preview.2\n✓ Node ${process.versions.node} · ${target}`); const pairing = createPairingSecret(); const controller = new AbortController(); const runtime = await new RuntimeManager().start(options, pairing); console.log(`✓ Local server: ${runtime.localUrl}/web`); const lanUrl = findLanUrl(runtime.port) ?? runtime.localUrl; let tunnel = null; let publicUrl = options.localOnly ? lanUrl : runtime.localUrl; try {
-    if (!options.localOnly) {
-        if (options.relay === "cloudflare") {
-            const executable = await ensureCloudflared(target, options.dataDir);
-            tunnel = await retry(() => new CloudflareTunnelProvider(executable).start({ localUrl: runtime.localUrl, signal: controller.signal, log: line => process.stderr.write(`${line}\n`) }), 3);
+import { findLanUrl } from "./network.js";
+import { createPairingSecret } from "./pairing.js";
+import { detectPlatform } from "./platform.js";
+import { renderQr } from "./qr.js";
+import { RuntimeManager } from "./runtime-manager.js";
+import { selectRelay } from "./tunnel/relay-orchestrator.js";
+const VERSION = "0.2.0-preview.4";
+export async function main(argv) {
+    const options = parseArgs(argv);
+    const target = detectPlatform();
+    if (options.command === "version") {
+        console.log(`agentroam ${VERSION}`);
+        return;
+    }
+    if (options.command === "doctor") {
+        await doctor(target, options.dataDir);
+        return;
+    }
+    console.log(`AgentRoam ${VERSION}\n✓ Node ${process.versions.node} · ${target}`);
+    const pairing = createPairingSecret();
+    const controller = new AbortController();
+    let runtime = null;
+    let relay = null;
+    let closing = false;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        controller.abort();
+        await relay?.tunnel?.close().catch(() => { });
+        await runtime?.close().catch(() => { });
+    };
+    const requestClose = () => void close();
+    process.once("SIGINT", requestClose);
+    process.once("SIGTERM", requestClose);
+    try {
+        runtime = await new RuntimeManager().start(options, pairing);
+        console.log(`✓ Local server: ${runtime.localUrl}/web`);
+        const lanUrl = findLanUrl(runtime.port) ?? runtime.localUrl;
+        relay = await selectRelay({
+            cli: options,
+            target,
+            localUrl: runtime.localUrl,
+            lanUrl,
+            port: runtime.port,
+            signal: controller.signal,
+            log: (line) => process.stderr.write(`${line}\n`),
+            onAttempt: (provider) => console.log(`▲ Trying ${providerDisplayName(provider)} relay...`),
+            onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} unavailable: ${message}`),
+        });
+        if (controller.signal.aborted)
+            return;
+        if (relay.provider === "lan") {
+            if (relay.failures.length > 0)
+                console.error(`  Continuing with local network access: ${relay.publicUrl}/web`);
+            else
+                console.log(`✓ Local network: ${relay.publicUrl}/web`);
+        }
+        else {
+            console.log(`✓ ${providerDisplayName(relay.provider)} tunnel ready: ${relay.publicUrl}`);
+        }
+        if (relay.provider === "pinggy") {
+            console.log("  Pinggy free tunnels expire after 60 minutes and use a new hostname each session.");
+            console.log("  The phone browser may show a one-time Pinggy security confirmation before pairing.");
         }
-        else
-            tunnel = await new CustomCommandTunnelProvider(options.tunnelCommand, runtime.port).start({ localUrl: runtime.localUrl, signal: controller.signal, log: line => process.stderr.write(`${line}\n`) });
-        publicUrl = tunnel.publicUrl;
-        console.log(`✓ Tunnel: ${publicUrl}`);
+        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(() => { })]);
+    }
+    finally {
+        process.removeListener("SIGINT", requestClose);
+        process.removeListener("SIGTERM", requestClose);
+        await close();
     }
 }
-catch (error) {
-    publicUrl = lanUrl;
-    console.error(`⚠ Tunnel unavailable: ${error instanceof Error ? error.message : error}`);
-    console.error(`  Continuing with local network access: ${publicUrl}/web`);
-    console.error("  Use --relay custom when Cloudflare is blocked.");
-} const accessUrl = `${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."); let closing = false; const close = async () => { if (closing)
-    return; closing = true; controller.abort(); await tunnel?.close().catch(() => { }); await runtime.close(); }; process.once("SIGINT", () => void close()); process.once("SIGTERM", () => void close()); await Promise.race([runtime.exited, tunnel?.exited ?? new Promise(() => { })]); await close(); }
-async function doctor(target, dataDir) { console.log(`✓ Node ${process.versions.node}`); console.log(`✓ Platform ${target}`); const runtimeRoot = fileURLToPath(new URL("../runtime/", import.meta.url)); const runtimeRequire = createRequire(fileURLToPath(new URL("../runtime/package.json", import.meta.url))); try {
-    await repairNativeRuntimePermissions(runtimeRoot);
-    console.log("✓ node-pty spawn-helper executable");
-}
-catch (error) {
-    console.log(`✗ ${error instanceof Error ? error.message : error}`);
-    process.exitCode = 1;
-} for (const module of ["node-pty", "better-sqlite3"]) {
+async function doctor(target, dataDir) {
+    console.log(`✓ Node ${process.versions.node}`);
+    console.log(`✓ Platform ${target}`);
+    const runtimeRoot = fileURLToPath(new URL("../runtime/", import.meta.url));
+    const runtimeRequire = createRequire(fileURLToPath(new URL("../runtime/package.json", import.meta.url)));
     try {
-        runtimeRequire(module);
-        console.log(`✓ ${module}`);
+        await repairNativeRuntimePermissions(runtimeRoot);
+        console.log("✓ node-pty spawn-helper executable");
     }
     catch (error) {
-        console.log(`✗ ${module}: ${error instanceof Error ? error.message : error}`);
-        process.exitCode = 1;
+        reportDoctorFailure(error);
+    }
+    for (const module of ["node-pty", "better-sqlite3"]) {
+        try {
+            runtimeRequire(module);
+            console.log(`✓ ${module}`);
+        }
+        catch (error) {
+            reportDoctorFailure(error, `${module}: `);
+        }
     }
-} console.log(`✓ Data directory ${dataDir}`); }
-async function retry(fn, count) { let last; for (let attempt = 1; attempt <= count; attempt++) {
     try {
-        return await fn();
+        const executable = await ensureCloudflared(target, dataDir);
+        console.log(`✓ cloudflared ${executable}`);
     }
     catch (error) {
-        last = error;
-        if (attempt < count)
-            await new Promise(resolve => setTimeout(resolve, attempt * 750));
+        reportDoctorFailure(error, "cloudflared: ");
     }
-} throw last; }
+    console.log(`✓ Data directory ${dataDir}`);
+}
+function reportDoctorFailure(error, prefix = "") {
+    console.log(`✗ ${prefix}${error instanceof Error ? error.message : error}`);
+    process.exitCode = 1;
+}
+function providerDisplayName(provider) {
+    if (provider === "cloudflare")
+        return "Cloudflare";
+    if (provider === "pinggy")
+        return "Pinggy";
+    return "Custom";
+}

package/dist/cloudflared/bundled-asset.js

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { CLOUDFLARED_PACKAGES, CLOUDFLARED_PACKAGE_VERSION } from "./manifest.js";
+export async function resolveBundledCloudflared(target, requireFromCli = createRequire(import.meta.url)) {
+    const packageName = CLOUDFLARED_PACKAGES[target];
+    if (!packageName)
+        return null;
+    let manifestPath;
+    let archivePath;
+    try {
+        manifestPath = requireFromCli.resolve(`${packageName}/manifest.json`);
+        archivePath = requireFromCli.resolve(`${packageName}/archive`);
+    }
+    catch (error) {
+        if (error?.code === "MODULE_NOT_FOUND")
+            return null;
+        throw error;
+    }
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (manifest.packageVersion !== CLOUDFLARED_PACKAGE_VERSION ||
+        manifest.target !== target ||
+        typeof manifest.upstreamVersion !== "string" ||
+        typeof manifest.fileName !== "string" ||
+        typeof manifest.size !== "number" ||
+        !Number.isSafeInteger(manifest.size) ||
+        typeof manifest.sha256 !== "string" ||
+        !/^[a-f0-9]{64}$/.test(manifest.sha256)) {
+        throw new Error(`invalid cloudflared platform manifest: ${manifestPath}`);
+    }
+    return {
+        archivePath,
+        sha256: manifest.sha256,
+        size: manifest.size,
+        fileName: manifest.fileName,
+        version: manifest.upstreamVersion,
+    };
+}

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

@@ -0,0 +1,50 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveBundledCloudflared } from "./bundled-asset.js";
+describe("resolveBundledCloudflared", () => {
+    it("resolves a valid platform package manifest and archive", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-bundled-resolver-"));
+        const manifestPath = resolve(root, "manifest.json");
+        const archivePath = resolve(root, "cloudflared.tgz");
+        await writeFile(archivePath, "archive");
+        await writeFile(manifestPath, JSON.stringify({
+            packageVersion: "0.2.0-preview.4",
+            upstreamVersion: "2026.8.2",
+            target: "darwin-arm64",
+            fileName: "cloudflared",
+            size: 7,
+            sha256: "a".repeat(64),
+        }));
+        const asset = await resolveBundledCloudflared("darwin-arm64", fakeRequire(manifestPath, archivePath));
+        expect(asset).toEqual({
+            archivePath,
+            version: "2026.8.2",
+            fileName: "cloudflared",
+            size: 7,
+            sha256: "a".repeat(64),
+        });
+    });
+    it("rejects a mismatched platform package version", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-bundled-version-"));
+        const manifestPath = resolve(root, "manifest.json");
+        const archivePath = resolve(root, "cloudflared.tgz");
+        await writeFile(archivePath, "archive");
+        await writeFile(manifestPath, JSON.stringify({
+            packageVersion: "0.2.0-preview.2",
+            upstreamVersion: "2026.8.2",
+            target: "darwin-arm64",
+            fileName: "cloudflared",
+            size: 7,
+            sha256: "a".repeat(64),
+        }));
+        await expect(resolveBundledCloudflared("darwin-arm64", fakeRequire(manifestPath, archivePath)))
+            .rejects.toThrow("invalid cloudflared platform manifest");
+    });
+});
+function fakeRequire(manifestPath, archivePath) {
+    return {
+        resolve: (id) => id.endsWith("/manifest.json") ? manifestPath : archivePath,
+    };
+}

package/dist/cloudflared/installer.js

@@ -1,48 +1,91 @@
-import { chmod, mkdir, readFile, rename, rm, stat, writeFile, access } from "node:fs/promises";
-import { constants, createWriteStream } from "node:fs";
-import { resolve, delimiter } from "node:path";
-import { pipeline } from "node:stream/promises";
 import { spawn } from "node:child_process";
-import { CLOUDFLARED_ASSETS } from "./manifest.js";
+import { constants } from "node:fs";
+import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { delimiter, resolve } from "node:path";
+import { resolveBundledCloudflared } from "./bundled-asset.js";
 import { sha256File } from "./checksum.js";
-export async function ensureCloudflared(target, dataDir) { const asset = CLOUDFLARED_ASSETS[target]; const binDir = resolve(dataDir, "bin"); const finalPath = resolve(binDir, asset.fileName); const marker = `${finalPath}.source.sha256`; await mkdir(binDir, { recursive: true }); if (await cached(finalPath, marker, asset.sha256))
-    return finalPath; const systemBinary = await findSystemCloudflared(); if (systemBinary)
-    return systemBinary; const temp = resolve(binDir, `.cloudflared-${Date.now()}.download`); await rm(temp, { force: true }); let response; try {
-    response = await fetch(asset.url, { redirect: "follow" });
+export async function ensureCloudflared(target, dataDir, options = {}) {
+    const binDir = resolve(dataDir, "bin");
+    const finalPath = resolve(binDir, process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+    const marker = `${finalPath}.source.sha256`;
+    await mkdir(binDir, { recursive: true });
+    const resolveBundled = options.resolveBundled ?? resolveBundledCloudflared;
+    const findSystem = options.findSystem ?? findSystemCloudflared;
+    const failures = [];
+    try {
+        const bundled = await resolveBundled(target);
+        if (bundled && (await cached(finalPath, marker, bundled.sha256)))
+            return finalPath;
+        if (bundled)
+            return await installBundledCloudflared(bundled, binDir, finalPath, marker);
+        failures.push(`platform package missing for ${target}`);
+    }
+    catch (error) {
+        failures.push(describeError(error));
+    }
+    const systemBinary = await findSystem();
+    if (systemBinary)
+        return systemBinary;
+    throw new Error(`cloudflared unavailable: ${failures.join("; ")}; no executable on PATH`);
+}
+export async function findSystemCloudflared(pathValue = process.env.PATH ?? "", platform = process.platform) {
+    const name = platform === "win32" ? "cloudflared.exe" : "cloudflared";
+    for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+        const candidate = resolve(directory, name);
+        try {
+            await access(candidate, platform === "win32" ? constants.F_OK : constants.X_OK);
+            return candidate;
+        }
+        catch { }
+    }
+    return null;
 }
-catch (error) {
-    throw new Error(`cloudflared download failed from github.com: ${describeError(error)}`);
-} if (!response.ok || !response.body)
-    throw new Error(`cloudflared download failed: HTTP ${response.status}`); await pipeline(response.body, createWriteStream(temp)); const info = await stat(temp); if (info.size !== asset.size || await sha256File(temp) !== asset.sha256) {
-    await rm(temp, { force: true });
-    throw new Error("cloudflared checksum mismatch");
-} if (asset.archive) {
-    await extractTgz(temp, binDir);
-    await rm(temp, { force: true });
+async function installBundledCloudflared(asset, binDir, finalPath, marker) {
+    const archiveInfo = await stat(asset.archivePath);
+    if (!archiveInfo.isFile() || archiveInfo.size !== asset.size)
+        throw new Error("bundled cloudflared size mismatch");
+    if ((await sha256File(asset.archivePath)) !== asset.sha256)
+        throw new Error("bundled cloudflared checksum mismatch");
+    const temporaryDir = resolve(binDir, `.cloudflared-${process.pid}-${Date.now()}`);
+    const markerTemp = `${marker}.${process.pid}.tmp`;
+    await mkdir(temporaryDir, { recursive: true });
+    try {
+        await extractTgz(asset.archivePath, temporaryDir);
+        const entries = await readdir(temporaryDir);
+        if (entries.length !== 1 || entries[0] !== asset.fileName) {
+            throw new Error(`unexpected bundled cloudflared contents: ${entries.join(", ")}`);
+        }
+        const extracted = resolve(temporaryDir, asset.fileName);
+        if (!(await stat(extracted)).isFile())
+            throw new Error("bundled cloudflared executable missing");
+        if (process.platform !== "win32")
+            await chmod(extracted, 0o755);
+        await rename(extracted, finalPath);
+        await writeFile(markerTemp, `${asset.sha256}\n`);
+        await rename(markerTemp, marker);
+        return finalPath;
+    }
+    finally {
+        await rm(temporaryDir, { recursive: true, force: true });
+        await rm(markerTemp, { force: true });
+    }
 }
-else
-    await rename(temp, finalPath); if (process.platform !== "win32")
-    await chmod(finalPath, 0o755); if (!await exists(finalPath))
-    throw new Error("cloudflared binary missing after install"); await writeFile(marker, asset.sha256); return finalPath; }
-export async function findSystemCloudflared(pathValue = process.env.PATH ?? "", platform = process.platform) { const name = platform === "win32" ? "cloudflared.exe" : "cloudflared"; for (const directory of pathValue.split(delimiter).filter(Boolean)) {
-    const candidate = resolve(directory, name);
+async function cached(path, marker, hash) {
     try {
-        await access(candidate, platform === "win32" ? constants.F_OK : constants.X_OK);
-        return candidate;
+        return (await stat(path)).isFile() && (await readFile(marker, "utf8")).trim() === hash;
     }
-    catch { }
-} return null; }
-async function cached(path, marker, hash) { try {
-    return await exists(path) && (await readFile(marker, "utf8")).trim() === hash;
+    catch {
+        return false;
+    }
+}
+function describeError(error) {
+    const value = error;
+    return [value.cause?.code, value.message, value.cause?.message].filter(Boolean).join(": ") || String(error);
 }
-catch {
-    return false;
-} }
-async function exists(path) { try {
-    return (await stat(path)).isFile();
+function extractTgz(archive, dir) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn("tar", ["-xzf", archive, "-C", dir], { stdio: "ignore" });
+        child.once("exit", (code) => (code === 0 ? resolvePromise() : reject(new Error(`tar exited ${code}`))));
+        child.once("error", reject);
+    });
 }
-catch {
-    return false;
-} }
-function describeError(error) { const value = error; const cause = value?.cause; return [cause?.code, value?.message, cause?.message].filter(Boolean).join(": ") || String(error); }
-function extractTgz(archive, dir) { return new Promise((resolve, reject) => { const child = spawn("tar", ["-xzf", archive, "-C", dir], { stdio: "ignore" }); child.once("exit", code => code === 0 ? resolve() : reject(new Error(`tar exited ${code}`))); child.once("error", reject); }); }

package/dist/cloudflared/installer.test.js

@@ -1,11 +1,55 @@
-import { chmod, mkdtemp, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, mkdtemp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
-import { describe, expect, it } from "vitest";
-import { findSystemCloudflared } from "./installer.js";
+import { describe, expect, it, vi } from "vitest";
+import { ensureCloudflared, findSystemCloudflared } from "./installer.js";
+describe("ensureCloudflared", () => {
+    it("extracts a verified bundled archive and repairs executable permissions", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-bundle-"));
+        const asset = await createArchive(root, "#!/bin/sh\necho bundled\n");
+        const executable = await ensureCloudflared("darwin-arm64", resolve(root, "data"), {
+            resolveBundled: async () => asset,
+            findSystem: async () => null,
+        });
+        expect(await readFile(executable, "utf8")).toContain("bundled");
+        await access(executable, constants.X_OK);
+        expect(await readFile(`${executable}.source.sha256`, "utf8")).toBe(`${asset.sha256}\n`);
+    });
+    it("reuses the verified cache", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-cache-"));
+        const asset = await createArchive(root, "#!/bin/sh\n");
+        const resolver = vi.fn(async () => asset);
+        const options = { resolveBundled: resolver, findSystem: async () => null };
+        const first = await ensureCloudflared("darwin-arm64", resolve(root, "data"), options);
+        const second = await ensureCloudflared("darwin-arm64", resolve(root, "data"), options);
+        expect(second).toBe(first);
+        expect(resolver).toHaveBeenCalledTimes(2);
+    });
+    it("falls back to PATH when the bundled checksum is invalid", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-fallback-"));
+        const asset = await createArchive(root, "#!/bin/sh\n");
+        const system = resolve(root, "system-cloudflared");
+        await writeFile(system, "#!/bin/sh\n", { mode: 0o755 });
+        const result = await ensureCloudflared("darwin-arm64", resolve(root, "data"), {
+            resolveBundled: async () => ({ ...asset, sha256: "0".repeat(64) }),
+            findSystem: async () => system,
+        });
+        expect(result).toBe(system);
+    });
+    it("reports package and PATH failures without downloading", async () => {
+        const root = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-missing-"));
+        await expect(ensureCloudflared("darwin-arm64", resolve(root, "data"), {
+            resolveBundled: async () => null,
+            findSystem: async () => null,
+        })).rejects.toThrow("platform package missing for darwin-arm64; no executable on PATH");
+    });
+});
 describe("findSystemCloudflared", () => {
     it("reuses an executable cloudflared already installed on PATH", async () => {
-        const directory = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-"));
+        const directory = await mkdtemp(resolve(tmpdir(), "agentroam-cloudflared-path-"));
         const executable = resolve(directory, "cloudflared");
         await writeFile(executable, "#!/bin/sh\n", { mode: 0o644 });
         expect(await findSystemCloudflared(directory, "darwin")).toBeNull();
@@ -13,3 +57,18 @@ describe("findSystemCloudflared", () => {
         expect(await findSystemCloudflared(directory, "darwin")).toBe(executable);
     });
 });
+async function createArchive(root, content) {
+    const source = resolve(root, "source");
+    await mkdir(source, { recursive: true });
+    await writeFile(resolve(source, "cloudflared"), content, { mode: 0o644 });
+    const archivePath = resolve(root, "cloudflared.tgz");
+    execFileSync("tar", ["-czf", archivePath, "-C", source, "cloudflared"]);
+    const bytes = await readFile(archivePath);
+    return {
+        archivePath,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        size: (await stat(archivePath)).size,
+        fileName: "cloudflared",
+        version: "test",
+    };
+}

package/dist/cloudflared/manifest.js

@@ -1,7 +1,5 @@
 export const CLOUDFLARED_VERSION = "2026.8.2";
-const base = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}`;
-export const CLOUDFLARED_ASSETS = {
-    "darwin-arm64": { url: `${base}/cloudflared-darwin-arm64.tgz`, sha256: "9042c2c5d8b2de78e60f313d5fb31b6c5c1cebde787a3caf1f2c9588084ac442", size: 19214189, archive: true, fileName: "cloudflared" },
-    "darwin-amd64": { url: `${base}/cloudflared-darwin-amd64.tgz`, sha256: "f1727723c586500e2092368ae21871b3df7ddfd2cb097f22d81bee4a9c458bb4", size: 21116242, archive: true, fileName: "cloudflared" },
-    "windows-amd64": { url: `${base}/cloudflared-windows-amd64.exe`, sha256: "c29eee2b121f5436a642eed69fd9767da7e7b8c510fa50aaa130337f931357b5", size: 54893480, archive: false, fileName: "cloudflared.exe" }
+export const CLOUDFLARED_PACKAGE_VERSION = "0.2.0-preview.4";
+export const CLOUDFLARED_PACKAGES = {
+    "darwin-arm64": "agentroam-cloudflared-darwin-arm64",
 };