pilotswarm 0.0.1 → 0.4.0

package/tui/src/auth/cli.js

@@ -0,0 +1,111 @@
+import { parseArgs } from "node:util";
+import {
+    createTokenProvider,
+    fetchAuthConfig,
+    getSignedInAccount,
+    signIn,
+    signOut,
+} from "./entra-auth.js";
+
+/**
+ * `pilotswarm auth login|status|logout --api-url <url>`
+ *
+ * Pre-provision or inspect the per-origin token cache used by the TUI's
+ * API mode. The TUI triggers the same sign-in lazily on start, so
+ * `auth login` is optional.
+ */
+
+function resolveApiUrl(flags) {
+    const apiUrl = String(flags["api-url"] || process.env.PILOTSWARM_API_URL || "").trim();
+    if (!apiUrl) {
+        throw new Error("An API URL is required: pass --api-url <url> or set PILOTSWARM_API_URL.");
+    }
+    return apiUrl.replace(/\/+$/, "");
+}
+
+/**
+ * Resolve the deployment's auth mode and, for Entra, run sign-in (silent
+ * first, then device code) and return a token supplier. Used by both the
+ * auth subcommands and TUI startup — runs before the Ink app renders.
+ */
+export async function bootstrapApiAuth(apiUrl, { output = console.error, interactive = true, useDeviceCode = false } = {}) {
+    const authConfig = await fetchAuthConfig(apiUrl);
+    if (!authConfig?.enabled || authConfig?.provider === "none") {
+        return { authConfig, getAccessToken: async () => null };
+    }
+    if (authConfig.provider !== "entra") {
+        throw new Error(`Unsupported auth provider '${authConfig.provider}' reported by ${apiUrl}.`);
+    }
+    if (interactive) {
+        await signIn(apiUrl, authConfig, { output, useDeviceCode });
+    }
+    const getAccessToken = await createTokenProvider(apiUrl, authConfig);
+    return { authConfig, getAccessToken };
+}
+
+export async function runAuthCommand(argv) {
+    const { values: flags, positionals } = parseArgs({
+        options: {
+            "api-url": { type: "string" },
+            "device-code": { type: "boolean" },
+            env: { type: "string", short: "e" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        strict: false,
+        args: argv,
+    });
+
+    const action = positionals[0];
+    if (flags.help || !["login", "status", "logout"].includes(action)) {
+        console.log(`
+pilotswarm auth — manage Web API sign-in
+
+USAGE
+  pilotswarm auth login  --api-url <url>   Sign in (opens your browser) and cache tokens
+  pilotswarm auth status --api-url <url>   Show the signed-in account
+  pilotswarm auth logout --api-url <url>   Drop cached tokens for that origin
+
+FLAGS
+      --device-code    Use the device-code flow instead of the browser
+                       (headless hosts; only where the tenant permits it —
+                       many corp tenants block device code via Conditional Access)
+
+  PILOTSWARM_API_URL can replace --api-url.
+`.trim());
+        return flags.help ? 0 : 1;
+    }
+
+    const apiUrl = resolveApiUrl(flags);
+
+    if (action === "logout") {
+        const cacheFile = await signOut(apiUrl);
+        console.log(`Signed out of ${apiUrl} (removed ${cacheFile}).`);
+        return 0;
+    }
+
+    const authConfig = await fetchAuthConfig(apiUrl);
+    if (!authConfig?.enabled || authConfig?.provider === "none") {
+        console.log(`${apiUrl} does not require sign-in (auth provider: ${authConfig?.provider || "none"}).`);
+        return 0;
+    }
+
+    if (action === "login") {
+        const result = await signIn(apiUrl, authConfig, { output: console.log, useDeviceCode: Boolean(flags["device-code"]) });
+        const username = result?.account?.username || result?.account?.name || "signed in";
+        console.log(`Signed in to ${apiUrl} as ${username}.`);
+        return 0;
+    }
+
+    // status
+    const account = await getSignedInAccount(apiUrl, authConfig);
+    if (!account) {
+        console.log(`Not signed in to ${apiUrl}. Run: pilotswarm auth login --api-url ${apiUrl}`);
+        return 1;
+    }
+    console.log(`Signed in to ${apiUrl} as ${account.username || account.name}.`);
+    const getAccessToken = await createTokenProvider(apiUrl, authConfig);
+    const token = await getAccessToken();
+    console.log(token ? "Token cache is valid (silent acquisition succeeded)." : "Token cache is stale — run: pilotswarm auth login");
+    return token ? 0 : 1;
+}

package/tui/src/auth/entra-auth.js

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ApiClient } from "pilotswarm-sdk/api";
+import { openUrlInDefaultBrowser } from "../http-transport-host.js";
+
+/**
+ * Entra ID sign-in for the TUI's API mode.
+ *
+ * Default flow: OAuth 2.0 authorization code + PKCE via msal-node's
+ * `acquireTokenInteractive`. It opens the system browser to a normal Entra
+ * sign-in and captures the code on a loopback (`http://localhost:<port>`)
+ * redirect — the same interactive flow `az login`, the GitHub CLI, and the
+ * browser portal use. Crucially, it satisfies Conditional Access policies
+ * that block the device-code flow (common in hardened corporate tenants;
+ * Microsoft's own tenant returns AADSTS53003 for device code).
+ *
+ * Fallback flow: device code (`useDeviceCode`) for headless hosts with no
+ * browser — only usable where the tenant permits it.
+ *
+ * The TUI never carries tenant/client ids in local config — they are
+ * discovered from the deployment's public `GET /api/v1/auth/config`, so
+ * app-registration rotation never breaks clients. Tokens are cached per API
+ * origin at `~/.config/pilotswarm/auth/<origin>.json` (0600). MSAL owns
+ * refresh; `getAccessToken` runs acquireTokenSilent per call.
+ */
+
+const AUTH_CACHE_DIR = path.join(
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+    "pilotswarm",
+    "auth",
+);
+
+const BROWSER_RESULT_HTML = (heading, body) => `<!doctype html><html><head><meta charset="utf-8">`
+    + `<title>PilotSwarm</title><style>body{font-family:-apple-system,Segoe UI,sans-serif;`
+    + `background:#0d1117;color:#e5edf5;display:flex;align-items:center;justify-content:center;`
+    + `height:100vh;margin:0}.card{text-align:center;max-width:28rem;padding:2rem}`
+    + `h1{font-size:1.25rem;margin:0 0 .5rem}p{color:#8b949e}</style></head>`
+    + `<body><div class="card"><h1>${heading}</h1><p>${body}</p></div></body></html>`;
+
+const SUCCESS_TEMPLATE = BROWSER_RESULT_HTML("Signed in to PilotSwarm", "You can close this tab and return to the terminal.");
+const ERROR_TEMPLATE = BROWSER_RESULT_HTML("Sign-in failed", "Return to the terminal for details.");
+
+function cacheFileForOrigin(apiUrl) {
+    const origin = new URL(apiUrl).origin.replace(/[^\w.-]+/g, "_");
+    return path.join(AUTH_CACHE_DIR, `${origin}.json`);
+}
+
+function createCachePlugin(cacheFile) {
+    return {
+        beforeCacheAccess: async (cacheContext) => {
+            try {
+                cacheContext.tokenCache.deserialize(await fs.promises.readFile(cacheFile, "utf8"));
+            } catch {}
+        },
+        afterCacheAccess: async (cacheContext) => {
+            if (!cacheContext.cacheHasChanged) return;
+            await fs.promises.mkdir(AUTH_CACHE_DIR, { recursive: true, mode: 0o700 });
+            await fs.promises.writeFile(cacheFile, cacheContext.tokenCache.serialize(), { mode: 0o600 });
+        },
+    };
+}
+
+export async function fetchAuthConfig(apiUrl) {
+    const api = new ApiClient({ apiUrl });
+    return api.getAuthConfig();
+}
+
+function requireEntraClientConfig(authConfig, apiUrl) {
+    const client = authConfig?.client;
+    if (!client?.clientId || !client?.authority) {
+        throw new Error(
+            `The deployment at ${apiUrl} reports Entra auth but no public client configuration. `
+            + "Check PORTAL_AUTH_ENTRA_TENANT_ID / PORTAL_AUTH_ENTRA_CLIENT_ID on the server.",
+        );
+    }
+    return client;
+}
+
+async function createPublicClientApp(authConfig, apiUrl) {
+    const client = requireEntraClientConfig(authConfig, apiUrl);
+    const { PublicClientApplication } = await import("@azure/msal-node");
+    const app = new PublicClientApplication({
+        auth: {
+            clientId: client.clientId,
+            authority: client.authority,
+        },
+        cache: {
+            cachePlugin: createCachePlugin(cacheFileForOrigin(apiUrl)),
+        },
+    });
+    return { app, scopes: [`${client.clientId}/.default`] };
+}
+
+async function firstCachedAccount(app) {
+    const accounts = await app.getTokenCache().getAllAccounts();
+    return accounts[0] || null;
+}
+
+// MSAL's loopback listener never times out on its own; bound the wait so a
+// browser that never opens (headless/SSH, or a failed launch) surfaces an
+// actionable error instead of hanging TUI startup forever. Generous enough
+// for interactive MFA.
+const INTERACTIVE_TIMEOUT_MS = 5 * 60 * 1000;
+
+async function acquireInteractive(app, scopes, apiUrl, output) {
+    output("");
+    output(`  Opening your browser to sign in to ${apiUrl} …`);
+    output("");
+    const request = {
+        scopes,
+        successTemplate: SUCCESS_TEMPLATE,
+        errorTemplate: ERROR_TEMPLATE,
+        openBrowser: async (url) => {
+            // Print the URL too so the user can copy it if the browser does
+            // not open on its own (SSH, restricted shells).
+            output(`  If your browser does not open, visit:\n    ${url}`);
+            output("");
+            try {
+                await openUrlInDefaultBrowser(url);
+            } catch {
+                output("  (Could not launch a browser automatically — paste the URL above, or");
+                output("   press Ctrl-C and re-run with --device-code on a headless host.)");
+                output("");
+            }
+        },
+    };
+
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(
+                "Browser sign-in timed out. If your browser did not open, paste the printed URL "
+                + "into a browser on this machine, or re-run with --device-code.",
+            ));
+        }, INTERACTIVE_TIMEOUT_MS);
+        timer.unref?.();
+    });
+
+    let result;
+    try {
+        result = await Promise.race([app.acquireTokenInteractive(request), timeout]);
+    } finally {
+        clearTimeout(timer);
+    }
+    if (!result?.accessToken) {
+        throw new Error("Entra sign-in did not produce an access token.");
+    }
+    return result;
+}
+
+async function acquireDeviceCode(app, scopes, apiUrl, output) {
+    const result = await app.acquireTokenByDeviceCode({
+        scopes,
+        deviceCodeCallback: (deviceCode) => {
+            output("");
+            output(`  Sign in to ${apiUrl}`);
+            output(`  Visit ${deviceCode.verificationUri} and enter code ${deviceCode.userCode}`);
+            output("");
+            openUrlInDefaultBrowser(deviceCode.verificationUri).catch(() => {});
+        },
+    });
+    if (!result?.accessToken) {
+        throw new Error("Entra sign-in did not produce an access token.");
+    }
+    return result;
+}
+
+/**
+ * Interactive sign-in: silent first, then the browser (auth-code+PKCE) flow —
+ * or the device-code flow when `useDeviceCode` is set.
+ */
+export async function signIn(apiUrl, authConfig, { output = console.error, useDeviceCode = false } = {}) {
+    const { app, scopes } = await createPublicClientApp(authConfig, apiUrl);
+
+    const account = await firstCachedAccount(app);
+    if (account) {
+        try {
+            const silent = await app.acquireTokenSilent({ account, scopes });
+            if (silent?.accessToken) return silent;
+        } catch {}
+    }
+
+    return useDeviceCode
+        ? acquireDeviceCode(app, scopes, apiUrl, output)
+        : acquireInteractive(app, scopes, apiUrl, output);
+}
+
+/**
+ * Build the `getAccessToken` callback for an Entra deployment. Runs the
+ * silent flow per call (MSAL caches in memory); if silent acquisition fails
+ * the caller sees null and the server's 401 tells the user to run
+ * `pilotswarm auth login`.
+ */
+export async function createTokenProvider(apiUrl, authConfig) {
+    const { app, scopes } = await createPublicClientApp(authConfig, apiUrl);
+    return async () => {
+        const account = await firstCachedAccount(app);
+        if (!account) return null;
+        try {
+            const result = await app.acquireTokenSilent({ account, scopes });
+            return result?.accessToken || null;
+        } catch {
+            return null;
+        }
+    };
+}
+
+export async function getSignedInAccount(apiUrl, authConfig) {
+    const { app } = await createPublicClientApp(authConfig, apiUrl);
+    return firstCachedAccount(app);
+}
+
+export async function signOut(apiUrl) {
+    const cacheFile = cacheFileForOrigin(apiUrl);
+    await fs.promises.rm(cacheFile, { force: true });
+    return cacheFile;
+}

package/tui/src/bootstrap-env.js

@@ -0,0 +1,176 @@
+import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveTuiBranding } from "./plugin-config.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, "..");
+
+function resolvePluginDir(flags) {
+    if (flags.plugin) return path.resolve(flags.plugin);
+    if (process.env.PLUGIN_DIRS) {
+        const dirs = process.env.PLUGIN_DIRS.split(",").map((value) => value.trim()).filter(Boolean);
+        return dirs[0] || null;
+    }
+    const cwdPlugin = path.resolve("plugins");
+    if (fs.existsSync(cwdPlugin)) return cwdPlugin;
+    const bundledPlugin = path.join(pkgRoot, "plugins");
+    if (fs.existsSync(bundledPlugin)) return bundledPlugin;
+    return null;
+}
+
+function resolveSystemMessage(flags) {
+    if (flags.system) {
+        if (fs.existsSync(flags.system)) {
+            return fs.readFileSync(flags.system, "utf-8").trim();
+        }
+        return flags.system;
+    }
+
+    const pluginDir = resolvePluginDir(flags);
+    if (pluginDir) {
+        const systemMd = path.join(pluginDir, "system.md");
+        if (fs.existsSync(systemMd)) {
+            return fs.readFileSync(systemMd, "utf-8").trim();
+        }
+    }
+
+    if (process.env.SYSTEM_MESSAGE) return process.env.SYSTEM_MESSAGE;
+    return undefined;
+}
+
+function loadEnvFile(envFile) {
+    if (!fs.existsSync(envFile)) return;
+    const envContent = fs.readFileSync(envFile, "utf-8");
+    for (const line of envContent.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const value = trimmed.slice(eqIdx + 1).trim();
+        if (!process.env[key]) {
+            process.env[key] = value;
+        }
+    }
+}
+
+function ensureGithubToken() {
+    if (process.env.GITHUB_TOKEN) return;
+    try {
+        const token = execFileSync("gh", ["auth", "token"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (token) {
+            process.env.GITHUB_TOKEN = token;
+        }
+    } catch {}
+}
+
+export function parseCliIntoEnv(argv) {
+    const { values: flags, positionals } = parseArgs({
+        options: {
+            store: { type: "string", short: "s" },
+            "api-url": { type: "string" },
+            "device-code": { type: "boolean" },
+            env: { type: "string", short: "e" },
+            plugin: { type: "string", short: "p" },
+            worker: { type: "string", short: "w" },
+            workers: { type: "string", short: "n" },
+            model: { type: "string", short: "m" },
+            system: { type: "string" },
+            context: { type: "string", short: "c" },
+            namespace: { type: "string" },
+            label: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        strict: false,
+        args: argv,
+    });
+
+    if (flags.help) {
+        console.log(`
+pilotswarm — PilotSwarm terminal UI
+
+USAGE
+  npx pilotswarm [local|remote] [flags]
+  npx pilotswarm auth login|status|logout --api-url <url>
+
+MODES
+  local                  Run everything locally (embedded workers)
+  remote                 Connect to a deployment's Web API (--api-url; the
+                         supported remote mode) or directly to its database
+                         (--store; internal/operator use)
+
+FLAGS
+      --api-url <url>    Web API base URL for remote mode (or PILOTSWARM_API_URL)
+      --device-code      Entra sign-in via device code instead of the browser
+                         (headless; only where the tenant allows it)
+  -e, --env <file>       Env file
+  -p, --plugin <dir>     Plugin directory
+  -w, --worker <module>  Worker tools module (local mode)
+  -n, --workers <count>  Embedded worker count (local mode)
+  -m, --model <name>     Initial model
+  -c, --context <ctx>    K8s context (direct remote mode only)
+      --namespace <ns>   K8s namespace (direct remote mode only)
+      --label <selector> K8s pod label (direct remote mode only)
+  -h, --help             Show help
+`.trim());
+        process.exit(0);
+    }
+
+    const mode = positionals[0] === "remote" ? "remote" : "local";
+    const envFile = flags.env || (mode === "remote" ? ".env.remote" : ".env");
+    loadEnvFile(envFile);
+    ensureGithubToken();
+
+    const apiUrl = String(flags["api-url"] || process.env.PILOTSWARM_API_URL || "").trim().replace(/\/+$/, "");
+    if (apiUrl && mode !== "remote") {
+        throw new Error("--api-url is only valid in remote mode: npx pilotswarm remote --api-url <url>");
+    }
+    if (apiUrl && flags.store) {
+        throw new Error("Pass either --api-url (Web API remote mode) or --store (direct remote mode), not both.");
+    }
+    if (apiUrl && (flags.context || flags.namespace || flags.label)) {
+        console.warn("[pilotswarm] K8s log-tail flags are ignored in API mode — the server tails logs in-cluster.");
+    }
+
+    process.env.DATABASE_URL = flags.store || process.env.DATABASE_URL || "sqlite::memory:";
+    process.env.WORKERS = mode === "remote" ? "0" : (flags.workers ?? process.env.WORKERS ?? "4");
+    process.env.COPILOT_MODEL = flags.model || process.env.COPILOT_MODEL || "";
+    process.env.K8S_CONTEXT = flags.context || process.env.K8S_CONTEXT || "";
+    process.env.K8S_NAMESPACE = flags.namespace || process.env.K8S_NAMESPACE || "copilot-runtime";
+    process.env.K8S_POD_LABEL = flags.label || process.env.K8S_POD_LABEL || "app.kubernetes.io/component=worker";
+
+    const pluginDir = resolvePluginDir(flags);
+    if (pluginDir) {
+        process.env.PLUGIN_DIRS = pluginDir;
+    }
+
+    const branding = resolveTuiBranding(pluginDir);
+    process.env._TUI_TITLE = branding.title;
+    process.env._TUI_SPLASH = branding.splash;
+
+    const systemMessage = resolveSystemMessage(flags);
+    if (systemMessage) process.env._TUI_SYSTEM_MESSAGE = systemMessage;
+
+    if (mode === "local" && flags.worker) {
+        const resolvedWorker = path.resolve(flags.worker);
+        if (!fs.existsSync(resolvedWorker)) {
+            throw new Error(`Worker module not found: ${resolvedWorker}`);
+        }
+        process.env._TUI_WORKER_MODULE = resolvedWorker;
+    }
+
+    return {
+        mode,
+        store: process.env.DATABASE_URL,
+        apiUrl: apiUrl || null,
+        deviceCode: Boolean(flags["device-code"]),
+        branding,
+    };
+}

package/tui/src/embedded-workers.js

@@ -0,0 +1,79 @@
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
+import { PilotSwarmWorker, horizonConfigFromEnv } from "pilotswarm-sdk";
+import { getPluginDirsFromEnv } from "./plugin-config.js";
+
+export async function startEmbeddedWorkers({ count, store }) {
+    const workers = [];
+    if (!count || count <= 0) return workers;
+
+    const pluginDirs = getPluginDirsFromEnv();
+
+    let workerModuleConfig = {};
+    if (process.env._TUI_WORKER_MODULE) {
+        const imported = await import(process.env._TUI_WORKER_MODULE);
+        workerModuleConfig = imported.default || imported;
+    }
+
+    const sessionStateDir = process.env.SESSION_STATE_DIR || path.join(os.homedir(), ".copilot", "session-state");
+    const originalConsole = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+    };
+
+    for (let index = 0; index < count; index++) {
+        console.log = () => {};
+        console.warn = () => {};
+        console.error = () => {};
+        try {
+            const worker = new PilotSwarmWorker({
+                store,
+                githubToken: process.env.GITHUB_TOKEN,
+                logLevel: process.env.LOG_LEVEL || "error",
+                sessionStateDir,
+                workerNodeId: `local-${index}`,
+                systemMessage: workerModuleConfig.systemMessage || process.env._TUI_SYSTEM_MESSAGE || undefined,
+                pluginDirs,
+                // Bicep-deploy MI flow (set in worker-env ConfigMap by the
+                // overlay .env). Unset for legacy `scripts/deploy-aks.sh`,
+                // local Docker, and CI — those keep using the password
+                // URL via `store` (and AZURE_STORAGE_CONNECTION_STRING for
+                // blobs). See packages/sdk/src/pg-pool-factory.ts.
+                useManagedIdentity: ["1", "true", "yes", "on"].includes(
+                    (process.env.PILOTSWARM_USE_MANAGED_IDENTITY || "").trim().toLowerCase(),
+                ),
+                cmsFactsDatabaseUrl: process.env.PILOTSWARM_CMS_FACTS_DATABASE_URL || undefined,
+                aadDbUser: process.env.PILOTSWARM_DB_AAD_USER || undefined,
+                blobAccountUrl: process.env.AZURE_STORAGE_ACCOUNT_URL || undefined,
+                blobConnectionString: process.env.AZURE_STORAGE_CONNECTION_STRING || undefined,
+                blobContainer: process.env.AZURE_STORAGE_CONTAINER || undefined,
+                // Optional EnhancedFactStore + knowledge graph (HorizonDB). Empty
+                // unless HORIZON_DATABASE_URL is set, so default deployments are
+                // unaffected (plain PgFactStore).
+                ...horizonConfigFromEnv(),
+            });
+
+            const workerTools = typeof workerModuleConfig.createTools === "function"
+                ? await workerModuleConfig.createTools({ workerNodeId: `local-${index}`, workerIndex: index })
+                : workerModuleConfig.tools;
+            if (workerTools?.length) {
+                worker.registerTools(workerTools);
+            }
+
+            await worker.start();
+            workers.push(worker);
+        } finally {
+            console.log = originalConsole.log;
+            console.warn = originalConsole.warn;
+            console.error = originalConsole.error;
+        }
+    }
+
+    return workers;
+}
+
+export async function stopEmbeddedWorkers(workers) {
+    await Promise.allSettled((workers || []).map((worker) => worker.stop()));
+}

package/tui/src/http-transport-host.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { HttpApiTransport } from "pilotswarm-sdk/api";
+
+/**
+ * TUI host for the Web API transport: HttpApiTransport plus the local-machine
+ * conveniences the shared UI expects from a Node environment (artifact export
+ * to disk, open-in-default-app/browser). All data flows through the API —
+ * this file only touches the local filesystem and OS openers.
+ */
+
+function expandUserPath(filePath) {
+    const raw = String(filePath || "");
+    if (raw === "~") return os.homedir();
+    if (raw.startsWith("~/")) return path.join(os.homedir(), raw.slice(2));
+    return raw;
+}
+
+const EXPORTS_DIR = path.resolve(
+    expandUserPath(process.env.PILOTSWARM_EXPORT_DIR || path.join(os.homedir(), "pilotswarm-exports")),
+);
+
+function spawnDetached(command, args) {
+    return new Promise((resolve, reject) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore" });
+            child.once("error", reject);
+            child.unref();
+            resolve();
+        } catch (error) {
+            reject(error);
+        }
+    });
+}
+
+async function openWithPlatformOpener(target) {
+    if (process.platform === "darwin") {
+        await spawnDetached("open", [target]);
+    } else if (process.platform === "win32") {
+        await spawnDetached("cmd", ["/c", "start", "", target]);
+    } else {
+        await spawnDetached("xdg-open", [target]);
+    }
+}
+
+async function saveArtifactDownload(transport, sessionId, filename) {
+    const response = await transport.api.downloadArtifactResponse(sessionId, filename);
+    const body = Buffer.from(await response.arrayBuffer());
+    const sessionDir = path.join(EXPORTS_DIR, String(sessionId || "").slice(0, 8));
+    await fs.promises.mkdir(sessionDir, { recursive: true });
+    const localPath = path.join(sessionDir, path.basename(filename));
+    await fs.promises.writeFile(localPath, body);
+    return { localPath, filename };
+}
+
+async function uploadArtifactFromPath(transport, sessionId, filePath) {
+    const resolvedPath = path.resolve(expandUserPath(filePath));
+    const content = await fs.promises.readFile(resolvedPath);
+    return transport.uploadArtifactContent(
+        sessionId,
+        path.basename(resolvedPath),
+        content.toString("base64"),
+        undefined,
+        "base64",
+    );
+}
+
+async function openPathInDefaultApp(targetPath) {
+    const resolvedPath = path.resolve(expandUserPath(targetPath));
+    const stat = await fs.promises.stat(resolvedPath).catch(() => null);
+    if (!stat || !stat.isFile()) {
+        throw new Error(`File not found: ${targetPath}`);
+    }
+    await openWithPlatformOpener(resolvedPath);
+    return { localPath: resolvedPath };
+}
+
+export async function openUrlInDefaultBrowser(targetUrl) {
+    const href = String(targetUrl || "").trim();
+    if (!href) throw new Error("URL cannot be empty.");
+    const parsedUrl = new URL(href);
+    if (!/^https?:$/i.test(parsedUrl.protocol)) {
+        throw new Error(`Unsupported URL protocol: ${parsedUrl.protocol}`);
+    }
+    await openWithPlatformOpener(parsedUrl.toString());
+    return { url: parsedUrl.toString() };
+}
+
+export function createHttpTransportHost({ apiUrl, getAccessToken, onUnauthorized, onForbidden }) {
+    fs.mkdirSync(EXPORTS_DIR, { recursive: true });
+    return new HttpApiTransport({
+        apiUrl,
+        getAccessToken,
+        onUnauthorized,
+        onForbidden,
+        host: {
+            saveArtifactDownload,
+            uploadArtifactFromPath,
+            openPathInDefaultApp,
+            openUrlInDefaultBrowser,
+            artifactExportDirectory: EXPORTS_DIR,
+        },
+    });
+}