@miraland-labs/conduit-bridge 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @miraland-labs/conduit-bridge
+
+Local Bridge CLI for [Conduit](https://github.com/miralandlabs/conduit). Connects a computer to one organization, claims work, and drives a local agent.
+
+## Prerequisites
+
+- Node.js 20+
+- **Claude Code** (`claude` on PATH) for automated execution today
+- macOS or Linux for `install-service` (Windows: keep a terminal runner open)
+
+## Install / run
+
+No global install required:
+
+```bash
+npx @miraland-labs/conduit-bridge join --url <https://your-conduit> --organization <slug>
+```
+
+After approval, keep the computer executing work (not heartbeat-only):
+
+```bash
+npx @miraland-labs/conduit-bridge runner --agent claude-code --workspace /path/to/repo
+npx @miraland-labs/conduit-bridge install-service --agent claude-code --workspace /path/to/repo
+```
+
+Optional global install creates a `conduit` shim on PATH:
+
+```bash
+npm install -g @miraland-labs/conduit-bridge
+conduit join --url <https://your-conduit> --organization <slug>
+```
+
+Detected IDEs (Cursor, VS Code, Codex) are diagnostics only. Execution drivers today: `claude-code` only.

package/dist/brief.js

@@ -0,0 +1,85 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const MANIFESTS = ["package.json", "wrangler.jsonc", "wrangler.toml", "tsconfig.json", "Cargo.toml", "pyproject.toml", "go.mod", "Makefile"];
+const VERIFICATION_SCRIPTS = ["verify", "typecheck", "lint", "test", "build"];
+const EXCLUDED_DIRECTORIES = new Set(["node_modules", "dist", "build", "target", "coverage"]);
+export async function buildWorkspaceBrief(workspace) {
+    const entries = await readdir(workspace, { withFileTypes: true });
+    const modules = entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !EXCLUDED_DIRECTORIES.has(entry.name))
+        .map((entry) => entry.name).sort().slice(0, 30);
+    const files = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+    const manifests = MANIFESTS.filter((name) => files.has(name));
+    return {
+        repository: await gitRemoteUrl(workspace),
+        base_commit: await gitHeadCommit(workspace),
+        modules,
+        manifests,
+        verification: await verificationCommands(workspace, files),
+    };
+}
+export function normalizeRepositoryUrl(url) {
+    let value = url.trim().replace(/\.git$/, "").replace(/\/+$/, "").toLowerCase();
+    const ssh = value.match(/^git@([^:]+):(.+)$/);
+    if (ssh)
+        value = `https://${ssh[1]}/${ssh[2]}`;
+    return value.replace(/^https?:\/\//, "").replace(/^ssh:\/\/(git@)?/, "");
+}
+async function gitRemoteUrl(workspace) {
+    try {
+        const { common } = await gitDirectories(workspace);
+        const config = await readFile(join(common, "config"), "utf8");
+        const remote = config.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+        return remote?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function gitHeadCommit(workspace) {
+    try {
+        const { worktree, common } = await gitDirectories(workspace);
+        const head = (await readFile(join(worktree, "HEAD"), "utf8")).trim();
+        if (/^[0-9a-f]{40,64}$/i.test(head))
+            return head;
+        const ref = head.match(/^ref:\s*(\S+)$/)?.[1];
+        if (!ref)
+            return null;
+        try {
+            return (await readFile(join(common, ref), "utf8")).trim();
+        }
+        catch {
+            const packed = await readFile(join(common, "packed-refs"), "utf8");
+            const line = packed.split("\n").find((entry) => entry.endsWith(` ${ref}`));
+            return line?.split(" ")[0] ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function gitDirectories(workspace) {
+    const dotGit = join(workspace, ".git");
+    const info = await stat(dotGit);
+    const pointer = info.isDirectory() ? null : (await readFile(dotGit, "utf8")).trim().match(/^gitdir:\s*(.+)$/)?.[1];
+    if (!info.isDirectory() && !pointer)
+        throw new Error("Invalid Git worktree metadata");
+    const worktree = info.isDirectory() ? dotGit : resolve(workspace, pointer);
+    try {
+        return { worktree, common: resolve(worktree, (await readFile(join(worktree, "commondir"), "utf8")).trim()) };
+    }
+    catch {
+        return { worktree, common: worktree };
+    }
+}
+async function verificationCommands(workspace, files) {
+    if (!files.has("package.json"))
+        return [];
+    try {
+        const manifest = JSON.parse(await readFile(join(workspace, "package.json"), "utf8"));
+        return VERIFICATION_SCRIPTS.filter((name) => manifest.scripts?.[name]).map((name) => `npm run ${name}`);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/cli.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { hostname, userInfo } from "node:os";
+import { spawn } from "node:child_process";
+import { ConduitClient } from "./client.js";
+import { clearPendingConnection, loadConfig, loadConfigIfPresent, loadOrCreateInstallationId, loadPendingConnection, redactSecrets, saveConfig, savePendingConnection, suggestMachineName, } from "./config.js";
+import { runMcp } from "./mcp.js";
+import { detectInstalledClients } from "./detect.js";
+import { DRIVERS } from "./driver.js";
+import { buildWorkspaceBrief } from "./brief.js";
+import { executeNextAssignment, renewLeases } from "./execution.js";
+import { installRunnerService, uninstallRunnerService } from "./service.js";
+const [command] = process.argv.slice(2);
+/** Install-free form shown in help/output so clean laptops never need `conduit` on PATH. */
+const BRIDGE_NPX = "npx @miraland-labs/conduit-bridge";
+function bridgeUsage(...args) {
+    return `${BRIDGE_NPX} ${args.join(" ")}`;
+}
+function parseFuelSource(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "conduit" || value === "local")
+        return value;
+    throw new Error("Fuel source must be conduit or local");
+}
+async function connect() {
+    const { values } = parseArgs({ args: process.argv.slice(3), options: { url: { type: "string" }, code: { type: "string" }, fuel: { type: "string" } } });
+    if (!values.url || !values.code)
+        throw new Error(`Usage: ${bridgeUsage("connect", "--url", "<worker-url>", "--code", "<one-time-code>", "[--fuel conduit|local]")}`);
+    const parsedUrl = new URL(values.url);
+    if (!["http:", "https:"].includes(parsedUrl.protocol))
+        throw new Error("Conduit URL must use http or https");
+    const baseUrl = parsedUrl.toString().replace(/\/+$/, "");
+    const response = await fetch(`${baseUrl}/runner/v1/bootstrap/exchange`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ code: values.code }) });
+    const data = await response.json();
+    if (!response.ok)
+        throw new Error(data.error?.message ?? `Connect failed (${response.status})`);
+    await finishConnection(baseUrl, data, parseFuelSource(values.fuel));
+}
+async function join() {
+    const { values } = parseArgs({ args: process.argv.slice(3), options: {
+            url: { type: "string" }, resume: { type: "boolean" }, machine: { type: "string" }, operator: { type: "string" },
+            organization: { type: "string" },
+            capability: { type: "string", multiple: true }, capacity: { type: "string" }, "no-open": { type: "boolean" },
+            fuel: { type: "string" },
+        } });
+    const fuelSource = parseFuelSource(values.fuel);
+    let pending = await loadPendingConnection();
+    if (pending && Date.now() >= new Date(pending.expiresAt).getTime()) {
+        await clearPendingConnection();
+        pending = null;
+    }
+    if (values.resume && !pending)
+        throw new Error("No pending connection request to resume");
+    if (pending && values.url && normalizeBaseUrl(values.url) !== pending.baseUrl) {
+        throw new Error(`A connection request for ${pending.baseUrl} is still pending. Run \`${bridgeUsage("join", "--resume")}\`.`);
+    }
+    if (pending && !values.resume)
+        console.log(`Resuming the pending connection request for ${pending.baseUrl}.`);
+    if (!pending) {
+        if (!values.url || !values.organization) {
+            throw new Error(`Usage: ${bridgeUsage("join", "--url", "<worker-url>", "--organization", "<slug>", "[--machine <name>]", "[--capability <role>]", "[--fuel conduit|local]")}`);
+        }
+        const baseUrl = normalizeBaseUrl(values.url);
+        const organization = values.organization.trim().toLowerCase();
+        if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(organization))
+            throw new Error("Organization must be its lowercase workspace slug");
+        // A config that fails validation (for example pre-organization) must not
+        // block rejoining — join replaces it with a complete identity.
+        const connected = await loadConfigIfPresent().catch(() => null);
+        if (connected)
+            throw new Error(`This Bridge is already connected to ${connected.baseUrl} as ${connected.machineId}.`);
+        const installationId = await loadOrCreateInstallationId();
+        const detected = await detectInstalledClients();
+        const operatorName = values.operator?.trim() || userInfo().username;
+        const machineName = values.machine?.trim() || suggestMachineName(hostname(), installationId);
+        const capabilities = values.capability?.map((item) => item.trim()).filter(Boolean) ?? ["implement"];
+        const leaseCapacity = values.capacity ? Number(values.capacity) : 1;
+        console.log("\nRequesting a Conduit connection:");
+        console.log(`Operator: ${operatorName}`);
+        console.log(`Computer: ${machineName}`);
+        console.log(`Detected local clients: ${detected.join(", ") || "none"}`);
+        console.log(`Proposed roles: ${capabilities.join(", ")}`);
+        console.log(`Assignments at once: ${leaseCapacity}`);
+        if (fuelSource)
+            console.log(`Fuel source: ${fuelSource === "local" ? "local subscription" : "Conduit pump"}`);
+        console.log("Execution today requires Claude Code (`claude` on PATH). Other detected clients are diagnostics only.");
+        console.log("Use --machine <name> to override the computer label.\n");
+        const response = await fetch(`${baseUrl}/runner/v1/connect/requests`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                organization,
+                installation_id: installationId,
+                agent_name: operatorName,
+                machine_name: machineName,
+                detected_clients: detected,
+                capabilities,
+                lease_capacity: leaseCapacity,
+            }),
+        });
+        const data = await response.json();
+        if (!response.ok)
+            throw new Error(data.error?.message ?? `Connection request failed (${response.status})`);
+        pending = {
+            baseUrl,
+            organization,
+            requestId: String(data.request_id),
+            secret: String(data.secret),
+            userCode: String(data.user_code),
+            verificationUrl: String(data.verification_url),
+            expiresAt: String(data.expires_at),
+        };
+        await savePendingConnection(pending);
+    }
+    console.log(`\nOpen ${pending.verificationUrl}`);
+    console.log(`Enter device code: ${pending.userCode}`);
+    console.log("Waiting for a project owner to approve. You may close this terminal and run `conduit join --resume` later.\n");
+    if (!values["no-open"])
+        openUrl(pending.verificationUrl);
+    await waitForConnection(pending, fuelSource);
+}
+function normalizeBaseUrl(value) {
+    const parsedUrl = new URL(value);
+    if (!["http:", "https:"].includes(parsedUrl.protocol))
+        throw new Error("Conduit URL must use http or https");
+    return parsedUrl.toString().replace(/\/+$/, "");
+}
+async function waitForConnection(pending, fuelSource) {
+    let lastStatus = "";
+    while (Date.now() < new Date(pending.expiresAt).getTime()) {
+        const response = await fetch(`${pending.baseUrl}/runner/v1/connect/requests/${pending.requestId}/exchange`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ secret: pending.secret }),
+        });
+        const data = await response.json();
+        if (response.status === 202) {
+            const status = String(data.status ?? "pending");
+            if (status !== lastStatus)
+                console.log(status === "pending_claim" ? "Waiting for you to confirm the device code…" : "Waiting for project approval…");
+            lastStatus = status;
+            await new Promise((resolveSleep) => setTimeout(resolveSleep, 3_000));
+            continue;
+        }
+        if (!response.ok) {
+            if ([403, 409, 410].includes(response.status))
+                await clearPendingConnection();
+            throw new Error(data.error?.message ?? `Connection failed (${response.status})`);
+        }
+        await finishConnection(pending.baseUrl, data, fuelSource);
+        await clearPendingConnection();
+        return;
+    }
+    await clearPendingConnection();
+    throw new Error("Connection request expired. Run `conduit join --url <worker-url>` again.");
+}
+async function finishConnection(baseUrl, data, fuelSource) {
+    const fuelList = Array.isArray(data.fuel) ? data.fuel : [];
+    const fuel = {};
+    for (const row of fuelList) {
+        if (row.project_id && row.gateway_secret)
+            fuel[row.project_id] = { gatewayKey: row.gateway_secret };
+    }
+    const config = {
+        baseUrl,
+        organizationId: String(data.organization_id),
+        machineId: String(data.machine_id),
+        runnerKey: String(data.runner_secret),
+        capabilities: data.capabilities,
+        grants: data.grants,
+        leaseCapacity: Number(data.lease_capacity),
+        activeAttempts: {},
+        fuelSource: fuelSource ?? "conduit",
+        ...(Object.keys(fuel).length ? { fuel } : {}),
+    };
+    await saveConfig(config);
+    const client = new ConduitClient(config);
+    let heartbeatOk = true;
+    try {
+        await heartbeat(client, config, null);
+    }
+    catch {
+        heartbeatOk = false;
+    }
+    const detected = await detectInstalledClients();
+    console.log(`Connected machine: ${config.machineId}`);
+    console.log(heartbeatOk ? "Runner credential and heartbeat: OK" : "Runner credential saved; heartbeat will retry when the runner starts");
+    console.log(`Detected local clients: ${detected.join(", ") || "none"}`);
+    console.log(`Confirmed capabilities (matching): ${config.capabilities.join(", ") || "none"}`);
+    console.log(`Allowed actions: ${config.grants.join(", ") || "none"}`);
+    console.log(`Fuel source: ${config.fuelSource === "local" ? "local subscription" : "Conduit pump"}`);
+    console.log("Heartbeats report capabilities for diagnostics only; matching uses the Connect confirmation. Detected clients never receive grants automatically.");
+    console.log(`MCP setup: {"mcpServers":{"conduit":{"command":"npx","args":["-y","@miraland-labs/conduit-bridge","mcp"]}}}`);
+    console.log(`Execute work: ${bridgeUsage("runner", "--agent", "claude-code", "--workspace", "<repo>")}`);
+    console.log(`Keep on shift (macOS/Linux): ${bridgeUsage("install-service", "--agent", "claude-code", "--workspace", "<repo>")}`);
+    console.log(`Flip fuel later: ${bridgeUsage("fuel", "local|conduit")}`);
+    console.log("Windows: keep the runner terminal open — install-service is macOS/Linux only.");
+    if (Object.keys(fuel).length) {
+        console.log(`Fleet fueling: ${Object.keys(fuel).length} project key(s) configured for Conduit /v1`);
+    }
+    else {
+        console.log(`Gateway base URL (fuel keys provisioned on first assignment): ${baseUrl}/v1`);
+    }
+}
+function openUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
+    if (!command)
+        return;
+    try {
+        const child = spawn(command, [url], { detached: true, stdio: "ignore" });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        // The printed URL remains the reliable fallback on headless machines.
+    }
+}
+async function installService() {
+    await loadConfig();
+    const { values } = parseArgs({ args: process.argv.slice(3), options: {
+            agent: { type: "string" }, workspace: { type: "string" }, interval: { type: "string" }, "agent-timeout-minutes": { type: "string" },
+        } });
+    if (!values.agent || !values.workspace) {
+        throw new Error(`Usage: ${bridgeUsage("install-service", "--agent", "claude-code", "--workspace", "<repository-path>")} (agent + workspace required; heartbeat-only services are not supported)`);
+    }
+    if (!DRIVERS[values.agent]) {
+        throw new Error(`Unknown agent driver: ${values.agent}. Available: ${Object.keys(DRIVERS).join(", ")}`);
+    }
+    const result = await installRunnerService({
+        agent: values.agent,
+        workspace: resolve(values.workspace),
+        interval: values.interval,
+        agentTimeoutMinutes: values["agent-timeout-minutes"],
+    });
+    console.log(`Installed Conduit runner service (${result.platform}): ${result.path}`);
+    console.log("The runner keeps executing after this terminal closes. Laptop sleep still pauses work.");
+}
+async function uninstallService() {
+    const result = await uninstallRunnerService();
+    console.log(`Removed Conduit runner service (${result.platform}): ${result.path}`);
+}
+async function fuelCommand() {
+    const mode = process.argv[3];
+    if (mode !== "local" && mode !== "conduit") {
+        throw new Error(`Usage: ${bridgeUsage("fuel", "local|conduit")}`);
+    }
+    const config = await loadConfig();
+    config.fuelSource = mode;
+    await saveConfig(config);
+    const client = new ConduitClient(config);
+    await heartbeat(client, config, null);
+    console.log(`Fuel source set to ${mode === "local" ? "local subscription" : "Conduit pump"} and reported on heartbeat.`);
+}
+async function runner() {
+    const { values } = parseArgs({ args: process.argv.slice(3), options: {
+            agent: { type: "string" }, workspace: { type: "string" }, interval: { type: "string" }, once: { type: "boolean" },
+            "agent-timeout-minutes": { type: "string" }, fuel: { type: "string" },
+        } });
+    const config = await loadConfig();
+    const fuelOverride = parseFuelSource(values.fuel);
+    if (fuelOverride) {
+        config.fuelSource = fuelOverride;
+        await saveConfig(config);
+    }
+    const client = new ConduitClient(config);
+    let driver = null;
+    if (values.agent) {
+        driver = DRIVERS[values.agent] ?? null;
+        if (!driver)
+            throw new Error(`Unknown agent driver: ${values.agent}. Available: ${Object.keys(DRIVERS).join(", ")}`);
+        if (!values.workspace)
+            throw new Error("--workspace <repository-path> is required with --agent");
+    }
+    const workspace = values.workspace ? resolve(values.workspace) : null;
+    const brief = workspace ? await buildWorkspaceBrief(workspace) : null;
+    const intervalMs = values.interval ? Math.max(5_000, Number(values.interval)) : 15_000;
+    const timeoutMs = values["agent-timeout-minutes"] ? Number(values["agent-timeout-minutes"]) * 60_000 : undefined;
+    const fuelLabel = config.fuelSource === "local" ? "local subscription" : "Conduit pump";
+    if (!driver || !workspace) {
+        console.warn(`WARNING: heartbeat only — no work will execute. Use: ${bridgeUsage("runner", "--agent", "claude-code", "--workspace", "<repo>")}`);
+    }
+    console.log(`Conduit runner connected to ${config.baseUrl}${driver ? ` — executing via ${driver.name} in ${workspace}` : " — heartbeat only (no --agent)"} (fuel: ${fuelLabel})`);
+    for (;;) {
+        let executed = false;
+        try {
+            await heartbeat(client, config, workspace ? await buildWorkspaceBrief(workspace).catch(() => brief) : null);
+            await renewLeases(client, config);
+            if (driver && workspace) {
+                executed = await executeNextAssignment(client, config, driver, workspace, brief, timeoutMs);
+            }
+        }
+        catch (error) {
+            console.error(`Runner cycle failed; retrying: ${redactSecrets(error instanceof Error ? error.message : "unknown error")}`);
+        }
+        if (values.once && executed)
+            return;
+        await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
+    }
+}
+async function heartbeat(client, config, brief) {
+    await client.request("/runner/v1/heartbeat", { method: "POST", body: JSON.stringify({
+            status: "online",
+            capabilities: config.capabilities,
+            lease_capacity: config.leaseCapacity,
+            fuel_source: config.fuelSource === "local" ? "local" : "conduit",
+            ...(brief ? { workspace_brief: brief } : {}),
+        }) });
+}
+try {
+    if (command === "connect")
+        await connect();
+    else if (command === "join")
+        await join();
+    else if (command === "fuel")
+        await fuelCommand();
+    else if (command === "mcp")
+        await runMcp();
+    else if (command === "runner")
+        await runner();
+    else if (command === "install-service")
+        await installService();
+    else if (command === "uninstall-service")
+        await uninstallService();
+    else
+        throw new Error(`Usage: ${BRIDGE_NPX} <join|connect|fuel|mcp|runner|install-service|uninstall-service>`);
+}
+catch (error) {
+    console.error(error instanceof Error ? redactSecrets(error.message) : "Conduit command failed");
+    process.exitCode = 1;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+import { saveConfig } from "./config.js";
+export class ConduitRequestError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export class ConduitClient {
+    config;
+    persist;
+    constructor(config, persist = saveConfig) {
+        this.config = config;
+        this.persist = persist;
+    }
+    async request(path, init = {}) {
+        const response = await fetch(`${this.config.baseUrl}${path}`, {
+            ...init,
+            headers: { authorization: `Bearer ${this.config.runnerKey}`, "content-type": "application/json", ...init.headers },
+        });
+        const data = await response.json();
+        if (!response.ok)
+            throw new ConduitRequestError(data.error?.message ?? `Conduit request failed (${response.status})`, response.status, data.error?.code);
+        return data;
+    }
+    async claim(taskId, attemptId) {
+        const data = await this.request(`/runner/v1/tasks/${taskId}/claim`, { method: "POST", body: JSON.stringify({ attempt_id: attemptId, idempotency_key: `bridge:claim:${attemptId}` }) });
+        const active = { taskId, attemptId, leaseToken: String(data.lease_token), leaseExpiresAt: String(data.lease_expires_at), phase: "claimed" };
+        this.config.activeAttempts[taskId] = active;
+        await this.persist(this.config);
+        return { ...data, lease_token: "stored by Conduit Bridge" };
+    }
+    attempt(taskId) {
+        const active = this.config.activeAttempts[taskId];
+        if (!active)
+            throw new Error("Task has not been claimed by this Bridge");
+        return active;
+    }
+    async attemptRequest(taskId, action, body) {
+        const active = this.attempt(taskId);
+        return this.request(`/runner/v1/tasks/${taskId}/${action}`, { method: "POST", body: JSON.stringify({ ...body, attempt_id: active.attemptId, lease_token: active.leaseToken }) });
+    }
+    async updateAttempt(taskId, patch) {
+        const active = this.attempt(taskId);
+        Object.assign(active, patch);
+        await this.persist(this.config);
+        return active;
+    }
+    async clearAttempt(taskId) {
+        delete this.config.activeAttempts[taskId];
+        await this.persist(this.config);
+    }
+    /** Rotate and cache a project-scoped gateway fuel key for agent /v1 calls. */
+    async ensureFuel(projectId) {
+        const cached = this.config.fuel?.[projectId]?.gatewayKey;
+        if (cached)
+            return cached;
+        const data = await this.request(`/runner/v1/fuel/${projectId}`);
+        const gatewayKey = String(data.gateway_secret);
+        this.config.fuel = { ...this.config.fuel, [projectId]: { gatewayKey } };
+        await this.persist(this.config);
+        return gatewayKey;
+    }
+}

package/dist/config.js

@@ -0,0 +1,87 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const directory = join(homedir(), ".config", "conduit");
+const path = join(directory, "config.json");
+const pendingPath = join(directory, "pending-connect.json");
+const installationPath = join(directory, "installation.json");
+export async function loadConfig() {
+    const config = await loadConfigIfPresent();
+    if (!config)
+        throw new Error("Conduit is not connected. Run `conduit join --url <worker-url>` first.");
+    return config;
+}
+export async function loadConfigIfPresent() {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    // Fail closed on configs from before the organization retrofit: a Bridge
+    // without an organization identity must reconnect, not guess its tenant.
+    const config = raw;
+    const required = [
+        ["baseUrl", config.baseUrl], ["organizationId", config.organizationId], ["machineId", config.machineId], ["runnerKey", config.runnerKey],
+    ];
+    for (const [field, value] of required) {
+        if (typeof value !== "string" || value.length === 0) {
+            throw new Error(`Bridge configuration is missing ${field}; run \`conduit join --url <worker-url>\` to reconnect this machine.`);
+        }
+    }
+    config.activeAttempts ??= {};
+    for (const active of Object.values(config.activeAttempts))
+        active.phase ??= "agent_running";
+    if (config.fuelSource !== "local" && config.fuelSource !== "conduit")
+        config.fuelSource = "conduit";
+    return config;
+}
+export async function saveConfig(config) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+export async function loadPendingConnection() {
+    try {
+        return JSON.parse(await readFile(pendingPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function savePendingConnection(connection) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(pendingPath, `${JSON.stringify(connection, null, 2)}\n`, { mode: 0o600 });
+    await chmod(pendingPath, 0o600);
+}
+export async function clearPendingConnection() {
+    await unlink(pendingPath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+}
+export async function loadOrCreateInstallationId() {
+    try {
+        const identity = JSON.parse(await readFile(installationPath, "utf8"));
+        if (/^device_[A-Za-z0-9_-]{32}$/.test(identity.id))
+            return identity.id;
+    }
+    catch {
+        // Create the local identity below.
+    }
+    const identity = { id: `device_${randomBytes(24).toString("base64url")}` };
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(installationPath, `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+    await chmod(installationPath, 0o600);
+    return identity.id;
+}
+export function suggestMachineName(host, installationId) {
+    const base = host.split(".")[0]?.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "computer";
+    const suffix = installationId.slice(-5).toLowerCase();
+    return `${base.slice(0, 199 - suffix.length)}-${suffix}`;
+}
+export function redactSecrets(value) {
+    return value.replace(/(runner_sk_|gateway_sk_|lease_|connect_)[A-Za-z0-9-]+/g, "$1[redacted]");
+}

package/dist/detect.js

@@ -0,0 +1,31 @@
+import { access, constants } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+const CLIENTS = [
+    { command: "codex", label: "Codex CLI" },
+    { command: "claude", label: "Claude Code" },
+    { command: "cursor", label: "Cursor" },
+    { command: "code", label: "Visual Studio Code" },
+];
+export async function detectInstalledClients(pathValue = process.env.PATH ?? "", platform = process.platform) {
+    const directories = pathValue.split(delimiter).filter(Boolean);
+    const extensions = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+    const detected = [];
+    for (const client of CLIENTS) {
+        const found = await firstExecutable(directories.flatMap((directory) => extensions.map((extension) => join(directory, `${client.command}${extension}`))));
+        if (found)
+            detected.push(client.label);
+    }
+    return detected;
+}
+async function firstExecutable(paths) {
+    for (const path of paths) {
+        try {
+            await access(path, constants.X_OK);
+            return path;
+        }
+        catch {
+            // Continue through PATH; absence is an expected diagnostic result.
+        }
+    }
+    return null;
+}