@fusionkit/tool-cursor 0.1.6

package/dist/bridge.d.ts

@@ -0,0 +1,15 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * 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 declare function startCursorBridge(input: {
+    fusionUrl: string;
+    modelLabel: string;
+    logFile?: string;
+    caCertPath?: string;
+    log: (line: string) => void;
+}): Promise<{
+    child: ChildProcess;
+    port: number;
+}>;

package/dist/bridge.js

@@ -0,0 +1,56 @@
+import { resolveCursorkitCli } from "@fusionkit/ensemble";
+import { freePort, scrubBridgeEnv, spawnLogged, terminate, waitForOutput } from "@fusionkit/tools";
+/**
+ * Inject the portless CA so spawned Node children (the cursor bridge) trust the
+ * proxy's HTTPS routes. Only `NODE_EXTRA_CA_CERTS` is set: it extends Node's
+ * trust store rather than replacing it. A no-op when portless is off.
+ */
+function withCaEnv(env, caCertPath) {
+    if (caCertPath === undefined)
+        return env;
+    return {
+        ...env,
+        NODE_EXTRA_CA_CERTS: env.NODE_EXTRA_CA_CERTS ?? caCertPath
+    };
+}
+/** Drop bridge/model/e2e env so a parent's leftover config never leaks in. */
+function scrubbedBridgeEnv() {
+    return scrubBridgeEnv(process.env, [
+        "BRIDGE_",
+        "MODEL_",
+        "E2E_",
+        "CURSOR_UPSTREAM"
+    ]);
+}
+/**
+ * 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: input.modelLabel,
+        MODEL_PROVIDER_MODEL: input.modelLabel,
+        MODEL_CONTEXT_TOKEN_LIMIT: "128000"
+    };
+    const { serveCli } = resolveCursorkitCli();
+    const proc = spawnLogged(process.execPath, [serveCli, "serve"], {
+        ...(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 };
+}

package/dist/harness.d.ts

@@ -0,0 +1,47 @@
+import type { EnsembleModel, HarnessAdapter } from "@fusionkit/ensemble";
+export type CursorRunMode = "ask" | "agent";
+export type CursorExecInput = {
+    prompt: string;
+    cwd: string;
+    fusionBackendUrl: string;
+    apiKey?: string;
+    model: EnsembleModel;
+    command: string;
+    modelName: string;
+    providerModel: string;
+    mode: CursorRunMode;
+    timeoutMs?: number;
+    env: Record<string, string>;
+};
+export type CursorExecResult = {
+    status: "succeeded" | "failed";
+    transcript: string;
+    diff?: string;
+    toolEvents: number;
+    exitCode?: number;
+    reason?: string;
+};
+export type CursorExecRunner = (input: CursorExecInput) => Promise<CursorExecResult> | CursorExecResult;
+export type CursorHarnessOptions = {
+    id?: string;
+    command?: string;
+    fusionBackendUrl?: string;
+    apiKey?: string;
+    modelName?: string;
+    providerModel?: string;
+    mode?: CursorRunMode;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    runner?: CursorExecRunner;
+    skipWhenUnavailable?: boolean;
+};
+export declare function cursorHarnessUnavailableReason(env?: Record<string, string | undefined>, options?: Pick<CursorHarnessOptions, "command">): string | undefined;
+/**
+ * Drives the real cursor-agent CLI in ACP mode against a freshly spawned
+ * Cursorkit bridge whose local-model backend points at the fusion gateway.
+ * The bridge runs with BRIDGE_AGENT_TOOL_POLICY=all so Cursor can read, edit
+ * (apply_patch/write_file), and run shell commands inside the worktree.
+ */
+export declare function defaultCursorRunner(input: CursorExecInput): Promise<CursorExecResult>;
+export declare function createCursorHarness(options?: CursorHarnessOptions): HarnessAdapter;
+export declare const cursorHarness: typeof createCursorHarness;

package/dist/harness.js

@@ -0,0 +1,377 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { artifactHash } from "@fusionkit/protocol";
+import { resolveCursorkitCli } from "@fusionkit/ensemble";
+import { CURSOR_BRIDGE_MODEL_NAME, FUSION_PANEL_MODEL, buildSkippedCandidate, definedEnv, freePort, normalizeApiBaseUrl, scrubBridgeEnv, spawnLogged, terminate, waitForOutput } from "@fusionkit/tools";
+const DEFAULT_CURSOR_COMMAND = "cursor-agent";
+const DEFAULT_BRIDGE_MODEL_NAME = CURSOR_BRIDGE_MODEL_NAME;
+const DEFAULT_BRIDGE_PROVIDER_MODEL = FUSION_PANEL_MODEL;
+const BRIDGE_START_TIMEOUT_MS = 20_000;
+function commandOnPath(command, env) {
+    if (command.includes("/")) {
+        return existsSync(command);
+    }
+    const pathValue = env.PATH ?? process.env.PATH ?? "";
+    return pathValue
+        .split(delimiter)
+        .filter((entry) => entry.length > 0)
+        .some((dir) => existsSync(join(dir, command)));
+}
+function resolveAvailability(options, env) {
+    const command = options.command ?? DEFAULT_CURSOR_COMMAND;
+    if (options.runner !== undefined) {
+        return { available: true, command };
+    }
+    // Cursorkit ships as a bundled dependency, so only the Cursor CLI itself is a
+    // runtime prerequisite.
+    if (!commandOnPath(command, env)) {
+        return {
+            available: false,
+            reason: `Cursor CLI "${command}" was not found on PATH; install the Cursor CLI (https://cursor.com/cli) and log in.`
+        };
+    }
+    return { available: true, command };
+}
+export function cursorHarnessUnavailableReason(env = process.env, options = {}) {
+    const availability = resolveAvailability(options, definedEnv(env));
+    return availability.available ? undefined : availability.reason;
+}
+function modeFor(descriptor, override) {
+    if (override !== undefined)
+        return override;
+    switch (descriptor.policy.sideEffects) {
+        case "none":
+        case "read_only":
+            return "ask";
+        case "writes_workspace":
+        case "network":
+        case "tool_execution":
+        case "unknown":
+            return "agent";
+        default: {
+            const exhausted = descriptor.policy.sideEffects;
+            throw new Error(`unsupported side effects policy: ${String(exhausted)}`);
+        }
+    }
+}
+function skippedCandidate(input) {
+    return buildSkippedCandidate({
+        ...input,
+        adapter: "cursor",
+        transcript: `Cursor adapter skipped: ${input.reason}`
+    });
+}
+/**
+ * Drives the real cursor-agent CLI in ACP mode against a freshly spawned
+ * Cursorkit bridge whose local-model backend points at the fusion gateway.
+ * The bridge runs with BRIDGE_AGENT_TOOL_POLICY=all so Cursor can read, edit
+ * (apply_patch/write_file), and run shell commands inside the worktree.
+ */
+export async function defaultCursorRunner(input) {
+    // Reserve a real free loopback port instead of a random guess so parallel
+    // candidates cannot collide on the same bridge port.
+    const bridgePort = await freePort();
+    const bridgeEnv = scrubBridgeEnv(input.env);
+    Object.assign(bridgeEnv, {
+        BRIDGE_PORT: String(bridgePort),
+        BRIDGE_ROUTE_INVENTORY: "true",
+        BRIDGE_AGENT_TOOL_POLICY: "all",
+        BRIDGE_AGENT_TOOL_MAX_ITERATIONS: "24",
+        CURSOR_UPSTREAM_BASE_URL: "https://api2.cursor.sh",
+        MODEL_BASE_URL: normalizeApiBaseUrl(input.fusionBackendUrl),
+        MODEL_API_KEY: input.apiKey ?? "local",
+        MODEL_NAME: input.modelName,
+        MODEL_PROVIDER_MODEL: input.providerModel,
+        MODEL_CONTEXT_TOKEN_LIMIT: "128000"
+    });
+    const { serveCli } = resolveCursorkitCli();
+    const bridge = spawnLogged(process.execPath, [serveCli, "serve"], {
+        cwd: input.cwd,
+        env: bridgeEnv
+    });
+    const timeoutMs = input.timeoutMs ?? 180_000;
+    try {
+        try {
+            await waitForOutput(bridge, /bridge listening/, {
+                timeoutMs: BRIDGE_START_TIMEOUT_MS,
+                label: "Cursorkit bridge"
+            });
+        }
+        catch (error) {
+            return {
+                status: "failed",
+                transcript: bridge.log(),
+                toolEvents: 0,
+                reason: error instanceof Error ? error.message : String(error)
+            };
+        }
+        const printResult = await driveCursorAgentPrint({
+            command: input.command,
+            bridgePort,
+            modelName: input.modelName,
+            mode: input.mode,
+            cwd: input.cwd,
+            prompt: input.prompt,
+            timeoutMs
+        });
+        const diff = captureWorktreeDiff(input.cwd);
+        return {
+            status: printResult.status,
+            transcript: printResult.transcript,
+            toolEvents: diff !== undefined && diff.length > 0 ? 1 : 0,
+            ...(printResult.exitCode !== undefined ? { exitCode: printResult.exitCode } : {}),
+            ...(diff !== undefined ? { diff } : {}),
+            ...(printResult.reason !== undefined ? { reason: printResult.reason } : {})
+        };
+    }
+    finally {
+        // Tear down the whole bridge process group (serve may spawn children),
+        // escalating to SIGKILL if it ignores the grace period.
+        terminate(bridge.child);
+        bridge.closeLog();
+    }
+}
+/**
+ * Drives cursor-agent in headless print mode (`-p`), which "has access to all
+ * tools, including write and shell". The bridge runs the Cursor tool loop over
+ * the SSE/BidiAppend transport, so the agent can read, apply_patch/write, and
+ * run shell inside the worktree. `--trust` skips the workspace-trust prompt and
+ * `--force` auto-approves tool actions. For read-only tasks we pass `--mode ask`.
+ */
+async function driveCursorAgentPrint(input) {
+    const args = [
+        "-p",
+        "--force",
+        "--trust",
+        "--output-format",
+        "text",
+        "--model",
+        input.modelName,
+        "--endpoint",
+        `http://127.0.0.1:${input.bridgePort}`
+    ];
+    if (input.mode === "ask") {
+        args.push("--mode", "ask");
+    }
+    args.push(input.prompt);
+    return await new Promise((resolve) => {
+        const child = spawn(input.command, args, {
+            cwd: input.cwd,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, input.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({
+                status: "failed",
+                transcript: stdout,
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            const transcript = [stdout, stderr].filter(Boolean).join("\n");
+            if (timedOut) {
+                resolve({
+                    status: "failed",
+                    transcript,
+                    reason: "cursor-agent timed out"
+                });
+                return;
+            }
+            resolve({
+                status: code === 0 ? "succeeded" : "failed",
+                transcript,
+                exitCode: code ?? 0,
+                ...(code === 0 ? {} : { reason: stderr.slice(0, 500) })
+            });
+        });
+    });
+}
+function captureWorktreeDiff(cwd) {
+    try {
+        const result = spawnSync("git", ["-C", cwd, "diff"], { encoding: "utf8" });
+        const stdout = result.stdout ?? "";
+        return result.status === 0 && stdout.length > 0 ? stdout : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createCursorHarness(options = {}) {
+    const id = options.id ?? "cursor";
+    const runner = options.runner ?? defaultCursorRunner;
+    const skipWhenUnavailable = options.skipWhenUnavailable ?? true;
+    return {
+        id,
+        harnessKind: "cursor",
+        prepare: () => {
+            const env = definedEnv(options.env ?? process.env);
+            return { env, availability: resolveAvailability(options, env) };
+        },
+        capabilities: () => {
+            const env = definedEnv(options.env ?? process.env);
+            const available = resolveAvailability(options, env).available;
+            const status = available ? "supported" : "degraded";
+            return {
+                workspace_read: status,
+                workspace_write: status,
+                apply_patch: status,
+                tool_call_loop: status,
+                tool_records: status,
+                verification: status,
+                route_observation: "supported",
+                adapter_available: available ? "supported" : "unsupported"
+            };
+        },
+        verificationProfile: () => ({
+            id: `${id}-verification`,
+            requiredEvidence: [
+                "cursor-agent transcript",
+                "session status",
+                "worktree diff or skip reason"
+            ]
+        }),
+        run: async ({ descriptor, model, ordinal, prepared, worktree }) => {
+            const state = prepared;
+            if (!state.availability.available) {
+                if (!skipWhenUnavailable) {
+                    throw new Error(state.availability.reason);
+                }
+                return skippedCandidate({
+                    descriptor,
+                    model,
+                    ordinal,
+                    reason: state.availability.reason
+                });
+            }
+            const fusionBackendUrl = options.fusionBackendUrl ?? state.env.FUSIONKIT_BASE_URL;
+            if (fusionBackendUrl === undefined || fusionBackendUrl.length === 0) {
+                return skippedCandidate({
+                    descriptor,
+                    model,
+                    ordinal,
+                    reason: "Fusion backend URL is not configured for the Cursor harness."
+                });
+            }
+            const cwd = worktree?.path ?? descriptor.workspace ?? process.cwd();
+            let result;
+            try {
+                result = await runner({
+                    prompt: descriptor.prompt,
+                    cwd,
+                    fusionBackendUrl,
+                    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+                    model,
+                    command: state.availability.command,
+                    modelName: options.modelName ?? DEFAULT_BRIDGE_MODEL_NAME,
+                    providerModel: options.providerModel ?? model.model ?? DEFAULT_BRIDGE_PROVIDER_MODEL,
+                    mode: modeFor(descriptor, options.mode),
+                    ...(options.timeoutMs !== undefined
+                        ? { timeoutMs: options.timeoutMs }
+                        : descriptor.policy.timeoutMs !== undefined
+                            ? { timeoutMs: descriptor.policy.timeoutMs }
+                            : {}),
+                    env: state.env
+                });
+            }
+            catch (error) {
+                return skippedCandidate({
+                    descriptor,
+                    model,
+                    ordinal,
+                    reason: error instanceof Error ? error.message : String(error)
+                });
+            }
+            const transcript = result.transcript;
+            const outputHash = artifactHash(transcript.length > 0 ? transcript : `cursor:${descriptor.id}`);
+            const status = result.status;
+            const candidateId = `${descriptor.id}_${model.id}_${ordinal}`;
+            const artifacts = [
+                {
+                    artifact_id: `artifact_${descriptor.id}_${model.id}_cursor_transcript`,
+                    kind: "transcript",
+                    hash: outputHash,
+                    redaction_status: "synthetic"
+                }
+            ];
+            if (result.diff !== undefined && result.diff.length > 0) {
+                artifacts.push({
+                    artifact_id: `artifact_${descriptor.id}_${model.id}_cursor_patch`,
+                    kind: "patch",
+                    hash: artifactHash(result.diff),
+                    redaction_status: "synthetic"
+                });
+            }
+            return {
+                candidateId,
+                model,
+                status,
+                ...(worktree
+                    ? { branchName: worktree.branchName, worktreePath: worktree.path }
+                    : {}),
+                transcript,
+                ...(result.diff !== undefined ? { diff: result.diff } : {}),
+                log: transcript,
+                artifacts,
+                toolRecords: [
+                    {
+                        execution_id: `exec_${candidateId}_cursor`,
+                        plan_id: `plan_${candidateId}_cursor`,
+                        status,
+                        output_hash: outputHash,
+                        ...(status === "failed"
+                            ? {
+                                error: {
+                                    kind: "provider_error",
+                                    message: result.reason ?? "Cursor run failed.",
+                                    retryable: false
+                                }
+                            }
+                            : {})
+                    }
+                ],
+                verification: {
+                    status,
+                    evidence: [
+                        `tool_events=${result.toolEvents}`,
+                        outputHash,
+                        ...(result.diff !== undefined ? ["worktree_diff"] : [])
+                    ],
+                    ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {})
+                },
+                ...(status === "failed"
+                    ? {
+                        error: {
+                            kind: "provider_error",
+                            message: result.reason ?? "Cursor run failed.",
+                            retryable: false
+                        }
+                    }
+                    : {}),
+                metadata: {
+                    adapter: "cursor",
+                    mode: modeFor(descriptor, options.mode),
+                    tool_events: result.toolEvents,
+                    has_diff: result.diff !== undefined && result.diff.length > 0
+                }
+            };
+        },
+        collectArtifacts: () => [],
+        cleanup: () => undefined
+    };
+}
+export const cursorHarness = createCursorHarness;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { ToolIntegration } from "@fusionkit/tools";
+export declare const cursorTool: ToolIntegration;
+export { createCursorHarness, cursorHarness, cursorHarnessUnavailableReason, defaultCursorRunner } from "./harness.js";
+export type { CursorExecInput, CursorExecResult, CursorExecRunner, CursorHarnessOptions, CursorRunMode } from "./harness.js";
+export { startCursorBridge } from "./bridge.js";
+export { cursorInstructions, launchCursor } from "./launch.js";

package/dist/index.js

@@ -0,0 +1,60 @@
+import { createCursorHarness, cursorHarnessUnavailableReason } from "./harness.js";
+import { launchCursor } from "./launch.js";
+const LIVE_SMOKE_PROMPT = "Read README.md if present, then reply exactly CURSOR_LIVE_SMOKE_OK. Do not modify files.";
+export const cursorTool = {
+    id: "cursor",
+    displayName: "Cursor",
+    pickerHint: "needs a logged-in cursor-agent CLI",
+    binary: "cursor-agent",
+    modes: ["fusion", "local"],
+    harnessKinds: ["cursor-acp", "cursor-desktop"],
+    launch: launchCursor,
+    createHarness: (kind, options) => createCursorHarness({
+        id: kind,
+        fusionBackendUrl: options.fusionBackendUrl,
+        ...(options.fusionApiKey !== undefined ? { apiKey: options.fusionApiKey } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {})
+    }),
+    harness: {
+        harnessKind: "cursor",
+        sideEffects: "writes_workspace",
+        responseShape: "Return text suitable for Cursor ACP session/update plus route evidence notes."
+    },
+    dashboard: {
+        id: "cursor",
+        harnessKind: "cursor",
+        displayName: "Cursor",
+        availability: "credential_gated",
+        capabilities: {
+            model_override: "supported",
+            transcript_capture: "supported",
+            diff_capture: "supported",
+            tool_loop_capture: "supported",
+            patch_apply_visibility: "supported",
+            route_model_observation: "supported",
+            verification_hint: "supported",
+            replay_support: "degraded"
+        },
+        notes: ["Credential-gated; requires a logged-in Cursor CLI (Cursorkit is bundled)."],
+        makeMatrixHarness: (env) => createCursorHarness({ env }),
+        credentialSkipReason: (env) => cursorHarnessUnavailableReason(env),
+        smoke: {
+            taskId: "cursor-skipped",
+            model: { id: "cursor", model: "fusion-panel" },
+            sideEffects: "writes_workspace",
+            allowedTools: ["read_file", "write_file", "apply_patch", "run_shell"],
+            makeHarness: () => createCursorHarness({ env: {} })
+        },
+        liveSmoke: {
+            taskId: "cursor-live",
+            envName: "FUSIONKIT_CURSOR_SMOKE",
+            prompt: LIVE_SMOKE_PROMPT,
+            modelEnvName: "FUSIONKIT_CURSOR_SMOKE_MODEL",
+            defaultModel: "fusion-panel",
+            makeHarness: (env) => createCursorHarness({ env, skipWhenUnavailable: false })
+        }
+    }
+};
+export { createCursorHarness, cursorHarness, cursorHarnessUnavailableReason, defaultCursorRunner } from "./harness.js";
+export { startCursorBridge } from "./bridge.js";
+export { cursorInstructions, launchCursor } from "./launch.js";

package/dist/launch.d.ts

@@ -0,0 +1,5 @@
+import type { ToolLaunchContext } from "@fusionkit/tools";
+/** Human-facing setup for Cursor (IDE plan/chat panel only; needs a public URL). */
+export declare function cursorInstructions(publicUrl: string, model: string): string;
+/** Boot Cursor, branching on whether it backs the fusion panel or a local model. */
+export declare function launchCursor(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -0,0 +1,75 @@
+import { join } from "node:path";
+import { spawnTool, terminate } from "@fusionkit/tools";
+import { startCursorBridge } from "./bridge.js";
+/** Human-facing setup for Cursor (IDE plan/chat panel only; needs a public URL). */
+export function cursorInstructions(publicUrl, model) {
+    return [
+        "Cursor backs only its plan/chat panel with a custom model, and cannot reach",
+        "localhost — so this uses a public tunnel. In Cursor: Settings -> Models ->",
+        "enable 'Override OpenAI Base URL', then set:",
+        "",
+        `  Override OpenAI Base URL : ${publicUrl}/v1`,
+        `  Model name               : ${model}`,
+        `  OpenAI API Key           : fusionkit-local (any non-empty value)`,
+        "",
+        "Use the chat/plan panel (Cmd/Ctrl+L). Composer, inline edit, apply, and",
+        "autocomplete remain on Cursor's own backend and are not affected."
+    ].join("\n");
+}
+/**
+ * Fusion launch: spawn the Cursorkit bridge (its local-model backend pointed at
+ * the fusion gateway) and exec cursor-agent against it.
+ */
+async function launchCursorFusion(ctx) {
+    const started = await startCursorBridge({
+        fusionUrl: ctx.gatewayUrl,
+        modelLabel: ctx.modelLabel,
+        ...(ctx.logsDir !== undefined ? { logFile: join(ctx.logsDir, "cursor-bridge.log") } : {}),
+        ...(ctx.caCertPath !== undefined ? { caCertPath: ctx.caCertPath } : {}),
+        log: ctx.log
+    });
+    const bridgeUrl = ctx.registerPort("cursor", started.port);
+    ctx.registerDisposer(() => {
+        ctx.unregisterPort("cursor");
+        terminate(started.child);
+    });
+    ctx.prepareForPassthrough();
+    ctx.log("fusion: launching cursor-agent...");
+    return await spawnTool("cursor-agent", ["--endpoint", bridgeUrl, "--model", ctx.modelLabel, ...ctx.toolArgs], {}, ctx.repo);
+}
+/**
+ * Local launch: Cursor cannot reach loopback, so print the IDE override setup
+ * for a public tunnel and hold the gateway up.
+ */
+async function launchCursorLocal(ctx) {
+    const publicUrl = ctx.publicUrl;
+    if (publicUrl === undefined || publicUrl.length === 0) {
+        ctx.log("");
+        ctx.log("Cursor needs a public URL (it cannot reach localhost). Start a tunnel to");
+        ctx.log(`${ctx.gatewayUrl} (e.g. 'cloudflared tunnel --url ${ctx.gatewayUrl}' or 'ngrok http`);
+        ctx.log(`${ctx.gatewayUrl.replace(/^https?:\/\//, "")}'), then re-run with --public-url <url>`);
+        ctx.log("or set FUSIONKIT_PUBLIC_URL.");
+        return 1;
+    }
+    ctx.log("");
+    ctx.log(cursorInstructions(publicUrl, ctx.modelLabel));
+    ctx.log("");
+    ctx.log("Gateway is running; leave this process up while you use Cursor. Ctrl+C to stop.");
+    await new Promise(() => {
+        /* keep the gateway (and tunnel target) alive */
+    });
+    return 0;
+}
+/** Boot Cursor, branching on whether it backs the fusion panel or a local model. */
+export async function launchCursor(ctx) {
+    switch (ctx.mode) {
+        case "fusion":
+            return await launchCursorFusion(ctx);
+        case "local":
+            return await launchCursorLocal(ctx);
+        default: {
+            const exhaustive = ctx.mode;
+            throw new Error(`unknown launch mode: ${String(exhaustive)}`);
+        }
+    }
+}

package/dist/test/cursor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/cursor.test.js

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { createMockHarness, ensemble } from "@fusionkit/ensemble";
+import { cursorHarness, defaultCursorRunner } from "../index.js";
+function tempOutputRoot() {
+    const outputRoot = mkdtempSync(join(tmpdir(), "ensemble-cursor-out-"));
+    return {
+        outputRoot,
+        cleanup: () => rmSync(outputRoot, { recursive: true, force: true })
+    };
+}
+function descriptor(outputRoot, overrides = {}) {
+    return {
+        id: "cursor_ensemble_test",
+        harness: createMockHarness(),
+        models: [{ id: "cursor", model: "fusion-panel" }],
+        runtime: { id: "local" },
+        judge: { id: "judge", model: "fake-judge" },
+        policy: {
+            id: "policy",
+            allowedTools: ["read_file", "apply_patch", "run_shell"],
+            sideEffects: "writes_workspace",
+            timeoutMs: 1_000
+        },
+        prompt: "Fix the failing test in the repo.",
+        sourceRepo: "handoffkit",
+        baseGitSha: "b".repeat(40),
+        outputRoot,
+        ...overrides
+    };
+}
+test("cursor adapter skips clearly when the Cursor CLI is unavailable", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    try {
+        const result = await ensemble.run(descriptor(outputRoot, {
+            harness: cursorHarness({ env: { PATH: "" } })
+        }));
+        assert.equal(result.harnessRunResult.status, "skipped");
+        assert.equal(result.candidates[0]?.status, "skipped");
+        assert.equal(result.candidates[0]?.error?.kind, "capability_missing");
+        assert.match(result.candidates[0]?.error?.message ?? "", /Cursor CLI .* was not found on PATH/);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("cursor adapter produces a real candidate with a diff via the injected runner", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    let observedMode;
+    let observedBackend;
+    const runner = (input) => {
+        observedMode = input.mode;
+        observedBackend = input.fusionBackendUrl;
+        return {
+            status: "succeeded",
+            transcript: "Applied the fix and verified the tests pass.",
+            diff: "--- a/calc.ts\n+++ b/calc.ts\n@@ -1,1 +1,1 @@\n-return a - b;\n+return a + b;",
+            toolEvents: 3
+        };
+    };
+    try {
+        const result = await ensemble.run(descriptor(outputRoot, {
+            harness: cursorHarness({
+                fusionBackendUrl: "http://127.0.0.1:9999",
+                runner
+            })
+        }));
+        assert.equal(observedMode, "agent");
+        assert.equal(observedBackend, "http://127.0.0.1:9999");
+        assert.equal(result.harnessRunResult.status, "succeeded");
+        const candidate = result.candidates[0];
+        assert.equal(candidate?.status, "succeeded");
+        assert.equal(candidate?.metadata?.adapter, "cursor");
+        assert.equal(candidate?.metadata?.tool_events, 3);
+        assert.equal(candidate?.metadata?.has_diff, true);
+        assert.ok(result.artifacts.some((artifact) => artifact.kind === "patch"), "a patch artifact should be captured");
+    }
+    finally {
+        cleanup();
+    }
+});
+test("defaultCursorRunner spawns the bridge, drives the agent, and tears it down", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "cursor-runner-"));
+    // Stub `cursorkit serve`: announce readiness, then idle until terminated.
+    const stubServe = join(workdir, "serve.cjs");
+    writeFileSync(stubServe, [
+        'process.stdout.write("bridge listening on 127.0.0.1\\n");',
+        "const timer = setInterval(() => {}, 1000);",
+        'process.on("SIGTERM", () => { clearInterval(timer); process.exit(0); });'
+    ].join("\n"));
+    // Stub `cursor-agent`: print a deterministic transcript and exit 0.
+    const stubAgent = join(workdir, "cursor-agent");
+    writeFileSync(stubAgent, '#!/bin/sh\necho "CURSOR_STUB_OK"\nexit 0\n');
+    chmodSync(stubAgent, 0o755);
+    const previousOverride = process.env.FUSIONKIT_CURSORKIT_SERVE_CLI;
+    process.env.FUSIONKIT_CURSORKIT_SERVE_CLI = stubServe;
+    try {
+        const result = await defaultCursorRunner({
+            prompt: "say hello",
+            cwd: workdir,
+            fusionBackendUrl: "http://127.0.0.1:9999",
+            model: { id: "cursor", model: "fusion-panel" },
+            command: stubAgent,
+            modelName: "cursor-bridge",
+            providerModel: "fusion-panel",
+            mode: "agent",
+            timeoutMs: 10_000,
+            env: { PATH: process.env.PATH ?? "" }
+        });
+        assert.equal(result.status, "succeeded");
+        assert.match(result.transcript, /CURSOR_STUB_OK/);
+        assert.equal(result.exitCode, 0);
+    }
+    finally {
+        if (previousOverride === undefined) {
+            delete process.env.FUSIONKIT_CURSORKIT_SERVE_CLI;
+        }
+        else {
+            process.env.FUSIONKIT_CURSORKIT_SERVE_CLI = previousOverride;
+        }
+        rmSync(workdir, { recursive: true, force: true });
+    }
+});
+test("defaultCursorRunner reports a clear failure when the bridge never starts", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "cursor-runner-fail-"));
+    // Stub serve that exits immediately without announcing readiness.
+    const stubServe = join(workdir, "serve.cjs");
+    writeFileSync(stubServe, 'process.exit(1);\n');
+    const stubAgent = join(workdir, "cursor-agent");
+    writeFileSync(stubAgent, '#!/bin/sh\necho "unused"\n');
+    chmodSync(stubAgent, 0o755);
+    const previousOverride = process.env.FUSIONKIT_CURSORKIT_SERVE_CLI;
+    process.env.FUSIONKIT_CURSORKIT_SERVE_CLI = stubServe;
+    try {
+        const result = await defaultCursorRunner({
+            prompt: "say hello",
+            cwd: workdir,
+            fusionBackendUrl: "http://127.0.0.1:9999",
+            model: { id: "cursor", model: "fusion-panel" },
+            command: stubAgent,
+            modelName: "cursor-bridge",
+            providerModel: "fusion-panel",
+            mode: "agent",
+            timeoutMs: 10_000,
+            env: { PATH: process.env.PATH ?? "" }
+        });
+        assert.equal(result.status, "failed");
+        assert.equal(result.toolEvents, 0);
+        assert.ok((result.reason ?? "").length > 0);
+    }
+    finally {
+        if (previousOverride === undefined) {
+            delete process.env.FUSIONKIT_CURSORKIT_SERVE_CLI;
+        }
+        else {
+            process.env.FUSIONKIT_CURSORKIT_SERVE_CLI = previousOverride;
+        }
+        rmSync(workdir, { recursive: true, force: true });
+    }
+});
+test("cursor adapter capabilities report supported when available", () => {
+    const runner = () => ({
+        status: "succeeded",
+        transcript: "ok",
+        toolEvents: 0
+    });
+    const harness = cursorHarness({ runner, fusionBackendUrl: "http://x/v1" });
+    const capabilities = harness.capabilities({});
+    assert.equal(capabilities.apply_patch, "supported");
+    assert.equal(capabilities.tool_call_loop, "supported");
+    assert.equal(capabilities.adapter_available, "supported");
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fusionkit/tool-cursor",
+  "private": false,
+  "version": "0.1.6",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/tool-cursor"
+  },
+  "description": "Cursor tool integration for fusionkit: Cursorkit bridge launcher plus the ensemble Cursor harness adapter.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@fusionkit/ensemble": "0.1.6",
+    "@fusionkit/tools": "0.1.6",
+    "@fusionkit/protocol": "0.1.6"
+  }
+}