@velum-labs/cursorkit 0.1.0

package/dist/src/services/models.js

@@ -0,0 +1,216 @@
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { encodeEnvelope, encodeEndStream } from "../connectEnvelope.js";
+import { AgentV1_ApiKeyCredentialsSchema, AgentV1_GetDefaultModelForCliResponseSchema, AgentV1_GetUsableModelsResponseSchema, AgentV1_ModelDetailsSchema, AgentV1_RequestedModel_ModelParameterValueSchema, AvailableModelsResponse_DegradationStatus, AvailableModelsResponse_AvailableModelSchema, AvailableModelsResponse_ModelVariantConfigSchema, AvailableModelsResponse_TooltipDataSchema, AvailableModelsResponse_ModelVendorId, AvailableModelsResponse_ModelVendorSchema, AvailableModelsResponseSchema, GetDefaultModelResponseSchema, ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, ModelParameterDefinition_EnumParameterDefinitionSchema, ModelParameterDefinition_ModelParameterTypeSchema, ModelParameterDefinitionSchema, } from "../gen/aiserver/v1/aiserver_pb.js";
+export function mergeAvailableModels(upstreamPayload, models) {
+    const upstream = upstreamPayload === undefined
+        ? create(AvailableModelsResponseSchema)
+        : fromBinary(AvailableModelsResponseSchema, upstreamPayload);
+    const modelNames = new Set(upstream.modelNames);
+    const upstreamModels = [...upstream.models];
+    for (const model of models.list()) {
+        if (modelNames.has(model.id)) {
+            continue;
+        }
+        modelNames.add(model.id);
+        upstreamModels.push(create(AvailableModelsResponse_AvailableModelSchema, {
+            name: model.id,
+            defaultOn: false,
+            isChatOnly: false,
+            supportsAgent: true,
+            degradationStatus: AvailableModelsResponse_DegradationStatus.AVAILABLE_MODELS_RESPONSE_DEGRADATION_STATUS_DEGRADATION_STATUS_UNSPECIFIED,
+            supportsThinking: false,
+            supportsImages: false,
+            supportsAutoContext: false,
+            supportsMaxMode: true,
+            supportsNonMaxMode: true,
+            supportsPlanMode: true,
+            supportsSandboxing: false,
+            supportsCmdK: false,
+            cloudAgentEffortModes: [],
+            clientDisplayName: model.displayName,
+            serverModelName: model.id,
+            inputboxShortModelName: model.displayName,
+            contextTokenLimit: model.contextTokenLimit,
+            isUserAdded: true,
+            parameterDefinitions: localParameterDefinitions(),
+            legacySlugs: [model.id],
+            idAliases: uniqueStrings([model.id, model.displayName]),
+            namedModelSectionIndex: 1,
+            visibleInRoutedModelView: true,
+            vendorName: "local",
+            vendor: create(AvailableModelsResponse_ModelVendorSchema, {
+                id: AvailableModelsResponse_ModelVendorId.AVAILABLE_MODELS_RESPONSE_MODEL_VENDOR_ID_MODEL_VENDOR_ID_UNSPECIFIED,
+                displayName: "Local",
+            }),
+            variants: [
+                localVariantConfig(model, false),
+                localVariantConfig(model, true),
+            ],
+        }));
+    }
+    return Buffer.from(toBinary(AvailableModelsResponseSchema, {
+        ...upstream,
+        modelNames: Array.from(modelNames),
+        models: upstreamModels,
+    }));
+}
+export function mergeUsableModels(upstreamPayload, models) {
+    const upstream = upstreamPayload === undefined
+        ? create(AgentV1_GetUsableModelsResponseSchema)
+        : fromBinary(AgentV1_GetUsableModelsResponseSchema, upstreamPayload);
+    const modelIds = new Set(upstream.models.map((model) => model.modelId));
+    const mergedModels = [...upstream.models];
+    for (const model of models.list()) {
+        if (modelIds.has(model.id)) {
+            continue;
+        }
+        modelIds.add(model.id);
+        mergedModels.push(localCliModelDetails(model));
+    }
+    return Buffer.from(toBinary(AgentV1_GetUsableModelsResponseSchema, {
+        ...upstream,
+        models: mergedModels,
+    }));
+}
+export function mergeDefaultModelForCli(upstreamPayload, models) {
+    if (upstreamPayload !== undefined) {
+        const upstream = fromBinary(AgentV1_GetDefaultModelForCliResponseSchema, upstreamPayload);
+        if (upstream.model !== undefined) {
+            return Buffer.from(toBinary(AgentV1_GetDefaultModelForCliResponseSchema, upstream));
+        }
+    }
+    const firstLocalModel = models.list()[0];
+    const model = firstLocalModel === undefined
+        ? undefined
+        : localCliModelDetails(firstLocalModel);
+    return Buffer.from(toBinary(AgentV1_GetDefaultModelForCliResponseSchema, create(AgentV1_GetDefaultModelForCliResponseSchema, {
+        model,
+    })));
+}
+export function mergeDefaultModel(upstreamPayload, models) {
+    const upstream = upstreamPayload === undefined
+        ? create(GetDefaultModelResponseSchema)
+        : fromBinary(GetDefaultModelResponseSchema, upstreamPayload);
+    const firstLocalModel = models.list()[0];
+    if (firstLocalModel === undefined) {
+        return Buffer.from(toBinary(GetDefaultModelResponseSchema, upstream));
+    }
+    return Buffer.from(toBinary(GetDefaultModelResponseSchema, create(GetDefaultModelResponseSchema, {
+        ...upstream,
+        model: firstLocalModel.id,
+        thinkingModel: firstLocalModel.id,
+        maxMode: true,
+    })));
+}
+export function writeAvailableModelsResponse(response, payload, logger, format) {
+    writeModelResponse(response, payload, logger, "served available models", format);
+}
+export function writeModelResponse(response, payload, logger, message, format) {
+    response.statusCode = 200;
+    if (format === "connect") {
+        response.setHeader("content-type", "application/connect+proto");
+        response.write(encodeEnvelope(payload));
+        response.end(encodeEndStream());
+    }
+    else {
+        response.setHeader("content-type", "application/proto");
+        response.end(payload);
+    }
+    logger.info(message, { bytes: payload.length });
+}
+function localCliModelDetails(model) {
+    return create(AgentV1_ModelDetailsSchema, {
+        modelId: model.id,
+        displayModelId: model.id,
+        displayName: model.displayName,
+        displayNameShort: model.displayName,
+        aliases: uniqueStrings([model.id, model.displayName]),
+        maxMode: false,
+        apiKeyCredentials: create(AgentV1_ApiKeyCredentialsSchema, {
+            apiKey: model.apiKey,
+            baseUrl: model.baseUrl,
+        }),
+    });
+}
+function localVariantConfig(model, isMaxMode) {
+    return create(AvailableModelsResponse_ModelVariantConfigSchema, {
+        displayName: model.displayName,
+        displayNameOutsidePicker: model.displayName,
+        isMaxMode,
+        isDefaultMaxConfig: isMaxMode,
+        isDefaultNonMaxConfig: !isMaxMode,
+        parameterValues: localParameterValues(isMaxMode),
+        tooltipData: create(AvailableModelsResponse_TooltipDataSchema, {
+            markdownContent: `**${model.displayName}**<br />Local OpenAI-compatible model.`,
+        }),
+        variantStringRepresentation: localVariantString(model.id, isMaxMode),
+        legacySlug: model.id,
+    });
+}
+function localVariantString(modelId, isMaxMode) {
+    const context = isMaxMode ? "1m" : "272k";
+    return `${modelId}[context=${context},reasoning=medium,fast=false]`;
+}
+function localParameterDefinitions() {
+    return [
+        create(ModelParameterDefinitionSchema, {
+            id: "context",
+            name: "Context",
+            markdownTooltip: "Context size the model has available.",
+            parameterType: create(ModelParameterDefinition_ModelParameterTypeSchema, {
+                enumParameter: create(ModelParameterDefinition_EnumParameterDefinitionSchema, {
+                    values: [
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "272k", displayName: "272K" }),
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "1m", displayName: "1M" }),
+                    ],
+                }),
+            }),
+        }),
+        create(ModelParameterDefinitionSchema, {
+            id: "reasoning",
+            name: "Reasoning",
+            markdownTooltip: "Reasoning effort the model uses to generate its response.",
+            parameterType: create(ModelParameterDefinition_ModelParameterTypeSchema, {
+                enumParameter: create(ModelParameterDefinition_EnumParameterDefinitionSchema, {
+                    values: [
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "none", displayName: "None" }),
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "low", displayName: "Low" }),
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "medium", displayName: "Medium" }),
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "high", displayName: "High" }),
+                        create(ModelParameterDefinition_EnumParameterDefinition_EnumParameterValueSchema, { value: "extra-high", displayName: "Extra High" }),
+                    ],
+                }),
+            }),
+            isCycleableByHotkey: true,
+        }),
+        create(ModelParameterDefinitionSchema, {
+            id: "fast",
+            name: "Fast",
+            markdownTooltip: "Use the provider's fast lane when supported.",
+            parameterType: create(ModelParameterDefinition_ModelParameterTypeSchema, {
+                booleanParameter: {
+                    values: [{ value: "false" }, { value: "true", displayName: "Fast" }],
+                },
+            }),
+        }),
+    ];
+}
+function localParameterValues(isMaxMode) {
+    return [
+        create(AgentV1_RequestedModel_ModelParameterValueSchema, {
+            id: "context",
+            value: isMaxMode ? "1m" : "272k",
+        }),
+        create(AgentV1_RequestedModel_ModelParameterValueSchema, {
+            id: "reasoning",
+            value: "medium",
+        }),
+        create(AgentV1_RequestedModel_ModelParameterValueSchema, {
+            id: "fast",
+            value: "false",
+        }),
+    ];
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values.filter((value) => value.length > 0)));
+}

package/dist/src/services/serverConfig.d.ts

@@ -0,0 +1,2 @@
+export declare function rewriteServerConfigAgentUrls(upstreamPayload: Buffer, bridgeOrigin: string): Buffer;
+export declare function buildLocalServerConfig(bridgeOrigin: string): Buffer;

package/dist/src/services/serverConfig.js

@@ -0,0 +1,19 @@
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { AgentUrlConfigSchema, GetServerConfigResponseSchema, Http2Config, } from "../gen/aiserver/v1/aiserver_pb.js";
+export function rewriteServerConfigAgentUrls(upstreamPayload, bridgeOrigin) {
+    const upstream = fromBinary(GetServerConfigResponseSchema, upstreamPayload);
+    return encodeServerConfig(upstream, bridgeOrigin);
+}
+export function buildLocalServerConfig(bridgeOrigin) {
+    return encodeServerConfig(create(GetServerConfigResponseSchema), bridgeOrigin);
+}
+function encodeServerConfig(upstream, bridgeOrigin) {
+    return Buffer.from(toBinary(GetServerConfigResponseSchema, {
+        ...upstream,
+        http2Config: Http2Config.HTTP2_CONFIG_FORCE_ALL_DISABLED,
+        agentUrlConfig: create(AgentUrlConfigSchema, {
+            agentUrl: bridgeOrigin,
+            agentnUrl: bridgeOrigin,
+        }),
+    }));
+}

package/dist/src/testing/artifacts.d.ts

@@ -0,0 +1,14 @@
+import type { ArtifactWriter, ScenarioResult } from "./types.js";
+export declare class FileArtifactStore implements ArtifactWriter {
+    readonly rootDir: string;
+    constructor(rootDir: string);
+    pathFor(name: string): string;
+    writeText(name: string, contents: string): string;
+    writeJson(name: string, contents: unknown): string;
+}
+export declare function createRunDirectory(options: {
+    cwd: string;
+    artifactsDir?: string;
+    now?: Date;
+}): string;
+export declare function writeRunSummary(artifacts: ArtifactWriter, results: ScenarioResult[]): Record<string, string>;

package/dist/src/testing/artifacts.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+export class FileArtifactStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+        fs.mkdirSync(rootDir, { recursive: true });
+    }
+    pathFor(name) {
+        return path.join(this.rootDir, sanitizeArtifactName(name));
+    }
+    writeText(name, contents) {
+        const artifactPath = this.pathFor(name);
+        fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+        fs.writeFileSync(artifactPath, contents);
+        return artifactPath;
+    }
+    writeJson(name, contents) {
+        return this.writeText(name, `${JSON.stringify(contents, null, 2)}\n`);
+    }
+}
+export function createRunDirectory(options) {
+    if (options.artifactsDir !== undefined) {
+        return path.resolve(options.cwd, options.artifactsDir);
+    }
+    const timestamp = (options.now ?? new Date())
+        .toISOString()
+        .replace(/[:.]/g, "-");
+    return path.join(options.cwd, ".cursor-rpc", "test-runs", timestamp);
+}
+export function writeRunSummary(artifacts, results) {
+    return {
+        json: artifacts.writeJson("summary.json", {
+            status: results.some((result) => result.status === "failed")
+                ? "failed"
+                : "passed",
+            results,
+        }),
+        markdown: artifacts.writeText("summary.md", renderMarkdownSummary(results)),
+        junit: artifacts.writeText("junit.xml", renderJunit(results)),
+    };
+}
+function renderMarkdownSummary(results) {
+    const lines = ["# Harness Summary", ""];
+    for (const result of results) {
+        lines.push(`- ${result.status.toUpperCase()} ${result.id}: ${result.message}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderJunit(results) {
+    const failures = results.filter((result) => result.status === "failed");
+    const skipped = results.filter((result) => result.status === "skipped");
+    const testcases = results
+        .map((result) => {
+        const seconds = (result.durationMs / 1000).toFixed(3);
+        if (result.status === "failed") {
+            return `  <testcase classname="cursor-rpc.harness" name="${escapeXml(result.id)}" time="${seconds}"><failure message="${escapeXml(result.message)}">${escapeXml(result.failureCode ?? "command_failed")}</failure></testcase>`;
+        }
+        if (result.status === "skipped") {
+            return `  <testcase classname="cursor-rpc.harness" name="${escapeXml(result.id)}" time="${seconds}"><skipped message="${escapeXml(result.message)}" /></testcase>`;
+        }
+        return `  <testcase classname="cursor-rpc.harness" name="${escapeXml(result.id)}" time="${seconds}" />`;
+    })
+        .join("\n");
+    return [
+        `<?xml version="1.0" encoding="UTF-8"?>`,
+        `<testsuite name="cursor-rpc-harness" tests="${results.length}" failures="${failures.length}" skipped="${skipped.length}">`,
+        testcases,
+        `</testsuite>`,
+        "",
+    ].join("\n");
+}
+function sanitizeArtifactName(name) {
+    return name
+        .split("/")
+        .map((part) => {
+        if (part === "." || part === ".." || part.length === 0) {
+            return "_";
+        }
+        return part.replace(/[^A-Za-z0-9._-]/g, "_");
+    })
+        .join("/");
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}

package/dist/src/testing/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import type { HarnessOptions } from "./types.js";
+export declare function parseHarnessArgs(argv: string[], env?: NodeJS.ProcessEnv, cwd?: string): HarnessOptions;
+export declare function runHarnessCli(argv?: string[]): Promise<number>;

package/dist/src/testing/cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { FileArtifactStore, createRunDirectory, writeRunSummary, } from "./artifacts.js";
+import { ChildProcessRunner } from "./processRunner.js";
+import { ScenarioRunner } from "./runner.js";
+import { createScenarios } from "./scenarios.js";
+const HELP = `cursorkit test harness
+
+Usage:
+  pnpm test:harness -- --suite static
+  pnpm test:harness -- --suite traffic
+  pnpm test:harness -- --suite acp
+  pnpm test:harness -- --suite local-backend --base-url http://127.0.0.1:8080/v1 --model mlx-community/Qwen3.5-4B-8bit
+  pnpm test:harness -- --suite desktop --use-default-profile --timeout-ms 30000
+
+Options:
+  --suite <name>              Suite to run; repeat or comma-separate. Values: all, static, bridge-protocol, local-backend, cursor-agent, cursor-agent-traffic, traffic, acp, cli, desktop, desktop-route
+  --base-url <url>            OpenAI-compatible base URL
+  --model <id>                Model ID for local backend/desktop scenarios
+  --provider-model <id>       OpenAI-compatible backend model ID when different from --model
+  --display-name <name>       Cursor-facing display name
+  --api-key <key>             API key for local backend requests
+  --timeout-ms <ms>           Per-scenario timeout
+  --use-default-profile       Desktop: reuse signed-in Cursor profile
+  --include-experimental      Include ACP/UI experimental suites with all
+  --artifacts-dir <path>      Artifact output directory
+`;
+export function parseHarnessArgs(argv, env = process.env, cwd = process.cwd()) {
+    const suites = [];
+    let baseUrl = env.MODEL_BASE_URL ?? "http://127.0.0.1:8080/v1";
+    let model = env.MODEL_NAME ?? "mlx-community/Qwen3.5-4B-8bit";
+    let providerModel = env.MODEL_PROVIDER_MODEL ?? model;
+    let providerModelExplicit = env.MODEL_PROVIDER_MODEL !== undefined;
+    let displayName = env.MODEL_DISPLAY_NAME ?? "local-qwen";
+    let apiKey = env.MODEL_API_KEY ?? "local";
+    let timeoutMs = 30_000;
+    let useDefaultProfile = false;
+    let includeExperimental = false;
+    let artifactsDir;
+    const args = argv.slice(2);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "--":
+                break;
+            case "--suite": {
+                const value = requiredValue(args, index, arg);
+                suites.push(...parseSuites(value));
+                index += 1;
+                break;
+            }
+            case "--base-url":
+                baseUrl = requiredValue(args, index, arg);
+                index += 1;
+                break;
+            case "--model":
+                model = requiredValue(args, index, arg);
+                if (!providerModelExplicit) {
+                    providerModel = model;
+                }
+                index += 1;
+                break;
+            case "--provider-model":
+                providerModel = requiredValue(args, index, arg);
+                providerModelExplicit = true;
+                index += 1;
+                break;
+            case "--display-name":
+                displayName = requiredValue(args, index, arg);
+                index += 1;
+                break;
+            case "--api-key":
+                apiKey = requiredValue(args, index, arg);
+                index += 1;
+                break;
+            case "--timeout-ms":
+                timeoutMs = parsePositiveInteger(requiredValue(args, index, arg), arg);
+                index += 1;
+                break;
+            case "--use-default-profile":
+                useDefaultProfile = true;
+                break;
+            case "--include-experimental":
+                includeExperimental = true;
+                break;
+            case "--artifacts-dir":
+                artifactsDir = requiredValue(args, index, arg);
+                index += 1;
+                break;
+            case "--help":
+            case "-h":
+                throw new HelpRequested();
+            default:
+                throw new Error(`Unknown harness argument: ${arg}\n\n${HELP}`);
+        }
+    }
+    return {
+        suites: suites.length > 0 ? suites : ["all"],
+        cwd,
+        artifactsDir,
+        baseUrl,
+        model,
+        providerModel,
+        displayName,
+        apiKey,
+        timeoutMs,
+        useDefaultProfile,
+        includeExperimental,
+        env,
+    };
+}
+export async function runHarnessCli(argv = process.argv) {
+    let options;
+    try {
+        options = parseHarnessArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof HelpRequested) {
+            console.log(HELP);
+            return 0;
+        }
+        throw error;
+    }
+    const runDir = createRunDirectory({
+        cwd: options.cwd,
+        artifactsDir: options.artifactsDir,
+    });
+    const artifacts = new FileArtifactStore(runDir);
+    const processRunner = new ChildProcessRunner(options.cwd, artifacts);
+    const runner = new ScenarioRunner(createScenarios(), artifacts, processRunner);
+    const results = await runner.run(options);
+    const summaryPaths = writeRunSummary(artifacts, results);
+    printSummary(results, summaryPaths.json);
+    return results.some((result) => result.status === "failed") ? 1 : 0;
+}
+class HelpRequested extends Error {
+}
+function parseSuites(value) {
+    return value
+        .split(",")
+        .map((suite) => suite.trim())
+        .filter((suite) => suite.length > 0)
+        .map((suite) => {
+        if (isHarnessSuiteInput(suite)) {
+            return suite;
+        }
+        throw new Error(`Unknown suite: ${suite}`);
+    });
+}
+function isHarnessSuiteInput(value) {
+    return [
+        "all",
+        "acp",
+        "cli",
+        "desktop",
+        "static",
+        "bridge-protocol",
+        "local-backend",
+        "cursor-agent",
+        "cursor-agent-traffic",
+        "cursor-agent-acp-experimental",
+        "desktop-route",
+        "desktop-ui-experimental",
+        "traffic",
+    ].includes(value);
+}
+function requiredValue(args, index, name) {
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${name} requires a value`);
+    }
+    return value;
+}
+function parsePositiveInteger(value, name) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function printSummary(results, summaryPath) {
+    console.log("Harness Summary");
+    for (const result of results) {
+        console.log(`${result.status.toUpperCase()} ${result.id}: ${result.message}`);
+    }
+    console.log(`Artifacts: ${path.dirname(summaryPath)}`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runHarnessCli().then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/src/testing/localBackend.d.ts

@@ -0,0 +1,24 @@
+import type { FailureCode } from "./types.js";
+export interface LocalBackendProbeOptions {
+    baseUrl: string;
+    model: string;
+    apiKey: string;
+    timeoutMs: number;
+    checkToolCalls?: boolean;
+}
+export interface LocalBackendProbeReport {
+    ok: boolean;
+    failureCode?: FailureCode;
+    message: string;
+    modelsStatus?: number;
+    chatStatus?: number;
+    streamingChatStatus?: number;
+    toolChatStatus?: number;
+    models: string[];
+    selectedModelFound?: boolean;
+    nonStreamingSupported?: boolean;
+    streamingSupported?: boolean;
+    toolCallsSupported?: boolean;
+    completionPreview?: string;
+}
+export declare function probeLocalBackend(options: LocalBackendProbeOptions): Promise<LocalBackendProbeReport>;