@fusionkit/cli 0.1.4 → 0.1.6

package/dist/fusion-quickstart.js

@@ -10,713 +10,38 @@
  *
  * No mocks: the panel is real models, candidates are real patches verified by
  * really running the repo's tests, and the judge is a real model.
+ *
+ * This module is the run orchestrator; the supporting pieces live in `./fusion/`
+ * (env + defaults, the observability dashboard, the model stack, and preflight)
+ * and are re-exported here so existing import paths keep working.
  */
-import { spawn } from "node:child_process";
-import { execFileSync } from "node:child_process";
-import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { MlxBackend, startGateway } from "@fusionkit/model-gateway";
-import { gatewaySetupSnippets, setGatewayChatter, startFusionStepGateway } from "./gateway.js";
-import { claudeEnv, codexConfigToml } from "./local.js";
+import { join } from "node:path";
+import { FUSION_PANEL_MODEL } from "@fusionkit/tools";
+import { gatewaySetupSnippets, setGatewayChatter } from "./gateway.js";
+import { toolRegistry } from "./tools.js";
 import { createPortlessSession } from "./shared/portless.js";
 import { runPreflight } from "./shared/preflight.js";
 import { createBootView } from "./ui/boot.js";
 import { confirm, select } from "./ui/prompt.js";
 import { canPromptInteractively, isInteractive, uiStream } from "./ui/runtime.js";
 import { bold, brandHeader, dim, glyph, gray, green } from "./ui/theme.js";
-import { freePort, spawnLogged, spawnTool, terminate, waitForHttp, waitForOutput } from "./shared/proc.js";
-export const FUSION_TOOLS = ["codex", "claude", "cursor", "serve"];
-/** The model label the launched tool uses; the gateway ignores it for routing. */
-const FUSION_MODEL_LABEL = "fusion-panel";
-/**
- * The PyPI version of the `fusionkit` Python distribution that provides the
- * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
- * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
- */
-export const FUSIONKIT_PYPI_VERSION = "0.2.0";
-/**
- * Default cloud panel — works cross-platform with only `OPENAI_API_KEY` and
- * `ANTHROPIC_API_KEY` set. The judge defaults to the first entry.
- */
-export const DEFAULT_CLOUD_PANEL = [
-    { id: "gpt", model: "gpt-5.5", provider: "openai" },
-    { id: "sonnet", model: "claude-sonnet-4-6", provider: "anthropic" }
+import { DEFAULT_CLOUD_PANEL, DEFAULT_TRIO, gitToplevel, loadEnvFileInto } from "./fusion/env.js";
+import { openUrl, startObservability } from "./fusion/observability.js";
+import { startFusionStack } from "./fusion/stack.js";
+import { preflightRequirements } from "./fusion/preflight.js";
+export * from "./fusion/env.js";
+export * from "./fusion/observability.js";
+export * from "./fusion/stack.js";
+export * from "./fusion/preflight.js";
+/** Launchable fusion tools (registry-derived) plus the `serve` pseudo-tool. */
+export const FUSION_TOOLS = [
+    ...toolRegistry.launchableFusion().map((tool) => tool.id),
+    "serve"
 ];
-/** The locally cached MLX trio (Apple Silicon only) used behind `--local`. */
-export const DEFAULT_TRIO = [
-    { id: "qwen", model: "mlx-community/Qwen3-1.7B-4bit", provider: "mlx" },
-    { id: "gemma", model: "mlx-community/gemma-3-1b-it-4bit", provider: "mlx" },
-    { id: "llama", model: "mlx-community/Llama-3.2-1B-Instruct-4bit", provider: "mlx" }
-];
-/**
- * How to invoke the `fusionkit` Python CLI: from PyPI via `uvx` by default
- * (no checkout), or from a local checkout via `uv run` when `fusionkitDir` is
- * given (a dev override). Returns the command plus the argv prefix that
- * precedes the subcommand (`serve`, `serve-endpoint`, ...).
- */
-export function fusionkitPyCommand(fusionkitDir) {
-    if (fusionkitDir !== undefined) {
-        return { command: "uv", prefix: ["run", "fusionkit"], cwd: fusionkitDir };
-    }
-    return { command: "uvx", prefix: [`fusionkit@${FUSIONKIT_PYPI_VERSION}`] };
-}
-/**
- * Parse a `.env` file (KEY=VALUE lines, `#` comments, optional `export`,
- * single/double quotes) and fill any keys not already present in `env`.
- * Existing env values win, so an explicitly exported key is never overridden.
- */
-export function loadEnvFileInto(path, env) {
-    if (!existsSync(path))
-        return;
-    for (const rawLine of readFileSync(path, "utf8").split("\n")) {
-        const line = rawLine.trim();
-        if (line.length === 0 || line.startsWith("#"))
-            continue;
-        const withoutExport = line.startsWith("export ") ? line.slice("export ".length) : line;
-        const eq = withoutExport.indexOf("=");
-        if (eq <= 0)
-            continue;
-        const key = withoutExport.slice(0, eq).trim();
-        let value = withoutExport.slice(eq + 1).trim();
-        if (value.length >= 2 &&
-            ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
-            value = value.slice(1, -1);
-        }
-        if (env[key] === undefined)
-            env[key] = value;
-    }
-}
-/** Default env var holding the API key for each cloud provider. */
-export function defaultKeyEnv(provider) {
-    switch (provider) {
-        case "openai":
-            return "OPENAI_API_KEY";
-        case "anthropic":
-            return "ANTHROPIC_API_KEY";
-        case "google":
-            return "GEMINI_API_KEY";
-        case "openai-compatible":
-        case "mlx":
-            return undefined;
-        default: {
-            const exhaustive = provider;
-            throw new Error(`unknown provider ${String(exhaustive)}`);
-        }
-    }
-}
-/** The git repository root containing `dir`, or undefined if it is not in a repo. */
-export function gitToplevel(dir) {
-    try {
-        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
-            cwd: dir,
-            encoding: "utf8",
-            // Don't leak git's "fatal: not a git repository" to our stderr; we surface
-            // a clearer message ourselves.
-            stdio: ["ignore", "pipe", "ignore"]
-        }).trim();
-    }
-    catch {
-        return undefined;
-    }
-}
-/** The PATH binary each coding agent launches as. `serve` launches nothing. */
-function agentBinary(tool) {
-    switch (tool) {
-        case "codex":
-            return "codex";
-        case "claude":
-            return "claude";
-        case "cursor":
-            return "cursor-agent";
-        case "serve":
-            return undefined;
-        default: {
-            const exhaustive = tool;
-            throw new Error(`unknown fusion tool: ${String(exhaustive)}`);
-        }
-    }
-}
-/**
- * Compute the binaries and API keys the run requires given the tool, panel, and
- * options. Pre-running endpoints (`--model-endpoint`) and a pre-running
- * `--synthesis-url` drop the corresponding requirements.
- */
-export function preflightRequirements(tool, models, options) {
-    const requiredBins = [];
-    const requiredEnv = [];
-    const endpointsProvided = options.endpoints !== undefined;
-    const spawnsServers = !endpointsProvided;
-    const spawnsSynthesizer = options.synthesisUrl === undefined;
-    // The FusionKit Python CLI is fetched via uvx (or run from a local checkout).
-    if (spawnsServers || spawnsSynthesizer) {
-        requiredBins.push(options.fusionkitDir !== undefined ? "uv" : "uvx");
-    }
-    const agent = agentBinary(tool);
-    if (agent !== undefined)
-        requiredBins.push(agent);
-    // Cloud panel members need their provider key when we front them ourselves.
-    if (spawnsServers) {
-        for (const spec of models) {
-            const provider = spec.provider ?? "mlx";
-            if (provider === "mlx")
-                continue;
-            const keyEnv = spec.keyEnv ?? defaultKeyEnv(provider);
-            if (keyEnv !== undefined)
-                requiredEnv.push(keyEnv);
-        }
-    }
-    return { requiredBins, requiredEnv };
-}
-/** Fixed port for the local observability dashboard (the scope app). */
-export const SCOPE_DASHBOARD_PORT = 4317;
-/**
- * Locate the isolated scope dashboard app (handoffkit/apps/scope) by walking up
- * from this module. Works from both the compiled dist and src layouts. Only the
- * monorepo dev fallback uses this — published installs ship a prebuilt bundle.
- */
-export function findScopeAppDir() {
-    let dir = dirname(fileURLToPath(import.meta.url));
-    for (let depth = 0; depth < 8; depth++) {
-        const candidate = join(dir, "apps", "scope");
-        if (existsSync(join(candidate, "package.json")))
-            return candidate;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    throw new Error("could not locate apps/scope relative to the handoffkit CLI");
-}
-/**
- * Path to the prebuilt, self-contained dashboard server staged into the CLI
- * package (`scope/server.js`, a sibling of `dist/`), or undefined when it is
- * absent — i.e. a monorepo dev checkout where the bundle was never staged. Both
- * the compiled `dist/fusion-quickstart.js` and the `src/` layout resolve to the
- * same `<cli-package>/scope/server.js`.
- */
-export function bundledScopeServer() {
-    const serverJs = join(dirname(fileURLToPath(import.meta.url)), "..", "scope", "server.js");
-    return existsSync(serverJs) ? serverJs : undefined;
-}
-/**
- * Inject the portless CA so spawned Node children (dashboard, cursor bridge,
- * launched agents) trust the proxy's HTTPS routes. Only `NODE_EXTRA_CA_CERTS` is
- * set: it *extends* Node's trust store. We deliberately do NOT set Python's
- * `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`, because those *replace* the bundle — and
- * pointing them at the portless CA alone breaks the router's outbound HTTPS to
- * real providers (api.openai.com, etc.). The router never calls a portless HTTPS
- * URL (providers go direct; MLX is loopback), so it needs no portless CA. If a
- * Python process ever must reach a portless HTTPS URL, build a combined
- * certifi+portless bundle rather than replacing the bundle here. A no-op when
- * portless is off (no CA path).
- */
-function withCaEnv(env, caCertPath) {
-    if (caCertPath === undefined)
-        return env;
-    return {
-        ...env,
-        NODE_EXTRA_CA_CERTS: env.NODE_EXTRA_CA_CERTS ?? caCertPath
-    };
-}
-/** Best-effort: open a URL in the default browser (no-op on failure). */
-function openUrl(url) {
-    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    try {
-        const child = spawn(command, args, { stdio: "ignore", detached: true });
-        child.on("error", () => { });
-        child.unref();
-    }
-    catch {
-        // opening a browser is a convenience, never required
-    }
-}
-/**
- * Spawn the prebuilt standalone dashboard server (`node scope/server.js`) on the
- * fixed port. The Next standalone entrypoint reads PORT/HOSTNAME from the env
- * (there is no `-p` flag). This is the path every npm-installed user takes.
- */
-function startBundledDashboard(input) {
-    return spawnLogged(process.execPath, [input.serverJs], {
-        cwd: dirname(input.serverJs),
-        ...(input.logFile !== undefined ? { logFile: input.logFile } : {}),
-        env: { ...input.env, PORT: String(SCOPE_DASHBOARD_PORT), HOSTNAME: "127.0.0.1" }
-    });
-}
-/**
- * Monorepo dev fallback: build the scope app once (reusing a prior build) and
- * `next start` it on the fixed port. Only reached in a handoffkit checkout where
- * no bundle was staged; published installs always use {@link startBundledDashboard}.
- */
-function startDevDashboard(input) {
-    const scopeDir = findScopeAppDir();
-    const nextBin = join(scopeDir, "node_modules", ".bin", "next");
-    if (!existsSync(nextBin)) {
-        throw new Error("the observability dashboard is not available in this checkout.\n" +
-            `  Install its dependencies once: cd ${scopeDir} && pnpm install`);
-    }
-    // Rebuilding every run is slow; reuse a prior build when present. The build
-    // output is captured (never inherited) so it can't corrupt a live checklist.
-    const alreadyBuilt = existsSync(join(scopeDir, ".next", "BUILD_ID"));
-    if (!alreadyBuilt) {
-        try {
-            const buildOut = execFileSync(nextBin, ["build"], {
-                cwd: scopeDir,
-                env: input.env,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"]
-            });
-            if (input.logFile !== undefined)
-                appendFileSync(input.logFile, buildOut);
-        }
-        catch (error) {
-            if (input.logFile !== undefined) {
-                appendFileSync(input.logFile, String(error.stdout ?? "") + String(error.stderr ?? ""));
-            }
-            throw new Error("the observability dashboard failed to build. See the log for details" +
-                (input.logFile ? `: ${input.logFile}` : ""));
-        }
-    }
-    return spawnLogged(nextBin, ["start", "-p", String(SCOPE_DASHBOARD_PORT)], {
-        cwd: scopeDir,
-        ...(input.logFile !== undefined ? { logFile: input.logFile } : {}),
-        env: input.env
-    });
-}
-/**
- * Start the scope dashboard on the fixed port, backed by a fresh per-run SQLite
- * file and trace dir, and return the URLs the caller injects (as
- * FUSION_TRACE_URL / FUSION_TRACE_DIR) into every spawned process. Prefers the
- * prebuilt bundle shipped inside the npm package; falls back to building the
- * app from source in a monorepo dev checkout.
- */
-/** Identity token of a reusable scope dashboard (any healthy instance qualifies). */
-const SCOPE_IDENTITY = "scope-dashboard";
-export async function startObservability(input) {
-    const traceDir = mkdtempSync(join(tmpdir(), "fusion-trace-"));
-    const dbPath = join(traceDir, "scope.db");
-    // The dashboard server loads node:sqlite; keep its experimental warnings out
-    // of the log just like the parent CLI. The per-run db/trace dir isolate state.
-    const childEnv = withCaEnv({
-        ...process.env,
-        NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"].filter(Boolean).join(" "),
-        SCOPEKIT_DB: dbPath,
-        FUSION_TRACE_DIR: traceDir
-    }, input.portless.caCertPath);
-    const spawnDashboard = async () => {
-        const bundled = bundledScopeServer();
-        if (input.report)
-            input.report({ kind: "dashboard.start" });
-        else if (bundled !== undefined)
-            input.log("fusion: starting observability dashboard...");
-        else
-            input.log("fusion: building observability dashboard (one-time)...");
-        let proc;
-        try {
-            proc =
-                bundled !== undefined
-                    ? startBundledDashboard({
-                        serverJs: bundled,
-                        env: childEnv,
-                        ...(input.logFile !== undefined ? { logFile: input.logFile } : {})
-                    })
-                    : startDevDashboard({
-                        env: childEnv,
-                        traceDir,
-                        ...(input.logFile !== undefined ? { logFile: input.logFile } : {})
-                    });
-        }
-        catch (error) {
-            throw error instanceof Error ? error : new Error(String(error));
-        }
-        try {
-            await waitForHttp(`http://127.0.0.1:${SCOPE_DASHBOARD_PORT}`, proc, {
-                timeoutMs: 60_000,
-                label: "dashboard"
-            });
-        }
-        catch (error) {
-            terminate(proc.child);
-            throw error instanceof Error ? error : new Error(String(error));
-        }
-        return {
-            port: SCOPE_DASHBOARD_PORT,
-            ...(proc.child.pid !== undefined ? { pid: proc.child.pid } : {}),
-            close: () => terminate(proc.child)
-        };
-    };
-    let resolved;
-    try {
-        resolved = await input.portless.discoverOrSpawn({
-            name: "scope",
-            identity: SCOPE_IDENTITY,
-            healthCheck: async (loopbackUrl) => {
-                try {
-                    const response = await fetch(loopbackUrl, { signal: AbortSignal.timeout(2000) });
-                    return response.ok ? SCOPE_IDENTITY : undefined;
-                }
-                catch {
-                    return undefined;
-                }
-            },
-            spawn: spawnDashboard
-        });
-    }
-    catch (error) {
-        rmSync(traceDir, { recursive: true, force: true });
-        throw error instanceof Error ? error : new Error(String(error));
-    }
-    if (input.report)
-        input.report({ kind: "dashboard.ready", detail: resolved.url });
-    else
-        input.log(`fusion: observability dashboard ready on ${resolved.url}`);
-    return {
-        url: resolved.url,
-        // Trace events post over loopback (the in-process emitters do not carry the
-        // portless CA), so ingest uses the raw port; the named URL is for humans.
-        ingestUrl: `${resolved.loopbackUrl}/api/ingest`,
-        traceDir,
-        close: async () => {
-            await resolved.close();
-            rmSync(traceDir, { recursive: true, force: true });
-        }
-    };
-}
-/**
- * Spawn FusionKit's single-endpoint OpenAI-compatible server for one cloud
- * model, so the per-candidate coding harness can call it like any other
- * OpenAI-compatible backend. Runs `fusionkit serve-endpoint` via `uvx` (or
- * `uv run` against a local checkout); Anthropic/OpenAI/Google calls go through
- * FusionKit's provider clients.
- */
-/**
- * Heuristic: does the captured output indicate a permanent failure (bad key,
- * inaccessible model) that a retry cannot fix? Used to fail fast with a clear
- * message instead of burning the retry budget on a hopeless start.
- */
-function looksPermanentFailure(log) {
-    return /401|403|invalid[ _-]?api[ _-]?key|unauthorized|forbidden|authentication|permission|model[^\n]*(not found|does not exist)|no such model|model_not_found/i.test(log);
-}
-/**
- * Default provider base URL when a cloud spec carries no explicit `baseUrl`.
- * fusionkit's `ModelEndpoint` requires `base_url`, so the router config must
- * always set it (the `serve-endpoint` shim filled this in for us before). Mirrors
- * `PROVIDER_DEFAULT_BASE_URL` in fusionkit's openai_endpoint.py.
- */
-function providerDefaultBaseUrl(provider) {
-    switch (provider) {
-        case "openai":
-            return "https://api.openai.com";
-        case "anthropic":
-            return "https://api.anthropic.com";
-        case "google":
-            return "https://generativelanguage.googleapis.com";
-        case "openai-compatible":
-            return "http://127.0.0.1";
-        default: {
-            const exhaustive = provider;
-            throw new Error(`unknown provider ${String(exhaustive)}`);
-        }
-    }
-}
-/** Pick the panel spec that backs the judge (by model name), else the first. */
-function judgeSpecFor(specs, judgeModel) {
-    const first = specs[0];
-    if (first === undefined)
-        throw new Error("at least one panel model is required");
-    if (judgeModel === undefined)
-        return first;
-    return specs.find((spec) => spec.model === judgeModel) ?? first;
-}
-/**
- * Build the `fusionkit serve` config (YAML) for the consolidated router: one
- * endpoint per panel model. Cloud models call their provider directly (keyed by
- * `api_key_env`); MLX models are fronted as `openai-compatible` endpoints
- * pointing at their in-process gateway loopback URL. The judge endpoint doubles
- * as the synthesizer. Values are JSON-quoted (valid YAML flow scalars).
- */
-function routerConfigYaml(input) {
-    const lines = ["endpoints:"];
-    for (const spec of input.specs) {
-        const provider = spec.provider ?? "mlx";
-        lines.push(`  - id: ${JSON.stringify(spec.id)}`);
-        lines.push(`    model: ${JSON.stringify(spec.model)}`);
-        if (provider === "mlx") {
-            lines.push("    provider: openai-compatible");
-            lines.push(`    base_url: ${JSON.stringify(input.mlxUrls[spec.id] ?? "")}`);
-            lines.push("    api_key: not-needed");
-        }
-        else {
-            // `base_url` is required by fusionkit's ModelEndpoint, so always emit one
-            // (the spec's, or the provider default).
-            const baseUrl = spec.baseUrl ?? providerDefaultBaseUrl(provider);
-            lines.push(`    provider: ${provider}`);
-            lines.push(`    base_url: ${JSON.stringify(baseUrl)}`);
-            const keyEnv = spec.keyEnv ?? defaultKeyEnv(provider);
-            if (keyEnv !== undefined)
-                lines.push(`    api_key_env: ${JSON.stringify(keyEnv)}`);
-        }
-    }
-    lines.push(`default_model: ${JSON.stringify(input.judgeId)}`);
-    lines.push(`judge_model: ${JSON.stringify(input.judgeId)}`);
-    lines.push(`synthesizer_model: ${JSON.stringify(input.judgeId)}`);
-    // Generous budget: reasoning models (gpt-5.x) spend tokens on reasoning before
-    // producing content, so a small cap can yield an empty answer.
-    lines.push("sampling: {temperature: 0.2, top_p: 0.9, max_tokens: 8192}");
-    lines.push("");
-    return lines.join("\n");
-}
-/**
- * Spawn the single `fusionkit serve` router fronting every panel model + the
- * synthesizer. MLX specs first get an in-process OpenAI-compatible gateway
- * (loopback) that the router proxies to; cloud specs call their provider
- * directly. Returns the router URL, an id->routerUrl endpoint map, and a close
- * that tears down the router process and any MLX gateways it fronts.
- */
-export async function startRouter(options) {
-    const { specs, report } = options;
-    const judgeSpec = judgeSpecFor(specs, options.judgeModel);
-    const models = specs.map((spec) => ({ id: spec.id, model: spec.model }));
-    const identity = specs.map((spec) => spec.id).sort().join(",");
-    const announceStart = (label) => {
-        if (report)
-            report({ kind: "server.start", id: "router", label });
-        else
-            options.log(`fusion: starting ${label}...`);
-    };
-    const announceReady = (detail) => {
-        if (report)
-            report({ kind: "server.ready", id: "router", detail });
-        else
-            options.log(`fusion: router ready on ${detail}`);
-    };
-    announceStart(`router · ${specs.map((spec) => spec.id).join(", ")}`);
-    // The router inherits the parent env plus the FusionKit checkout's `.env` (so
-    // provider keys load seamlessly), without overriding anything already exported.
-    // It calls providers directly and MLX over loopback (never a portless HTTPS
-    // URL), so it needs no portless CA — and must keep its default certifi bundle
-    // intact to verify real provider certificates.
-    const env = { ...process.env };
-    if (options.fusionkitDir !== undefined) {
-        loadEnvFileInto(join(options.fusionkitDir, ".env"), env);
-    }
-    const backends = [];
-    const gateways = [];
-    const mlxUrls = {};
-    const closeBackends = async () => {
-        await Promise.allSettled(gateways.map((gateway) => gateway.close()));
-        await Promise.allSettled(backends.map((backend) => backend.stop()));
-    };
-    try {
-        // MLX backends are memory-heavy (each loads a model into RAM), so they start
-        // sequentially before the router that fronts them.
-        for (const spec of specs) {
-            if ((spec.provider ?? "mlx") !== "mlx")
-                continue;
-            const backend = new MlxBackend({ model: spec.model });
-            await backend.start();
-            const gateway = await startGateway({ backend });
-            backends.push(backend);
-            gateways.push(gateway);
-            mlxUrls[spec.id] = gateway.url();
-        }
-        const config = routerConfigYaml({ specs, mlxUrls, judgeId: judgeSpec.id });
-        const configDir = mkdtempSync(join(tmpdir(), "fusion-router-"));
-        const configPath = join(configDir, "router.yaml");
-        writeFileSync(configPath, config);
-        const runner = fusionkitPyCommand(options.fusionkitDir);
-        const port = await freePort();
-        const proc = spawnLogged(runner.command, [...runner.prefix, "serve", "--config", configPath, "--host", "127.0.0.1", "--port", String(port)], {
-            ...(runner.cwd !== undefined ? { cwd: runner.cwd } : {}),
-            ...(options.logsDir !== undefined ? { logFile: join(options.logsDir, "router.log") } : {}),
-            env
-        });
-        proc.child.once("exit", () => rmSync(configDir, { recursive: true, force: true }));
-        const url = `http://127.0.0.1:${port}`;
-        try {
-            await waitForHttp(`${url}/v1/models`, proc, {
-                timeoutMs: 60_000,
-                label: "fusion router",
-                requireOk: true
-            });
-        }
-        catch (error) {
-            terminate(proc.child);
-            // A provider-side rejection (bad key / model) will not be fixed by a
-            // retry, so surface the distilled cause with guidance.
-            const hint = looksPermanentFailure(proc.log()) ? " (check model names and provider API keys)" : "";
-            throw new Error(`${error instanceof Error ? error.message : String(error)}${hint}`);
-        }
-        announceReady(url);
-        const endpoints = Object.fromEntries(specs.map((spec) => [spec.id, url]));
-        return {
-            url,
-            port,
-            ...(proc.child.pid !== undefined ? { pid: proc.child.pid } : {}),
-            endpoints,
-            models,
-            judgeModel: judgeSpec.id,
-            identity,
-            close: async () => {
-                terminate(proc.child);
-                await closeBackends();
-            }
-        };
-    }
-    catch (error) {
-        await closeBackends();
-        throw error;
-    }
-}
-export async function startFusionStack(options) {
-    const report = options.report;
-    const portless = options.portless ?? (await createPortlessSession({ enabled: false }));
-    // Full override (pre-running per-model endpoints + a pre-running synthesis
-    // URL, e.g. tests): use them verbatim and spawn no router.
-    const override = options.endpoints !== undefined && options.synthesisUrl !== undefined;
-    const judgeModelName = options.judgeModel ?? options.models[0]?.model ?? "";
-    const models = options.models.map((spec) => ({ id: spec.id, model: spec.model }));
-    let modelEndpoints;
-    let fusionBackendUrl;
-    let routerClose = () => { };
-    if (override) {
-        modelEndpoints = options.endpoints;
-        fusionBackendUrl = options.synthesisUrl;
-    }
-    else {
-        // Discover-or-spawn the single router (models + synthesis), reusing a
-        // compatible running instance (same endpoint id set) across runs.
-        const expectedIdentity = options.models.map((spec) => spec.id).sort().join(",");
-        const resolved = await portless.discoverOrSpawn({
-            name: "router",
-            identity: expectedIdentity,
-            healthCheck: async (loopbackUrl) => {
-                try {
-                    const response = await fetch(`${loopbackUrl}/v1/models`, { signal: AbortSignal.timeout(2000) });
-                    if (!response.ok)
-                        return undefined;
-                    const body = (await response.json());
-                    return (body.data ?? [])
-                        .map((entry) => entry.id)
-                        .filter((id) => typeof id === "string" && id !== "fusionkit/router")
-                        .sort()
-                        .join(",");
-                }
-                catch {
-                    return undefined;
-                }
-            },
-            spawn: async () => {
-                if (report)
-                    report({ kind: "server.start", id: "router", label: "router" });
-                const router = await startRouter({
-                    specs: options.models,
-                    ...(options.judgeModel !== undefined ? { judgeModel: options.judgeModel } : {}),
-                    ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {}),
-                    ...(options.logsDir !== undefined ? { logsDir: options.logsDir } : {}),
-                    ...(report !== undefined ? { report } : {}),
-                    log: options.log
-                });
-                return {
-                    port: router.port,
-                    ...(router.pid !== undefined ? { pid: router.pid } : {}),
-                    close: router.close
-                };
-            }
-        });
-        // The harness + the in-process step call reach the router over loopback (the
-        // portless name is for humans); see the CA-at-startup note in portless.ts.
-        modelEndpoints = Object.fromEntries(options.models.map((spec) => [spec.id, resolved.loopbackUrl]));
-        fusionBackendUrl = resolved.loopbackUrl;
-        routerClose = resolved.close;
-    }
-    try {
-        if (report)
-            report({ kind: "gateway.start" });
-        // The judge-streamed-trajectory front door: each panel model produces a
-        // trajectory and the judge emits the trajectory the user's tool executes.
-        const gatewayConfig = {
-            fusionBackendUrl,
-            repo: options.repo,
-            outputRoot: options.outputRoot,
-            harnesses: ["agent"],
-            models,
-            judgeModel: judgeModelName,
-            modelEndpoints,
-            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {})
-        };
-        const gateway = await startFusionStepGateway({
-            config: gatewayConfig,
-            host: options.host ?? "127.0.0.1",
-            port: options.port ?? 0,
-            ...(options.authToken !== undefined ? { authToken: options.authToken } : {})
-        });
-        // The gateway runs in-process (dies with this CLI), so it gets a per-run
-        // portless name rather than being a cross-run singleton.
-        const fusionUrl = portless.register("gateway", gateway.port());
-        if (report)
-            report({ kind: "gateway.ready", detail: fusionUrl });
-        return {
-            fusionUrl,
-            endpoints: modelEndpoints,
-            close: async () => {
-                await gateway.close();
-                portless.unregister("gateway");
-                await routerClose();
-            }
-        };
-    }
-    catch (error) {
-        await routerClose();
-        throw error;
-    }
-}
-function scrubbedBridgeEnv() {
-    const env = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value === undefined)
-            continue;
-        if (key.startsWith("BRIDGE_") || key.startsWith("MODEL_") || key.startsWith("E2E_") || key.startsWith("CURSOR_UPSTREAM")) {
-            continue;
-        }
-        env[key] = value;
-    }
-    return env;
-}
-/**
- * Start the Cursorkit bridge with its local-model backend pointed at the fusion
- * gateway, and resolve once it is listening. Returns the child and its port.
- */
-export async function startCursorBridge(input) {
-    const port = await freePort();
-    const env = {
-        ...withCaEnv(scrubbedBridgeEnv(), input.caCertPath),
-        BRIDGE_PORT: String(port),
-        BRIDGE_ROUTE_INVENTORY: "true",
-        CURSOR_UPSTREAM_BASE_URL: "https://api2.cursor.sh",
-        MODEL_BASE_URL: `${input.fusionUrl}/v1`,
-        MODEL_API_KEY: "local",
-        MODEL_NAME: FUSION_MODEL_LABEL,
-        MODEL_PROVIDER_MODEL: FUSION_MODEL_LABEL,
-        MODEL_CONTEXT_TOKEN_LIMIT: "128000"
-    };
-    const proc = spawnLogged(process.execPath, ["dist/src/cli.js", "serve"], {
-        cwd: input.cursorKitDir,
-        ...(input.logFile !== undefined ? { logFile: input.logFile } : {}),
-        env
-    });
-    try {
-        await waitForOutput(proc, /bridge listening/, { timeoutMs: 20_000, label: "Cursorkit bridge" });
-    }
-    catch (error) {
-        terminate(proc.child);
-        throw error instanceof Error ? error : new Error(String(error));
-    }
-    input.log(`fusion: Cursorkit bridge listening on http://127.0.0.1:${port}`);
-    return { child: proc.child, port };
-}
+/** The model label the launched tool uses; the gateway ignores it for routing. */
+const FUSION_MODEL_LABEL = FUSION_PANEL_MODEL;
 /** Whether portless is enabled: explicit flag/config wins, else on unless PORTLESS=0. */
 export function portlessEnabled(options) {
     if (options.portless !== undefined)
@@ -836,7 +161,6 @@ export async function runFusion(tool, toolArgs, options = {}) {
     // spawned child (panel servers, synthesis serve, cursor bridge) inherit it.
     // Without the flag, FUSION_TRACE_* stays unset and all emitters are no-ops.
     let observability;
-    let bridge;
     let stack;
     try {
         if (options.observe === true) {
@@ -916,64 +240,36 @@ export async function runFusion(tool, toolArgs, options = {}) {
             stream.write("\u001b[?25h");
     };
     try {
-        switch (tool) {
-            case "serve": {
-                log("");
-                log(gatewaySetupSnippets(stack.fusionUrl, "http://127.0.0.1:<cursorkit-port>"));
-                log("");
-                log("Gateway is running. Point any tool at it, or Ctrl+C to stop.");
-                await new Promise(() => {
-                    /* run until interrupted */
-                });
-                return 0;
-            }
-            case "codex": {
-                const home = mkdtempSync(join(tmpdir(), "fusionkit-fusion-codex-"));
-                writeFileSync(join(home, "config.toml"), codexConfigToml(stack.fusionUrl, FUSION_MODEL_LABEL));
-                prepareForPassthrough();
-                log("fusion: launching codex (each prompt is a coding task fused across the panel)...");
-                return await spawnTool("codex", toolArgs, { CODEX_HOME: home }, repo);
-            }
-            case "claude": {
-                prepareForPassthrough();
-                log("fusion: launching claude...");
-                return await spawnTool("claude", toolArgs, claudeEnv(stack.fusionUrl, options.authToken), repo);
-            }
-            case "cursor": {
-                const cursorKitDir = options.cursorKitDir ?? process.env.FUSIONKIT_CURSORKIT_DIR ?? process.env.WARRANT_CURSORKIT_DIR;
-                if (cursorKitDir === undefined || cursorKitDir.length === 0) {
-                    log("");
-                    log("Cursor needs a built Cursorkit checkout. Re-run with --cursor-kit-dir <dir>");
-                    log("(or set FUSIONKIT_CURSORKIT_DIR), then this command spawns the bridge and");
-                    log("launches cursor-agent pre-wired to the gateway. Manual setup:");
-                    log(`  MODEL_BASE_URL=${stack.fusionUrl}/v1 MODEL_NAME=${FUSION_MODEL_LABEL} \\`);
-                    log("  MODEL_PROVIDER_MODEL=fusion-panel node dist/src/cli.js serve   # in cursorkit");
-                    log(`  cursor-agent --endpoint http://127.0.0.1:<bridge-port> --model ${FUSION_MODEL_LABEL}`);
-                    return 1;
-                }
-                const started = await startCursorBridge({
-                    cursorKitDir,
-                    fusionUrl: stack.fusionUrl,
-                    logFile: join(logsDir, "cursor-bridge.log"),
-                    ...(portless.caCertPath !== undefined ? { caCertPath: portless.caCertPath } : {}),
-                    log
-                });
-                bridge = started.child;
-                const bridgeUrl = portless.register("cursor", started.port);
-                disposers.push(() => {
-                    portless.unregister("cursor");
-                    if (bridge !== undefined)
-                        terminate(bridge);
-                });
-                prepareForPassthrough();
-                log("fusion: launching cursor-agent...");
-                return await spawnTool("cursor-agent", ["--endpoint", bridgeUrl, "--model", FUSION_MODEL_LABEL, ...toolArgs], {}, repo);
-            }
-            default: {
-                const unreachable = tool;
-                throw new Error(`unknown fusion tool: ${String(unreachable)}`);
-            }
+        if (tool === "serve") {
+            log("");
+            log(gatewaySetupSnippets(stack.fusionUrl, "http://127.0.0.1:<cursorkit-port>"));
+            log("");
+            log("Gateway is running. Point any tool at it, or Ctrl+C to stop.");
+            await new Promise(() => {
+                /* run until interrupted */
+            });
+            return 0;
         }
+        const integration = toolRegistry.get(tool);
+        if (integration === undefined || !integration.modes.includes("fusion")) {
+            throw new Error(`unknown fusion tool: ${String(tool)}`);
+        }
+        const ctx = {
+            mode: "fusion",
+            gatewayUrl: stack.fusionUrl,
+            modelLabel: FUSION_MODEL_LABEL,
+            toolArgs,
+            repo,
+            ...(options.authToken !== undefined ? { authToken: options.authToken } : {}),
+            ...(portless.caCertPath !== undefined ? { caCertPath: portless.caCertPath } : {}),
+            logsDir,
+            log,
+            prepareForPassthrough,
+            registerPort: (name, port) => portless.register(name, port),
+            unregisterPort: (name) => portless.unregister(name),
+            registerDisposer: (dispose) => disposers.push(dispose)
+        };
+        return await integration.launch(ctx);
     }
     finally {
         await cleanup();
@@ -984,9 +280,11 @@ export async function pickTool() {
     return select({
         message: "Which coding agent should model fusion back?",
         options: [
-            { value: "codex", label: "codex", hint: "OpenAI Codex CLI" },
-            { value: "claude", label: "claude", hint: "Claude Code" },
-            { value: "cursor", label: "cursor", hint: "needs --cursor-kit-dir / FUSIONKIT_CURSORKIT_DIR" },
+            ...toolRegistry.launchableFusion().map((tool) => ({
+                value: tool.id,
+                label: tool.id,
+                hint: tool.pickerHint
+            })),
             { value: "serve", label: "serve", hint: "just run the gateway and print setup" }
         ],
         defaultIndex: 0