@velum-labs/routekit-tool-cursor 0.10.0 → 0.11.0

package/README.md

@@ -1,10 +1,13 @@
 # @velum-labs/routekit-tool-cursor
 
-Product-neutral Cursor launcher, bridge serializer, and canonical ACP driver.
+Product-neutral Cursor custom-endpoint setup and canonical ACP driver.
 
 ## Architecture
 
-This package owns the one Cursor launch path and canonical driver.
+Cursor is supported through its own bring-your-own-key setting: Cursor Settings
+-> Models -> Override OpenAI Base URL, pointed at the gateway's `/v1/cursor`
+door. RouteKit does not proxy or emulate Cursor's backend protocol, so
+`cursor-agent` model calls stay on the logged-in Cursor account.
 
 ## Usage
 

package/dist/driver.js

@@ -8,7 +8,11 @@ const DEFAULT_COMMAND = "cursor-agent";
 const AUTH_METHOD_ID = "cursor_login";
 export const cursorDriverConfigSchema = z.object({
     command: z.string().default(DEFAULT_COMMAND),
-    /** OpenAI-compatible endpoint cursor-agent's model calls route to (the gateway/bridge). */
+    /**
+     * Caller-supplied `cursor-agent --endpoint`. This is a Cursor backend URL,
+     * not an OpenAI base URL, so the RouteKit gateway cannot serve it; model
+     * calls otherwise use the logged-in Cursor account.
+     */
     endpoint: z.string().optional(),
     model: z.string().optional()
 });

package/dist/index.d.ts

@@ -1,11 +1,6 @@
 import type { ToolIntegration } from "@velum-labs/routekit-tools";
 export declare const cursorTool: ToolIntegration;
-export { buildCursorAcpProducer } from "./acp.js";
-export { startCursorBridge } from "./bridge.js";
-export { CURSOR_AGENT_TOOL_MAX_ITERATIONS, CURSOR_AGENT_TOOL_POLICY, cursorBridgeEnv, cursorBridgeModelEnv, cursorIdeEnv, cursorIdeModelsJson } from "./bridge-config.js";
-export { resolveCursorkitCli } from "./cursorkit-path.js";
-export type { CursorkitCli } from "./cursorkit-path.js";
-export { cursorIdeInstructions, cursorInstructions, launchCursor } from "./launch.js";
+export { cursorByokBaseUrl, cursorInstructions, launchCursor } from "./launch.js";
 export { CURSOR_AGENTS_DIRNAME, cursorSubagentMarkdown, scaffoldCursorSubagents } from "./subagents.js";
 export { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";
 export type { CursorDriverConfig } from "./driver.js";

package/dist/index.js

@@ -1,20 +1,22 @@
+import { cursorModelName } from "@velum-labs/routekit-contracts";
 import { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";
-import { launchCursor } from "./launch.js";
+import { cursorByokBaseUrl, launchCursor } from "./launch.js";
 const driver = createCursorDriver();
 export const cursorTool = {
     id: "cursor",
     displayName: "Cursor",
-    pickerHint: "Cursor CLI or desktop",
-    binary: "cursor-agent",
+    pickerHint: "Cursor editor via a custom OpenAI endpoint",
     packageName: "@velum-labs/routekit-tool-cursor",
-    installHint: "install the Cursor CLI: https://cursor.com/cli",
-    authSummary: "Cursor uses a logged-in cursor-agent CLI and a local bridge.",
-    setupSnippet: ({ gatewayUrl, model = "gateway-model", note }) => `cursor-agent --endpoint ${note === undefined || note.length === 0 ? gatewayUrl : note} --model ${model}`,
+    installHint: "install Cursor: https://cursor.com",
+    authSummary: "Cursor uses its own login plus the gateway's OpenAI-compatible /v1/cursor endpoint.",
+    setupSnippet: ({ gatewayUrl, model = "gateway-model" }) => `Cursor Settings -> Models -> Override OpenAI Base URL: ${cursorByokBaseUrl(gatewayUrl)} (model name: ${cursorModelName(model)})`,
     launch: launchCursor,
     driver: {
         kind: driver.kind,
         driver,
-        configForRoute: (route) => cursorDriverConfigSchema.parse({ endpoint: route.gatewayUrl, model: route.model })
+        // cursor-agent talks to Cursor's own backend, not the gateway, so a
+        // RouteKit route contributes no endpoint here.
+        configForRoute: (route) => cursorDriverConfigSchema.parse({ model: route.model })
     },
     capabilities: {
         streaming: "full",
@@ -23,10 +25,6 @@ export const cursorTool = {
         reasoning_controls: "degraded"
     }
 };
-export { buildCursorAcpProducer } from "./acp.js";
-export { startCursorBridge } from "./bridge.js";
-export { CURSOR_AGENT_TOOL_MAX_ITERATIONS, CURSOR_AGENT_TOOL_POLICY, cursorBridgeEnv, cursorBridgeModelEnv, cursorIdeEnv, cursorIdeModelsJson } from "./bridge-config.js";
-export { resolveCursorkitCli } from "./cursorkit-path.js";
-export { cursorIdeInstructions, cursorInstructions, launchCursor } from "./launch.js";
+export { cursorByokBaseUrl, cursorInstructions, launchCursor } from "./launch.js";
 export { CURSOR_AGENTS_DIRNAME, cursorSubagentMarkdown, scaffoldCursorSubagents } from "./subagents.js";
 export { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";

package/dist/launch.d.ts

@@ -1,4 +1,12 @@
 import type { ToolLaunchContext } from "@velum-labs/routekit-tools";
-export declare function cursorIdeInstructions(model: string): string;
-export declare function cursorInstructions(publicUrl: string, model: string, apiKey?: string): string;
+/** Base URL for Cursor's "Override OpenAI Base URL" setting. */
+export declare function cursorByokBaseUrl(gatewayUrl: string): string;
+export declare function cursorInstructions(gatewayUrl: string, model: string, apiKey?: string): string;
+/**
+ * Print the endpoint Cursor must be pointed at, then return.
+ *
+ * Unlike the other tools RouteKit launches, there is no child process to
+ * supervise: Cursor is configured once in its own settings and connects from
+ * its own process against a gateway this command does not own.
+ */
 export declare function launchCursor(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -1,124 +1,36 @@
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
 import { cursorModelName } from "@velum-labs/routekit-contracts";
-import { definedEnv, spawnLogged, spawnTool, terminate, waitForOutput } from "@velum-labs/routekit-runtime";
-import { cursorIdeEnv } from "./bridge-config.js";
-import { startCursorBridge } from "./bridge.js";
-import { resolveCursorkitCli } from "./cursorkit-path.js";
+import { normalizeApiBaseUrl } from "@velum-labs/routekit-runtime";
 import { scaffoldCursorSubagents } from "./subagents.js";
-function bridgeModels(ctx) {
-    return ctx.spec.models.flatMap((model) => [
-        {
-            id: model.id,
-            ...(model.label !== undefined ? { displayName: model.label } : {}),
-            ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {})
-        },
-        ...(model.aliases ?? []).map((alias) => ({
-            id: alias,
-            ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {})
-        }))
-    ]);
+/** Base URL for Cursor's "Override OpenAI Base URL" setting. */
+export function cursorByokBaseUrl(gatewayUrl) {
+    return `${normalizeApiBaseUrl(gatewayUrl)}/cursor`;
 }
-export function cursorIdeInstructions(model) {
-    return `Cursor IDE is connected to the gateway. Choose "${model}" in the Agent model picker.`;
-}
-export function cursorInstructions(publicUrl, model, apiKey) {
+export function cursorInstructions(gatewayUrl, model, apiKey) {
     // Cursor routes BYOK by model-name prefix (`claude-*` → Anthropic,
     // `gemini-*` → Google). The gateway's /v1/cursor mirror namespaces every
     // id under `routekit/` so the pasted name always uses the OpenAI key +
     // base-URL override.
     return [
         "In Cursor Settings -> Models, enable Override OpenAI Base URL and set:",
-        `  Override OpenAI Base URL : ${publicUrl}/v1/cursor`,
+        `  Override OpenAI Base URL : ${cursorByokBaseUrl(gatewayUrl)}`,
         `  Model name               : ${cursorModelName(model)}`,
         `  OpenAI API Key           : ${apiKey ?? "routekit-local"}`,
         "Names are namespaced under routekit/ so Cursor does not route them to Anthropic/Google keys."
     ].join("\n");
 }
-function cursorCliAuthEnv(env = process.env) {
-    const apiKey = env.CURSOR_API_KEY;
-    const configDirectory = env.CURSOR_CONFIG_DIR;
-    return definedEnv({
-        CURSOR_API_KEY: typeof apiKey === "string" && apiKey.length > 0 ? apiKey : undefined,
-        CURSOR_CONFIG_DIR: typeof configDirectory === "string" && configDirectory.length > 0
-            ? configDirectory
-            : undefined
-    });
-}
-async function launchCursorCli(ctx) {
-    const started = await startCursorBridge({
-        gatewayUrl: ctx.spec.gatewayUrl,
-        modelLabel: ctx.spec.defaultModel,
-        models: bridgeModels(ctx),
-        ...(ctx.spec.auth?.token !== undefined
-            ? { apiKey: ctx.spec.auth.token }
-            : {}),
-        ...(ctx.spec.logsDir !== undefined
-            ? { logFile: join(ctx.spec.logsDir, "cursor-bridge.log") }
-            : {}),
-        ...(ctx.spec.tls?.caCertPath !== undefined
-            ? { caCertPath: ctx.spec.tls.caCertPath }
-            : {}),
-        log: ctx.log
-    });
-    const bridgeUrl = ctx.registerPort("cursor", started.port);
-    ctx.registerDisposer(() => {
-        ctx.unregisterPort("cursor");
-        terminate(started.child);
-    });
-    ctx.prepareForPassthrough();
-    return await spawnTool("cursor-agent", ["--endpoint", bridgeUrl, "--model", ctx.spec.defaultModel, ...ctx.spec.args], cursorCliAuthEnv(), ctx.spec.cwd);
-}
-async function launchCursorRemote(ctx) {
-    const publicUrl = ctx.spec.publicUrl;
-    if (publicUrl === undefined) {
-        throw new Error("Cursor remote configuration requires a public gateway URL");
-    }
-    ctx.log(cursorInstructions(publicUrl, ctx.spec.defaultModel, ctx.spec.auth?.token));
-    await new Promise(() => { });
-    return 0;
-}
-async function launchCursorIde(ctx) {
-    const { serveCli } = resolveCursorkitCli();
-    const repo = ctx.spec.cwd ?? process.cwd();
-    const stateDir = ctx.spec.logsDir !== undefined
-        ? join(ctx.spec.logsDir, "cursor-ide")
-        : join(repo, ".cursor-rpc-ide");
-    mkdirSync(stateDir, { recursive: true });
-    const proc = spawnLogged(process.execPath, [serveCli, "ck"], {
-        cwd: stateDir,
-        env: cursorIdeEnv({
-            repo,
-            gatewayUrl: ctx.spec.gatewayUrl,
-            modelLabel: ctx.spec.defaultModel,
-            models: bridgeModels(ctx),
-            ...(ctx.spec.auth?.token !== undefined ? { apiKey: ctx.spec.auth.token } : {}),
-            ...(ctx.spec.tls?.caCertPath !== undefined
-                ? { caCertPath: ctx.spec.tls.caCertPath }
-                : {})
-        }),
-        ...(ctx.spec.logsDir !== undefined
-            ? { logFile: join(ctx.spec.logsDir, "cursor-ide.log") }
-            : {})
-    });
-    await waitForOutput(proc, /ck ready|bridge listening/, {
-        timeoutMs: 60_000,
-        label: "Cursor desktop bridge"
-    });
-    ctx.registerDisposer(() => terminate(proc.child));
-    ctx.log(cursorIdeInstructions(ctx.spec.defaultModel));
-    return await new Promise((resolve) => {
-        proc.child.once("exit", (code) => resolve(code ?? 0));
-    });
-}
+/**
+ * Print the endpoint Cursor must be pointed at, then return.
+ *
+ * Unlike the other tools RouteKit launches, there is no child process to
+ * supervise: Cursor is configured once in its own settings and connects from
+ * its own process against a gateway this command does not own.
+ */
 export async function launchCursor(ctx) {
     const profiles = ctx.spec.agentProfiles ?? [];
     if (profiles.length > 0) {
         scaffoldCursorSubagents(ctx.spec.cwd ?? process.cwd(), profiles, ctx.log);
     }
-    if (ctx.spec.ide === true)
-        return launchCursorIde(ctx);
-    if (ctx.spec.publicUrl !== undefined)
-        return launchCursorRemote(ctx);
-    return launchCursorCli(ctx);
+    ctx.log(cursorInstructions(ctx.spec.publicUrl ?? ctx.spec.gatewayUrl, ctx.spec.defaultModel, ctx.spec.auth?.token));
+    ctx.log("The gateway keeps serving this endpoint; Cursor connects on its own.");
+    return 0;
 }

package/dist/test/instructions.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { cursorModelName } from "@velum-labs/routekit-contracts";
-import { cursorInstructions } from "../launch.js";
+import { cursorByokBaseUrl, cursorInstructions, launchCursor } from "../launch.js";
 test("cursorInstructions print the gateway's routekit/-namespaced spelling", () => {
     const model = "claude-code/claude-fable-5";
     const text = cursorInstructions("https://example.ts.net", model, "token");
@@ -10,3 +10,41 @@ test("cursorInstructions print the gateway's routekit/-namespaced spelling", ()
     assert.doesNotMatch(text, /claude-code-claude-fable-5/);
     assert.match(text, /namespaced under routekit\//);
 });
+test("cursorByokBaseUrl normalizes the gateway origin onto the /v1/cursor door", () => {
+    assert.equal(cursorByokBaseUrl("http://127.0.0.1:8080"), "http://127.0.0.1:8080/v1/cursor");
+    assert.equal(cursorByokBaseUrl("http://127.0.0.1:8080/"), "http://127.0.0.1:8080/v1/cursor");
+    assert.equal(cursorByokBaseUrl("https://gateway.test/v1"), "https://gateway.test/v1/cursor");
+});
+function launchContext(spec, log) {
+    return {
+        spec: {
+            gatewayUrl: "http://127.0.0.1:8080",
+            defaultModel: "openai/gpt-5.5",
+            models: [],
+            args: [],
+            ...spec
+        },
+        log,
+        prepareForPassthrough: () => {
+            throw new Error("cursor must not take over the terminal for a spawned tool");
+        },
+        registerPort: () => {
+            throw new Error("cursor must not register a local bridge port");
+        },
+        unregisterPort: () => { },
+        registerDisposer: () => { }
+    };
+}
+test("launchCursor prints BYOK setup for the local gateway without spawning a bridge", async () => {
+    const lines = [];
+    assert.equal(await launchCursor(launchContext({}, (line) => lines.push(line))), 0);
+    assert.match(lines[0], /Override OpenAI Base URL : http:\/\/127\.0\.0\.1:8080\/v1\/cursor/);
+    assert.match(lines[0], new RegExp(`Model name\\s+: ${cursorModelName("openai/gpt-5.5")}`));
+    assert.match(lines[0], /OpenAI API Key\s+: routekit-local/);
+});
+test("launchCursor prefers a public gateway URL and the gateway token", async () => {
+    const lines = [];
+    await launchCursor(launchContext({ publicUrl: "https://gateway.ts.net", auth: { token: "gateway-token" } }, (line) => lines.push(line)));
+    assert.match(lines[0], /Override OpenAI Base URL : https:\/\/gateway\.ts\.net\/v1\/cursor/);
+    assert.match(lines[0], /OpenAI API Key\s+: gateway-token/);
+});

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@velum-labs/routekit-tool-cursor",
   "private": false,
-  "version": "0.10.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "url": "git+https://github.com/velum-labs/routekit.git",
     "directory": "packages/tool-cursor"
   },
-  "description": "Product-neutral Cursor launcher, bridge serializer, and canonical ACP driver.",
+  "description": "Product-neutral Cursor custom-endpoint setup and canonical ACP driver.",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -26,13 +26,12 @@
     "provenance": true
   },
   "dependencies": {
-    "@velum-labs/cursorkit": "0.2.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.10.0",
-    "@velum-labs/routekit-runtime": "0.10.0",
-    "@velum-labs/routekit-tools": "0.10.0",
-    "@velum-labs/routekit-harness-core": "0.10.0"
+    "@velum-labs/routekit-harness-core": "0.11.0",
+    "@velum-labs/routekit-contracts": "0.11.0",
+    "@velum-labs/routekit-runtime": "0.11.0",
+    "@velum-labs/routekit-tools": "0.11.0"
   },
   "keywords": [
     "llm",

package/dist/acp.d.ts

@@ -1,20 +0,0 @@
-type CursorFrontDoorOutcome = {
-    id: string;
-    status: "passed" | "failed";
-    reason?: string;
-    request_path?: string;
-    evidence: string[];
-};
-type CursorFrontDoorOutcomeProducer = () => Promise<CursorFrontDoorOutcome>;
-export type CursorAcpProducerInput = {
-    gatewayUrl: string;
-    sentinel: string;
-    repo: string;
-    command?: string;
-    modelName?: string;
-    providerModel?: string;
-    timeoutMs?: number;
-    enabled?: boolean;
-};
-export declare function buildCursorAcpProducer(input: CursorAcpProducerInput): CursorFrontDoorOutcomeProducer | undefined;
-export {};

package/dist/acp.js

@@ -1,178 +0,0 @@
-import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
-import { commandOnPath, reservePort, terminate } from "@velum-labs/routekit-runtime";
-import { cursorBridgeEnv } from "./bridge-config.js";
-import { resolveCursorkitCli } from "./cursorkit-path.js";
-export function buildCursorAcpProducer(input) {
-    const command = input.command ?? "cursor-agent";
-    // The live Cursor ACP probe drives the real cursor-agent CLI through the
-    // bundled Cursorkit bridge, so it stays opt-in: without the live flag the
-    // acceptance suite reports this door as `blocked` rather than spawning live
-    // tooling (keeping deterministic runs free of credential/CLI dependencies).
-    if (input.enabled === false) {
-        return undefined;
-    }
-    if (!commandOnPath(command)) {
-        return undefined;
-    }
-    return () => runCursorAcpOutcome({ ...input, command });
-}
-async function runCursorAcpOutcome(input) {
-    const modelName = input.modelName ?? "routekit";
-    // Hold a real free loopback port until the bridge is about to bind it, so
-    // parallel probes cannot collide on (or steal) it.
-    const reservation = await reservePort();
-    const bridgePort = reservation.port;
-    const bridgeEnv = cursorBridgeEnv({
-        port: bridgePort,
-        gatewayUrl: input.gatewayUrl,
-        modelName,
-        providerModel: input.providerModel ?? modelName
-    });
-    const { serveCli } = resolveCursorkitCli();
-    let bridgeOut = "";
-    await reservation.release();
-    // detached: the bridge may spawn children; teardown kills the whole group.
-    const bridge = spawn(process.execPath, [serveCli, "serve"], {
-        env: bridgeEnv,
-        detached: true,
-        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 {
-        // Process-group SIGTERM with SIGKILL escalation, not a bare child kill.
-        terminate(bridge);
-    }
-}
-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, detached: true, 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: "routekit-acp", 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();
-        terminate(acp);
-    }
-}

package/dist/bridge-config.d.ts

@@ -1,40 +0,0 @@
-import type { ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
-export declare const CURSOR_AGENT_TOOL_POLICY = "all";
-export declare const CURSOR_AGENT_TOOL_MAX_ITERATIONS = 24;
-export declare const CURSOR_BRIDGE_SCRUB_PREFIXES: readonly ["BRIDGE_", "MODEL_", "E2E_", "CURSOR_UPSTREAM"];
-export declare const CURSOR_IDE_SCRUB_PREFIXES: readonly ["BRIDGE_", "MODEL_", "E2E_", "CURSOR_UPSTREAM", "CK_"];
-export type CursorBridgeModelEnvInput = {
-    gatewayUrl: string;
-    modelName: string;
-    providerModel?: string;
-    apiKey?: string;
-    upstreamBaseUrl?: string;
-    contextTokenLimit?: number;
-};
-export type CursorBridgeEnvInput = CursorBridgeModelEnvInput & {
-    port: number;
-    baseEnv?: NodeJS.ProcessEnv;
-    caCertPath?: string;
-    routeInventory?: boolean;
-    models?: readonly CursorBridgeModelDescriptor[];
-};
-export type CursorBridgeModelDescriptor = {
-    id: string;
-    displayName?: string;
-    reasoning?: ModelReasoningCapabilities;
-};
-export type CursorIdeModelsInput = {
-    gatewayUrl: string;
-    modelLabel: string;
-    models?: readonly CursorBridgeModelDescriptor[];
-    apiKey?: string;
-    contextTokenLimit?: number;
-};
-export declare function cursorBridgeBaseUrl(gatewayUrl: string): string;
-export declare function cursorBridgeModelEnv(input: CursorBridgeModelEnvInput): Record<string, string>;
-export declare function cursorBridgeEnv(input: CursorBridgeEnvInput): Record<string, string>;
-export declare function cursorIdeEnv(input: CursorIdeModelsInput & {
-    repo: string;
-    caCertPath?: string;
-}): Record<string, string>;
-export declare function cursorIdeModelsJson(input: CursorIdeModelsInput, legacyArray?: boolean): string;

package/dist/bridge-config.js

@@ -1,95 +0,0 @@
-import { normalizeApiBaseUrl, scrubBridgeEnv } from "@velum-labs/routekit-runtime";
-const DEFAULT_CONTEXT_TOKEN_LIMIT = 128000;
-const DEFAULT_LOCAL_API_KEY = "local";
-const DEFAULT_UPSTREAM_BASE_URL = "https://api2.cursor.sh";
-export const CURSOR_AGENT_TOOL_POLICY = "all";
-export const CURSOR_AGENT_TOOL_MAX_ITERATIONS = 24;
-export const CURSOR_BRIDGE_SCRUB_PREFIXES = [
-    "BRIDGE_",
-    "MODEL_",
-    "E2E_",
-    "CURSOR_UPSTREAM"
-];
-export const CURSOR_IDE_SCRUB_PREFIXES = [...CURSOR_BRIDGE_SCRUB_PREFIXES, "CK_"];
-export function cursorBridgeBaseUrl(gatewayUrl) {
-    return normalizeApiBaseUrl(gatewayUrl);
-}
-export function cursorBridgeModelEnv(input) {
-    return {
-        CURSOR_UPSTREAM_BASE_URL: input.upstreamBaseUrl ?? DEFAULT_UPSTREAM_BASE_URL,
-        MODEL_BASE_URL: cursorBridgeBaseUrl(input.gatewayUrl),
-        MODEL_API_KEY: input.apiKey ?? DEFAULT_LOCAL_API_KEY,
-        MODEL_NAME: input.modelName,
-        MODEL_PROVIDER_MODEL: input.providerModel ?? input.modelName,
-        MODEL_CONTEXT_TOKEN_LIMIT: String(input.contextTokenLimit ?? DEFAULT_CONTEXT_TOKEN_LIMIT)
-    };
-}
-export function cursorBridgeEnv(input) {
-    const env = scrubBridgeEnv(input.baseEnv ?? process.env, CURSOR_BRIDGE_SCRUB_PREFIXES);
-    return {
-        ...env,
-        ...(input.caCertPath !== undefined
-            ? { NODE_EXTRA_CA_CERTS: env.NODE_EXTRA_CA_CERTS ?? input.caCertPath }
-            : {}),
-        BRIDGE_PORT: String(input.port),
-        BRIDGE_ROUTE_INVENTORY: input.routeInventory === false ? "false" : "true",
-        ...(input.models !== undefined && input.models.length > 1
-            ? {
-                BRIDGE_MODELS_JSON: cursorIdeModelsJson({
-                    gatewayUrl: input.gatewayUrl,
-                    modelLabel: input.modelName,
-                    models: input.models,
-                    ...(input.apiKey !== undefined ? { apiKey: input.apiKey } : {}),
-                    ...(input.contextTokenLimit !== undefined
-                        ? { contextTokenLimit: input.contextTokenLimit }
-                        : {})
-                }, true)
-            }
-            : {}),
-        ...cursorBridgeModelEnv(input)
-    };
-}
-export function cursorIdeEnv(input) {
-    const env = scrubBridgeEnv(process.env, CURSOR_IDE_SCRUB_PREFIXES);
-    return {
-        ...env,
-        CK_WORKSPACE_PATH: input.repo,
-        BRIDGE_MODELS_JSON: cursorIdeModelsJson(input, true),
-        ...cursorBridgeModelEnv({
-            gatewayUrl: input.gatewayUrl,
-            modelName: input.modelLabel,
-            providerModel: input.modelLabel,
-            ...(input.apiKey !== undefined ? { apiKey: input.apiKey } : {})
-        }),
-        ...(input.caCertPath !== undefined
-            ? { NODE_EXTRA_CA_CERTS: env.NODE_EXTRA_CA_CERTS ?? input.caCertPath }
-            : {})
-    };
-}
-export function cursorIdeModelsJson(input, legacyArray = false) {
-    const baseUrl = cursorBridgeBaseUrl(input.gatewayUrl);
-    const apiKey = input.apiKey ?? DEFAULT_LOCAL_API_KEY;
-    const contextTokenLimit = input.contextTokenLimit ?? DEFAULT_CONTEXT_TOKEN_LIMIT;
-    const supplied = input.models ?? [];
-    const byId = new Map(supplied.map((model) => [model.id, model]));
-    if (!byId.has(input.modelLabel)) {
-        byId.set(input.modelLabel, { id: input.modelLabel });
-    }
-    const models = [...byId.values()].map((model) => ({
-        id: model.id,
-        displayName: model.displayName ?? model.id,
-        providerModel: model.id,
-        baseUrl,
-        apiKey,
-        contextTokenLimit,
-        ...(model.reasoning !== undefined
-            ? { reasoning: model.reasoning }
-            : {})
-    }));
-    return JSON.stringify(legacyArray
-        ? models
-        : {
-            version: 2,
-            models
-        });
-}

package/dist/bridge.d.ts

@@ -1,18 +0,0 @@
-import type { ChildProcess } from "node:child_process";
-import type { CursorBridgeModelDescriptor } from "./bridge-config.js";
-/**
- * Start the Cursorkit bridge with its local-model backend pointed at the
- * configured gateway. Resolves once it is listening.
- */
-export declare function startCursorBridge(input: {
-    gatewayUrl: string;
-    modelLabel: string;
-    models?: readonly CursorBridgeModelDescriptor[];
-    logFile?: string;
-    caCertPath?: string;
-    apiKey?: string;
-    log: (line: string) => void;
-}): Promise<{
-    child: ChildProcess;
-    port: number;
-}>;

package/dist/bridge.js

@@ -1,37 +0,0 @@
-import { reservePort, spawnLogged, terminate, waitForOutput } from "@velum-labs/routekit-runtime";
-import { cursorBridgeEnv } from "./bridge-config.js";
-import { resolveCursorkitCli } from "./cursorkit-path.js";
-/**
- * Start the Cursorkit bridge with its local-model backend pointed at the
- * configured gateway. Resolves once it is listening.
- */
-export async function startCursorBridge(input) {
-    // Hold the port until the bridge is about to bind it, so a concurrent picker
-    // cannot steal it in the gap between choosing and spawning.
-    const reservation = await reservePort();
-    const port = reservation.port;
-    const env = cursorBridgeEnv({
-        port,
-        gatewayUrl: input.gatewayUrl,
-        modelName: input.modelLabel,
-        providerModel: input.modelLabel,
-        ...(input.apiKey !== undefined ? { apiKey: input.apiKey } : {}),
-        ...(input.models !== undefined ? { models: input.models } : {}),
-        ...(input.caCertPath !== undefined ? { caCertPath: input.caCertPath } : {})
-    });
-    const { serveCli } = resolveCursorkitCli();
-    await reservation.release();
-    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(`Cursorkit bridge listening on http://127.0.0.1:${port}`);
-    return { child: proc.child, port };
-}

package/dist/cursorkit-path.d.ts

@@ -1,5 +0,0 @@
-export type CursorkitCli = {
-    serveCli: string;
-    harnessCli: string;
-};
-export declare function resolveCursorkitCli(): CursorkitCli;

package/dist/cursorkit-path.js

@@ -1,10 +0,0 @@
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-const require = createRequire(import.meta.url);
-export function resolveCursorkitCli() {
-    const override = process.env.ROUTEKIT_CURSORKIT_SERVE_CLI;
-    const serveCli = override !== undefined && override.length > 0
-        ? override
-        : require.resolve("@velum-labs/cursorkit");
-    return { serveCli, harnessCli: join(dirname(serveCli), "testing", "cli.js") };
-}

package/dist/test/bridge-config.test.d.ts

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

package/dist/test/bridge-config.test.js

@@ -1,57 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { cursorBridgeEnv, cursorIdeModelsJson } from "../bridge-config.js";
-test("cursorIdeModelsJson preserves opaque model order and removes duplicates", () => {
-    const parsed = JSON.parse(cursorIdeModelsJson({
-        gatewayUrl: "http://127.0.0.1:9999",
-        modelLabel: "opaque-primary",
-        models: [
-            {
-                id: "opaque-primary",
-                reasoning: {
-                    status: "supported",
-                    efforts: [{ id: "quick" }, { id: "deep" }],
-                    provenance: "provider"
-                }
-            },
-            { id: "opaque-secondary" },
-            { id: "native-model" },
-            { id: "opaque-secondary" }
-        ]
-    }));
-    assert.equal(parsed.version, 2);
-    assert.deepEqual(parsed.models.map((entry) => entry.id), ["opaque-primary", "opaque-secondary", "native-model"]);
-    assert.ok(parsed.models.every((entry) => entry.baseUrl.startsWith("http://127.0.0.1:9999")));
-    assert.ok(parsed.models.every((entry) => entry.providerModel === entry.id));
-    assert.deepEqual(parsed.models[0]?.reasoning?.efforts, [
-        { id: "quick" },
-        { id: "deep" }
-    ]);
-});
-test("cursorBridgeEnv seeds BRIDGE_MODELS_JSON for multiple opaque models", () => {
-    const env = cursorBridgeEnv({
-        port: 4321,
-        gatewayUrl: "http://127.0.0.1:9999",
-        modelName: "opaque-primary",
-        models: [
-            { id: "opaque-primary" },
-            { id: "opaque-secondary" },
-            { id: "native-model" }
-        ],
-        baseEnv: {}
-    });
-    // MODEL_NAME stays the session default for single-model bridges.
-    assert.equal(env.MODEL_NAME, "opaque-primary");
-    const models = JSON.parse(env.BRIDGE_MODELS_JSON ?? "[]");
-    assert.deepEqual(models.map((entry) => entry.id), ["opaque-primary", "opaque-secondary", "native-model"]);
-});
-test("cursorBridgeEnv omits BRIDGE_MODELS_JSON for one model", () => {
-    const env = cursorBridgeEnv({
-        port: 4321,
-        gatewayUrl: "http://127.0.0.1:9999",
-        modelName: "opaque-primary",
-        models: [{ id: "opaque-primary" }],
-        baseEnv: {}
-    });
-    assert.equal(env.BRIDGE_MODELS_JSON, undefined);
-});

package/dist/test/ide-launch.test.d.ts

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

package/dist/test/ide-launch.test.js

@@ -1,218 +0,0 @@
-import assert from "node:assert/strict";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { test } from "node:test";
-import { launchCursor } from "../launch.js";
-/**
- * A stub for `cursorkit ck`: records the env + cwd it was launched with, prints
- * the readiness line `launchCursorIde` waits for, then idles until SIGTERM so
- * the disposer-driven teardown path is exercised.
- */
-function writeCkStub(path, outFile) {
-    writeFileSync(path, [
-        "const fs = require('node:fs');",
-        `fs.writeFileSync(${JSON.stringify(outFile)}, JSON.stringify({`,
-        "  argv: process.argv.slice(2),",
-        "  cwd: process.cwd(),",
-        "  workspace: process.env.CK_WORKSPACE_PATH,",
-        "  models: process.env.BRIDGE_MODELS_JSON,",
-        "  modelBaseUrl: process.env.MODEL_BASE_URL,",
-        "  modelApiKey: process.env.MODEL_API_KEY,",
-        "  caCerts: process.env.NODE_EXTRA_CA_CERTS,",
-        "  leakedBridge: process.env.BRIDGE_PORT",
-        "}));",
-        "process.stdout.write('ck ready\\n');",
-        "const timer = setInterval(() => {}, 1000);",
-        "process.on('SIGTERM', () => { clearInterval(timer); process.exit(0); });"
-    ].join("\n"));
-}
-test("launchCursor CLI forwards only supported Cursor auth inputs", async () => {
-    const workdir = mkdtempSync(join(tmpdir(), "cursor-cli-auth-"));
-    const bridgeStub = join(workdir, "bridge.cjs");
-    const agentStub = join(workdir, "cursor-agent");
-    const recorder = join(workdir, "record-agent.cjs");
-    const observations = join(workdir, "agent-observations.ndjson");
-    writeFileSync(bridgeStub, [
-        "process.stdout.write('bridge listening\\n');",
-        "const timer = setInterval(() => {}, 1000);",
-        "process.on('SIGTERM', () => { clearInterval(timer); process.exit(0); });"
-    ].join("\n"));
-    writeFileSync(recorder, [
-        'const { appendFileSync } = require("node:fs");',
-        `appendFileSync(${JSON.stringify(observations)}, JSON.stringify({`,
-        "  auth: process.env.CURSOR_API_KEY ?? null,",
-        "  config: process.env.CURSOR_CONFIG_DIR ?? null,",
-        "  unrelated: process.env.UNRELATED_SECRET ?? null",
-        "}) + '\\n');"
-    ].join("\n"));
-    writeFileSync(agentStub, `#!/bin/sh\nexec "${process.execPath}" "${recorder}" "$@"\n`);
-    chmodSync(agentStub, 0o755);
-    const previous = {
-        path: process.env.PATH,
-        serveCli: process.env.ROUTEKIT_CURSORKIT_SERVE_CLI,
-        apiKey: process.env.CURSOR_API_KEY,
-        configDirectory: process.env.CURSOR_CONFIG_DIR,
-        unrelated: process.env.UNRELATED_SECRET
-    };
-    process.env.PATH = `${workdir}:${process.env.PATH ?? ""}`;
-    process.env.ROUTEKIT_CURSORKIT_SERVE_CLI = bridgeStub;
-    process.env.UNRELATED_SECRET = "must-not-leak";
-    try {
-        const stagedConfig = join(workdir, "staged-config");
-        for (const [, apiKey, configDirectory, expected] of [
-            [
-                "env-key",
-                "cursor-test-key",
-                undefined,
-                { auth: "cursor-test-key", config: null }
-            ],
-            [
-                "staged-config",
-                undefined,
-                stagedConfig,
-                { auth: null, config: stagedConfig }
-            ],
-            ["absent", undefined, undefined, { auth: null, config: null }]
-        ]) {
-            if (apiKey === undefined)
-                delete process.env.CURSOR_API_KEY;
-            else
-                process.env.CURSOR_API_KEY = apiKey;
-            if (configDirectory === undefined)
-                delete process.env.CURSOR_CONFIG_DIR;
-            else
-                process.env.CURSOR_CONFIG_DIR = configDirectory;
-            const disposers = [];
-            const ctx = {
-                spec: {
-                    gatewayUrl: "http://127.0.0.1:9999",
-                    defaultModel: "primary",
-                    models: [{ id: "primary" }],
-                    args: [],
-                    cwd: workdir
-                },
-                log: () => undefined,
-                prepareForPassthrough: () => undefined,
-                registerPort: (_name, port) => `http://127.0.0.1:${port}`,
-                unregisterPort: () => undefined,
-                registerDisposer: (dispose) => disposers.push(dispose)
-            };
-            try {
-                assert.equal(await launchCursor(ctx), 0);
-                const observed = readFileSync(observations, "utf8")
-                    .trim()
-                    .split("\n")
-                    .map((line) => JSON.parse(line))
-                    .at(-1);
-                assert.deepEqual(observed, {
-                    ...expected,
-                    unrelated: null
-                });
-            }
-            finally {
-                for (const dispose of disposers)
-                    await dispose();
-            }
-        }
-    }
-    finally {
-        for (const [name, value] of [
-            ["PATH", previous.path],
-            ["ROUTEKIT_CURSORKIT_SERVE_CLI", previous.serveCli],
-            ["CURSOR_API_KEY", previous.apiKey],
-            ["CURSOR_CONFIG_DIR", previous.configDirectory],
-            ["UNRELATED_SECRET", previous.unrelated]
-        ]) {
-            if (value === undefined)
-                delete process.env[name];
-            else
-                process.env[name] = value;
-        }
-        rmSync(workdir, { recursive: true, force: true });
-    }
-});
-test("launchCursor --ide drives the desktop launcher with the gateway-wired model", async () => {
-    const workdir = mkdtempSync(join(tmpdir(), "cursor-ide-"));
-    const repo = mkdtempSync(join(tmpdir(), "cursor-ide-repo-"));
-    const logsDir = join(workdir, "logs");
-    const stub = join(workdir, "ck-stub.cjs");
-    const outFile = join(workdir, "ck-invocation.json");
-    writeCkStub(stub, outFile);
-    const previousOverride = process.env.ROUTEKIT_CURSORKIT_SERVE_CLI;
-    // A leftover BRIDGE_* var that must be scrubbed before spawning the launcher.
-    const previousLeak = process.env.BRIDGE_PORT;
-    process.env.ROUTEKIT_CURSORKIT_SERVE_CLI = stub;
-    process.env.BRIDGE_PORT = "59999";
-    const disposers = [];
-    const logs = [];
-    const ctx = {
-        spec: {
-            gatewayUrl: "http://127.0.0.1:9999",
-            defaultModel: "primary",
-            models: [{ id: "primary", aliases: ["primary-alias"] }, { id: "gpt" }, { id: "sonnet" }],
-            args: [],
-            cwd: repo,
-            tls: { caCertPath: "/tmp/portless-ca.pem" },
-            logsDir,
-            ide: true
-        },
-        log: (line) => logs.push(line),
-        prepareForPassthrough: () => undefined,
-        registerPort: (_name, port) => `http://127.0.0.1:${port}`,
-        unregisterPort: () => undefined,
-        registerDisposer: (dispose) => disposers.push(dispose)
-    };
-    try {
-        const launched = launchCursor(ctx);
-        try {
-            // Wait until the launcher is fully up: a registered disposer means it
-            // passed the readiness gate and recorded its teardown (the stub wrote its
-            // invocation file before announcing readiness).
-            for (let i = 0; i < 200 && disposers.length === 0; i++) {
-                await delay(50);
-            }
-            assert.equal(disposers.length, 1);
-            assert.ok(existsSync(outFile), "the ck stub should have been invoked");
-            const invocation = JSON.parse(readFileSync(outFile, "utf8"));
-            assert.deepEqual(invocation.argv, ["ck"]);
-            // Opens the user's repo but keeps state out of it (cwd is the scratch dir).
-            assert.equal(invocation.workspace, repo);
-            assert.notEqual(invocation.cwd, repo);
-            assert.equal(invocation.modelBaseUrl, "http://127.0.0.1:9999/v1");
-            assert.equal(invocation.modelApiKey, "local");
-            assert.equal(invocation.caCerts, "/tmp/portless-ca.pem");
-            // A parent's BRIDGE_* env is scrubbed; only our seeded models flow through.
-            assert.equal(invocation.leakedBridge, undefined);
-            const models = JSON.parse(invocation.models ?? "[]");
-            assert.deepEqual(models.map((entry) => entry.id), ["primary", "primary-alias", "gpt", "sonnet"]);
-            assert.ok(models.every((entry) => entry.baseUrl === "http://127.0.0.1:9999/v1"));
-        }
-        finally {
-            // Always tear the desktop launcher down so the launch promise resolves and
-            // the test process can exit even when an assertion fails.
-            for (const dispose of disposers) {
-                await dispose();
-            }
-            const code = await launched;
-            assert.equal(code, 0);
-        }
-    }
-    finally {
-        if (previousOverride === undefined) {
-            delete process.env.ROUTEKIT_CURSORKIT_SERVE_CLI;
-        }
-        else {
-            process.env.ROUTEKIT_CURSORKIT_SERVE_CLI = previousOverride;
-        }
-        if (previousLeak === undefined) {
-            delete process.env.BRIDGE_PORT;
-        }
-        else {
-            process.env.BRIDGE_PORT = previousLeak;
-        }
-        rmSync(workdir, { recursive: true, force: true });
-        rmSync(repo, { recursive: true, force: true });
-    }
-});