@velum-labs/routekit-tool-cursor 0.9.0

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

@@ -0,0 +1,57 @@
+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/driver.test.d.ts

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

package/dist/test/driver.test.js

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { driverContractSuite } from "@velum-labs/routekit-harness-core/testing";
+import { createCursorDriver } from "../driver.js";
+// The fake ACP agent lives beside this test in src (tsc does not copy .mjs),
+// so resolve it relative to the compiled test's location back into src.
+const here = dirname(fileURLToPath(import.meta.url));
+const FAKE_AGENT = join(here, "..", "..", "src", "test", "fake-acp-agent.mjs");
+const driver = createCursorDriver();
+// A wrapper executable so the driver's appended `acp` arg lands after the fake
+// agent script: `<wrapper> acp` -> `node <fake-agent> acp`. `--version` is
+// answered directly so the probe sees an installed CLI.
+let cachedWrapper;
+function wrapperCommand() {
+    if (cachedWrapper !== undefined)
+        return cachedWrapper;
+    const dir = mkdtempSync(join(tmpdir(), "cursor-driver-"));
+    const wrapper = join(dir, "cursor-agent-fake");
+    writeFileSync(wrapper, `#!/bin/sh\nif [ "$1" = "--version" ]; then echo "cursor-agent 2026.1.1"; exit 0; fi\nexec "${process.execPath}" "${FAKE_AGENT}" "$@"\n`);
+    chmodSync(wrapper, 0o755);
+    cachedWrapper = wrapper;
+    return wrapper;
+}
+driverContractSuite({
+    name: "cursor driver",
+    createInstance: async () => driver.createInstance(driver.configSchema.parse({ command: wrapperCommand() })),
+    startOptions: () => ({ cwd: here }),
+    supportsResume: true,
+    turnTimeoutMs: 15_000
+});
+test("cursor driver maps ACP session updates into canonical events", async () => {
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: wrapperCommand() }));
+    try {
+        const session = await instance.startSession({ cwd: here });
+        const events = [];
+        for await (const event of session.sendTurn({ prompt: "hello cursor" })) {
+            events.push(event);
+        }
+        const types = events.map((event) => event.type);
+        assert.ok(types.includes("turn.started"));
+        const delta = events.find((event) => event.type === "content.delta");
+        assert.ok(delta && delta.text.includes("hello cursor"));
+        const completed = events.find((event) => event.type === "turn.completed");
+        assert.equal(completed?.endReason, "completed");
+        assert.ok(events.every((event) => event.kind === "cursor"));
+        assert.ok(session.resumeCursor()?.data);
+        await session.stop();
+    }
+    finally {
+        await instance.dispose();
+    }
+});
+test("cursor driver forwards effort through the ACP config option", async () => {
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: wrapperCommand() }));
+    try {
+        const session = await instance.startSession({
+            cwd: here,
+            reasoning: { mode: "effort", effort: "deep" }
+        });
+        for await (const _event of session.sendTurn({ prompt: "reason about this" })) {
+            // Drain.
+        }
+        await session.stop();
+    }
+    finally {
+        await instance.dispose();
+    }
+});
+test("cursor driver auto-approves under the automation policy", async () => {
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: wrapperCommand() }));
+    try {
+        // Automation policy (autoApprove:all) is the default: exec approval is granted
+        // server-side without a surfaced request, so the turn completes.
+        const session = await instance.startSession({ cwd: here });
+        const events = [];
+        for await (const event of session.sendTurn({ prompt: "please APPROVE and continue" })) {
+            events.push(event);
+        }
+        assert.ok(!events.some((event) => event.type === "request.opened"));
+        const completed = events.find((event) => event.type === "turn.completed");
+        assert.equal(completed?.endReason, "completed");
+        await session.stop();
+    }
+    finally {
+        await instance.dispose();
+    }
+});
+test("cursor driver surfaces approvals under autoApprove none and resolves them", async () => {
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: wrapperCommand() }));
+    try {
+        const session = await instance.startSession({
+            cwd: here,
+            approvalPolicy: { autoApprove: "none" }
+        });
+        const events = [];
+        for await (const event of session.sendTurn({ prompt: "please APPROVE and continue" })) {
+            events.push(event);
+            if (event.type === "request.opened") {
+                assert.equal(event.requestType, "exec_command_approval");
+                await session.respondToRequest(event.requestId, "accept");
+            }
+        }
+        assert.ok(events.some((event) => event.type === "request.opened"));
+        assert.ok(events.some((event) => event.type === "request.resolved"));
+        const completed = events.find((event) => event.type === "turn.completed");
+        assert.equal(completed?.endReason, "completed");
+        await session.stop();
+    }
+    finally {
+        await instance.dispose();
+    }
+});

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

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

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

@@ -0,0 +1,218 @@
+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 });
+    }
+});

package/dist/test/subagents.test.d.ts

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

package/dist/test/subagents.test.js

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import { CURSOR_AGENTS_DIRNAME, cursorSubagentMarkdown, scaffoldCursorSubagents } from "../subagents.js";
+const PROFILES = [
+    {
+        id: "reviewer",
+        model: "opaque-model",
+        description: "Review changes.",
+        instructions: "Return findings."
+    },
+    {
+        id: "implementer",
+        model: "other-model",
+        description: "Implement changes.",
+        instructions: "Make the requested change."
+    }
+];
+const tmpRoots = [];
+function freshRepo() {
+    const dir = mkdtempSync(join(tmpdir(), "cursor-subagents-"));
+    tmpRoots.push(dir);
+    return dir;
+}
+after(() => {
+    for (const dir of tmpRoots)
+        rmSync(dir, { recursive: true, force: true });
+});
+test("cursorSubagentMarkdown serializes a generic profile", () => {
+    const md = cursorSubagentMarkdown(PROFILES[0]);
+    assert.match(md, /name: reviewer/);
+    assert.match(md, /model: opaque-model/);
+    assert.match(md, /Return findings/);
+});
+test("scaffoldCursorSubagents writes profiles and never overwrites", () => {
+    const repo = freshRepo();
+    assert.equal(scaffoldCursorSubagents(repo, PROFILES).length, 2);
+    const path = join(repo, CURSOR_AGENTS_DIRNAME, "reviewer.md");
+    assert.ok(existsSync(path));
+    writeFileSync(path, "USER EDIT\n");
+    assert.deepEqual(scaffoldCursorSubagents(repo, PROFILES), []);
+    assert.equal(readFileSync(path, "utf8"), "USER EDIT\n");
+});
+test("scaffoldCursorSubagents is best-effort", () => {
+    const repo = freshRepo();
+    writeFileSync(join(repo, ".cursor"), "not a directory");
+    const lines = [];
+    assert.deepEqual(scaffoldCursorSubagents(repo, PROFILES, (line) => lines.push(line)), []);
+    assert.equal(lines.length, 1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@velum-labs/routekit-tool-cursor",
+  "private": false,
+  "version": "0.9.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/tool-cursor"
+  },
+  "description": "Product-neutral Cursor launcher, bridge serializer, and canonical ACP driver.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "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.9.0",
+    "@velum-labs/routekit-runtime": "0.9.0",
+    "@velum-labs/routekit-harness-core": "0.9.0",
+    "@velum-labs/routekit-tools": "0.9.0"
+  },
+  "keywords": [
+    "llm",
+    "coding-agent",
+    "cursor",
+    "harness",
+    "adapter"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "node --test \"dist/test/*.test.js\""
+  }
+}