@fusionkit/cli 0.1.3 → 0.1.5

package/README.md

@@ -47,7 +47,7 @@ cloud panel (skip with `--yes`). Use `--local` for the on-device MLX panel, or
 Tired of long flag lines? Scaffold a committed `fusionkit.json`:
 
 ```bash
-fusionkit fusion init
+fusionkit init
 ```
 
 It records the panel, judge, default tool, and run defaults so the whole team
@@ -60,7 +60,7 @@ config and a dry-run preview with `fusionkit status`.
 - `fusionkit codex | claude | cursor` — launch that agent backed by the panel.
 - `fusionkit serve` — just run the gateway and print setup snippets for any tool.
 - `fusionkit fusion [tool]` — the generic launcher (interactive picker on a TTY).
-- `fusionkit fusion init` — scaffold `fusionkit.json` for this repo.
+- `fusionkit init` — scaffold `fusionkit.json` for this repo.
 - `fusionkit doctor` — check prerequisites with fix hints.
 - `fusionkit status` — show the effective config and what a run will do.
 

package/dist/cli.js

@@ -5,18 +5,11 @@ import { FUSIONKIT_PYPI_VERSION } from "./fusion-quickstart.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerEnsemble } from "./commands/ensemble.js";
 import { registerFusion } from "./commands/fusion.js";
-import { registerInit } from "./commands/init.js";
-import { registerLifecycle } from "./commands/lifecycle.js";
 import { registerLocal } from "./commands/local.js";
-import { registerPlane } from "./commands/plane.js";
-import { registerRun } from "./commands/run.js";
-import { registerRunner } from "./commands/runner.js";
-import { registerSecrets } from "./commands/secrets.js";
 /**
- * Build the `fusionkit` command tree. The global `--dir` option must precede the
- * subcommand (`enablePositionalOptions` keeps the launcher commands' passthrough
- * unambiguous). Each `register*` helper attaches its command(s) and reads the
- * global home directory via `program.opts().dir`.
+ * Build the `fusionkit` command tree. `enablePositionalOptions` keeps the
+ * launcher commands' passthrough unambiguous (fusionkit's own flags must
+ * precede the tool name). Each `register*` helper attaches its command(s).
  */
 function cliVersion() {
     // dist/cli.js -> ../package.json is the published package manifest.
@@ -34,14 +27,7 @@ export function buildProgram() {
         .name("fusionkit")
         .description("real model fusion behind your coding agent (codex, claude, cursor)")
         .version(`@fusionkit/cli ${cliVersion()} (synthesizer: fusionkit@${FUSIONKIT_PYPI_VERSION} from PyPI)`, "-v, --version", "print the CLI (npm) and pinned synthesizer (PyPI) versions")
-        .option("-d, --dir <dir>", "fusionkit home (default: ./.fusionkit)")
         .enablePositionalOptions();
-    registerInit(program);
-    registerPlane(program);
-    registerRunner(program);
-    registerSecrets(program);
-    registerRun(program);
-    registerLifecycle(program);
     registerEnsemble(program);
     registerLocal(program);
     registerFusion(program);

package/dist/commands/fusion.js

@@ -4,6 +4,7 @@ import { loadFusionConfig } from "../fusion-config.js";
 import { runFusionInit } from "../fusion-init.js";
 import { fail } from "../shared/errors.js";
 import { collect, parseFusionTool, parseIdValue, parsePanelModelSpec, parsePort } from "../shared/options.js";
+import { reapFusionServices } from "../shared/portless.js";
 /** Attach the panel/gateway flags shared by `fusion` and the per-tool launchers. */
 function applyFusionOptions(command) {
     return command
@@ -23,6 +24,8 @@ function applyFusionOptions(command) {
         .option("--yes", "skip the interactive cloud-panel cost confirmation")
         .option("--auth-token <token>", "require a bearer token on the gateway")
         .option("--port <n>", "gateway port (default: ephemeral)")
+        .option("--portless", "route services through portless stable URLs (default; needs the proxy)")
+        .option("--no-portless", "disable portless; use raw loopback ports (same as PORTLESS=0)")
         .allowUnknownOption()
         .passThroughOptions();
 }
@@ -52,6 +55,8 @@ function resolveOptions(opts) {
         options.observe = opts.observe;
     if (opts.yes === true)
         options.yes = true;
+    if (opts.portless !== undefined)
+        options.portless = opts.portless;
     if (opts.authToken !== undefined)
         options.authToken = opts.authToken;
     if (opts.port !== undefined)
@@ -92,6 +97,8 @@ function mergeConfig(options, config) {
         options.local = config.local;
     if (options.observe === undefined && config.observe !== undefined)
         options.observe = config.observe;
+    if (options.portless === undefined && config.portless !== undefined)
+        options.portless = config.portless;
     if (options.cursorKitDir === undefined && config.cursorKitDir != null)
         options.cursorKitDir = config.cursorKitDir;
     if (options.port === undefined && config.port != null)
@@ -122,22 +129,34 @@ function resolveContext(opts) {
     return { options, ...(config?.tool !== undefined ? { configTool: config.tool } : {}) };
 }
 export function registerFusion(program) {
+    // Top-level `init` — scaffold a committed fusionkit.json for this repo.
+    program
+        .command("init")
+        .description("scaffold a committed fusionkit.json for this repo")
+        .option("--repo <dir>", "coding workspace the panel fuses over")
+        .option("--force", "overwrite an existing fusionkit.json")
+        .action(async (opts) => {
+        const repoRoot = configRepoRoot(resolveOptions(opts));
+        const code = await runFusionInit({ repoRoot, force: opts.force === true });
+        process.exit(code);
+    });
     // Generic `fusion [tool]` — keeps the original surface and interactive pick.
     applyFusionOptions(program
         .command("fusion")
         .description("one command: real model fusion backs a coding agent")
-        .argument("[tool]", `${FUSION_TOOLS.join(" | ")} | init (omit on a TTY to pick interactively)`)
+        .argument("[tool]", `${FUSION_TOOLS.join(" | ")} | stop (omit on a TTY to pick interactively)`)
         .argument("[args...]", "arguments forwarded to the tool")
-        .option("--tool <tool>", `coding agent to launch (${FUSION_TOOLS.join(" | ")})`)
-        .option("--force", "overwrite an existing fusionkit.json (with `fusion init`)"))
+        .option("--tool <tool>", `coding agent to launch (${FUSION_TOOLS.join(" | ")})`))
         .addHelpText("after", "\nfusionkit's own flags must precede the tool name; everything after the tool is forwarded to it." +
-        "\nRun `fusionkit fusion init` to scaffold a committed fusionkit.json for this repo.")
+        "\nRun `fusionkit init` to scaffold a committed fusionkit.json for this repo." +
+        "\nRun `fusionkit fusion stop` to reap portless singleton services (router, dashboard, ...).")
         .action(async (positionalTool, args, opts) => {
-        // `fusion init` scaffolds the per-repo config instead of launching a tool.
-        if (positionalTool === "init") {
-            const repoRoot = configRepoRoot(resolveOptions(opts));
-            const code = await runFusionInit({ repoRoot, force: opts.force === true });
-            process.exit(code);
+        // `fusion stop` reaps persistent portless singletons left running by prior
+        // runs (the router, dashboard, ...).
+        if (positionalTool === "stop") {
+            const stopped = await reapFusionServices((line) => console.error(line));
+            console.error(`fusion: stopped ${stopped} portless service(s)`);
+            process.exit(0);
         }
         const { options, configTool } = resolveContext(opts);
         let tool = opts.tool ? parseFusionTool(opts.tool) : undefined;

package/dist/cursor-acp.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Real Cursor ACP front-door producer. Spawns the Cursorkit bridge (its
+ * local-model backend pointed at the running Fusion Harness Gateway) and drives
+ * the real cursor-agent CLI in ACP mode, asserting the fusion-synthesized
+ * sentinel reaches Cursor via session/update. Returns undefined when the
+ * Cursorkit checkout or the cursor-agent CLI are unavailable, so the acceptance
+ * suite records the explicit `blocked` / `cursorkit_backend_not_running`
+ * outcome instead of a silent pass.
+ */
+import type { FrontDoorOutcomeProducer } from "@fusionkit/model-gateway";
+export type CursorAcpProducerInput = {
+    cursorKitDir: string | undefined;
+    gatewayUrl: string;
+    sentinel: string;
+    repo: string;
+    command?: string;
+    modelName?: string;
+    timeoutMs?: number;
+};
+export declare function buildCursorAcpProducer(input: CursorAcpProducerInput): FrontDoorOutcomeProducer | undefined;

package/dist/cursor-acp.js

@@ -0,0 +1,205 @@
+/**
+ * Real Cursor ACP front-door producer. Spawns the Cursorkit bridge (its
+ * local-model backend pointed at the running Fusion Harness Gateway) and drives
+ * the real cursor-agent CLI in ACP mode, asserting the fusion-synthesized
+ * sentinel reaches Cursor via session/update. Returns undefined when the
+ * Cursorkit checkout or the cursor-agent CLI are unavailable, so the acceptance
+ * suite records the explicit `blocked` / `cursorkit_backend_not_running`
+ * outcome instead of a silent pass.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { createInterface } from "node:readline";
+function commandOnPath(command) {
+    if (command.includes("/"))
+        return existsSync(command);
+    const pathValue = process.env.PATH ?? "";
+    return pathValue
+        .split(delimiter)
+        .filter((entry) => entry.length > 0)
+        .some((dir) => existsSync(join(dir, command)));
+}
+function normalizeModelBaseUrl(gatewayUrl) {
+    const trimmed = gatewayUrl.replace(/\/+$/, "");
+    return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+export function buildCursorAcpProducer(input) {
+    const command = input.command ?? "cursor-agent";
+    if (input.cursorKitDir === undefined || input.cursorKitDir.length === 0) {
+        return undefined;
+    }
+    if (!existsSync(join(input.cursorKitDir, "dist/src/cli.js"))) {
+        return undefined;
+    }
+    if (!commandOnPath(command)) {
+        return undefined;
+    }
+    return () => runCursorAcpOutcome({ ...input, command });
+}
+async function runCursorAcpOutcome(input) {
+    const cursorKitDir = input.cursorKitDir;
+    const modelName = input.modelName ?? "local-fusion";
+    const bridgePort = 9700 + Math.floor(Math.random() * 250);
+    const bridgeEnv = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (key.startsWith("BRIDGE_") || key.startsWith("MODEL_") || key.startsWith("CURSOR_UPSTREAM")) {
+            continue;
+        }
+        bridgeEnv[key] = value;
+    }
+    Object.assign(bridgeEnv, {
+        BRIDGE_PORT: String(bridgePort),
+        BRIDGE_ROUTE_INVENTORY: "true",
+        CURSOR_UPSTREAM_BASE_URL: "https://api2.cursor.sh",
+        MODEL_BASE_URL: normalizeModelBaseUrl(input.gatewayUrl),
+        MODEL_API_KEY: "local",
+        MODEL_NAME: modelName,
+        MODEL_PROVIDER_MODEL: "fusion-panel",
+        MODEL_CONTEXT_TOKEN_LIMIT: "128000"
+    });
+    let bridgeOut = "";
+    const bridge = spawn(process.execPath, ["dist/src/cli.js", "serve"], {
+        cwd: cursorKitDir,
+        env: bridgeEnv,
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    bridge.stdout.on("data", (chunk) => {
+        bridgeOut += chunk.toString("utf8");
+    });
+    bridge.stderr.on("data", (chunk) => {
+        bridgeOut += chunk.toString("utf8");
+    });
+    const evidence = [];
+    try {
+        const deadline = Date.now() + 20_000;
+        while (!/bridge listening/.test(bridgeOut) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        if (!/bridge listening/.test(bridgeOut)) {
+            return {
+                id: "cursor-acp",
+                status: "failed",
+                reason: "cursorkit_bridge_did_not_start",
+                evidence
+            };
+        }
+        const acpText = await driveCursorAgentSentinel({
+            command: input.command,
+            bridgePort,
+            modelName,
+            cwd: input.repo,
+            sentinel: input.sentinel,
+            timeoutMs: input.timeoutMs ?? 120_000
+        });
+        if (acpText.includes(input.sentinel)) {
+            evidence.push(input.sentinel);
+            return {
+                id: "cursor-acp",
+                status: "passed",
+                request_path: "/agent.v1.AgentService/Run",
+                evidence
+            };
+        }
+        return {
+            id: "cursor-acp",
+            status: "failed",
+            reason: "sentinel_not_observed_in_cursor_session_update",
+            evidence
+        };
+    }
+    catch (error) {
+        return {
+            id: "cursor-acp",
+            status: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+            evidence
+        };
+    }
+    finally {
+        bridge.kill("SIGTERM");
+    }
+}
+async function driveCursorAgentSentinel(input) {
+    const acp = spawn(input.command, [
+        "--endpoint",
+        `http://127.0.0.1:${input.bridgePort}`,
+        "--model",
+        input.modelName,
+        "--mode",
+        "ask",
+        "acp"
+    ], { cwd: input.cwd, stdio: ["pipe", "pipe", "pipe"] });
+    let acpText = "";
+    let nextId = 1;
+    const pending = new Map();
+    const rl = createInterface({ input: acp.stdout });
+    const send = (method, params) => {
+        const id = nextId++;
+        acp.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        return new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
+    };
+    rl.on("line", (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (message.id !== undefined && message.method === undefined) {
+            const waiter = pending.get(Number(message.id));
+            if (waiter === undefined)
+                return;
+            pending.delete(Number(message.id));
+            if (message.error !== undefined)
+                waiter.reject(message.error);
+            else
+                waiter.resolve(message.result);
+            return;
+        }
+        if (message.method !== undefined) {
+            if (message.method === "session/update")
+                acpText += JSON.stringify(message.params);
+            if (message.id !== undefined) {
+                acp.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: { outcome: { outcome: "skipped", reason: "acceptance" } } })}\n`);
+            }
+        }
+    });
+    const withTimeout = (promise, ms) => Promise.race([
+        promise,
+        new Promise((_resolve, reject) => setTimeout(() => reject(new Error("ACP step timed out")), ms))
+    ]);
+    try {
+        await withTimeout(send("initialize", {
+            protocolVersion: 1,
+            clientCapabilities: {
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false
+            },
+            clientInfo: { name: "fusionkit-acceptance", version: "0.1.0" }
+        }), 60_000);
+        await withTimeout(send("authenticate", { methodId: "cursor_login" }), 60_000);
+        const session = (await withTimeout(send("session/new", { cwd: input.cwd, mcpServers: [] }), 60_000));
+        const sessionId = session.sessionId ?? session.session?.id;
+        if (sessionId === undefined)
+            return acpText;
+        await withTimeout(send("session/prompt", {
+            sessionId,
+            prompt: [
+                {
+                    type: "text",
+                    text: `Reply with exactly this token and nothing else: ${input.sentinel}`
+                }
+            ]
+        }), input.timeoutMs);
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+        return acpText;
+    }
+    finally {
+        rl.close();
+        acp.kill("SIGTERM");
+    }
+}

package/dist/fusion-config.d.ts

@@ -8,6 +8,7 @@ export type FusionConfig = {
     judgeModel?: string;
     local?: boolean;
     observe?: boolean;
+    portless?: boolean;
     cursorKitDir?: string | null;
     port?: number | null;
 };

package/dist/fusion-config.js

@@ -91,6 +91,11 @@ export function parseFusionConfig(raw, source) {
             throw new FusionConfigError(`${source}: observe must be a boolean`);
         config.observe = raw.observe;
     }
+    if (raw.portless !== undefined) {
+        if (typeof raw.portless !== "boolean")
+            throw new FusionConfigError(`${source}: portless must be a boolean`);
+        config.portless = raw.portless;
+    }
     if (raw.cursorKitDir !== undefined && raw.cursorKitDir !== null) {
         if (typeof raw.cursorKitDir !== "string") {
             throw new FusionConfigError(`${source}: cursorKitDir must be a string or null`);

package/dist/fusion-quickstart.d.ts

@@ -13,6 +13,7 @@
  */
 import type { ChildProcess } from "node:child_process";
 import type { EnsembleModel } from "@fusionkit/ensemble";
+import type { PortlessSession } from "./shared/portless.js";
 export type FusionTool = "codex" | "claude" | "cursor" | "serve";
 export declare const FUSION_TOOLS: readonly FusionTool[];
 export type PanelProvider = "mlx" | "openai" | "anthropic" | "google" | "openai-compatible";
@@ -34,7 +35,7 @@ export type PanelModelSpec = {
  * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
  * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
  */
-export declare const FUSIONKIT_PYPI_VERSION = "0.1.1";
+export declare 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.
@@ -94,23 +95,29 @@ export type Observability = {
     traceDir: string;
     close: () => Promise<void>;
 };
-/**
- * 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.
- */
 export declare function startObservability(input: {
     log: (line: string) => void;
     logFile?: string;
     report?: StackReporter;
+    portless: PortlessSession;
 }): Promise<Observability>;
-export type ModelServers = {
+/**
+ * The single `fusionkit serve` router: one process that fronts every panel
+ * model (passthrough, routed by the endpoint id in the request `model` field)
+ * and also performs trajectory synthesis. `endpoints` maps each panel id to the
+ * router URL so the harness reaches its model through the one base URL.
+ */
+export type Router = {
+    url: string;
+    port: number;
+    /** The router process pid (owns its portless route across runs). */
+    pid?: number;
     endpoints: Record<string, string>;
-    judgeUrl: string;
-    judgeModel: string;
     models: EnsembleModel[];
+    /** The endpoint id used as the judge/synthesizer. */
+    judgeModel: string;
+    /** Sorted endpoint ids — the router's discover-or-spawn identity token. */
+    identity: string;
     close: () => Promise<void>;
 };
 /**
@@ -152,19 +159,20 @@ export type StackEvent = {
 };
 export type StackReporter = (event: StackEvent) => void;
 /**
- * Bring up one real model server per panel model and return an id -> base URL
- * map. `mlx` specs run locally; cloud specs are fronted by FusionKit. When
- * `endpoints` is supplied (pre-running servers or tests), those are used
- * verbatim and nothing is spawned.
+ * 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 declare function startModelServers(options: {
+export declare function startRouter(options: {
     specs: PanelModelSpec[];
-    endpoints?: Record<string, string>;
+    judgeModel?: string;
     fusionkitDir?: string;
     logsDir?: string;
     report?: StackReporter;
     log: (line: string) => void;
-}): Promise<ModelServers>;
+}): Promise<Router>;
 export type FusionStack = {
     fusionUrl: string;
     endpoints: Record<string, string>;
@@ -185,24 +193,10 @@ export type StartFusionStackOptions = {
     timeoutMs?: number;
     logsDir?: string;
     report?: StackReporter;
+    /** Active portless session; defaults to a disabled (loopback) session. */
+    portless?: PortlessSession;
     log: (line: string) => void;
 };
-/**
- * Spawn a `fusionkit serve` as the trajectory-synthesis backend, configured
- * with the judge model. FusionKit owns synthesis, so the agent harness fuses
- * its trajectories through this server's `/v1/fusion/trajectories:fuse`.
- */
-export declare function startSynthesisServer(input: {
-    fusionkitDir?: string;
-    judgeModel: string;
-    judgeBaseUrl: string;
-    env: Record<string, string | undefined>;
-    logFile?: string;
-    log: (line: string) => void;
-}): Promise<{
-    url: string;
-    child: ChildProcess;
-}>;
 export declare function startFusionStack(options: StartFusionStackOptions): Promise<FusionStack>;
 /**
  * Start the Cursorkit bridge with its local-model backend pointed at the fusion
@@ -212,6 +206,7 @@ export declare function startCursorBridge(input: {
     cursorKitDir: string;
     fusionUrl: string;
     logFile?: string;
+    caCertPath?: string;
     log: (line: string) => void;
 }): Promise<{
     child: ChildProcess;
@@ -234,8 +229,12 @@ export type RunFusionOptions = {
     observe?: boolean;
     /** Skip the interactive cost/scope confirmation for the cloud panel. */
     yes?: boolean;
+    /** Route services through portless (stable named URLs + singletons). Default on. */
+    portless?: boolean;
     log?: (line: string) => void;
 };
+/** Whether portless is enabled: explicit flag/config wins, else on unless PORTLESS=0. */
+export declare function portlessEnabled(options: RunFusionOptions): boolean;
 export declare function runFusion(tool: FusionTool, toolArgs: string[], options?: RunFusionOptions): Promise<number>;
 /** Interactive tool picker for when no `--tool` was provided on a TTY. */
 export declare function pickTool(): Promise<FusionTool>;