@velum-labs/cursorkit 0.1.0

package/dist/src/desktop.js

@@ -0,0 +1,167 @@
+import { X509Certificate } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import { generateTlsMaterial } from "./certs.js";
+export const DESKTOP_HOSTNAME = "api2.cursor.sh";
+export const DESKTOP_HOSTNAMES = [
+    DESKTOP_HOSTNAME,
+    "api3.cursor.sh",
+    "agent.api5.cursor.sh",
+    "agentn.api5.cursor.sh",
+    "agentn.global.api5.cursor.sh",
+];
+export const DESKTOP_CERT_DIR = path.join(".cursor-rpc", "certs");
+export const DESKTOP_CERT_PATH = path.join(DESKTOP_CERT_DIR, `${DESKTOP_HOSTNAME}.crt`);
+export const DESKTOP_KEY_PATH = path.join(DESKTOP_CERT_DIR, `${DESKTOP_HOSTNAME}.key`);
+export function desktopEnv(env) {
+    const next = { ...env };
+    next.BRIDGE_DESKTOP_MODE ??= "true";
+    next.BRIDGE_USE_TLS ??= "true";
+    next.BRIDGE_TLS_HOSTNAMES ??= `${DESKTOP_HOSTNAMES.join(",")},localhost,127.0.0.1,::1`;
+    next.BRIDGE_PUBLIC_ORIGIN ??= `https://${DESKTOP_HOSTNAME}`;
+    next.CURSOR_UPSTREAM_BASE_URL ??= `https://${DESKTOP_HOSTNAME}`;
+    if (next.BRIDGE_CERT_PATH === undefined &&
+        next.BRIDGE_KEY_PATH === undefined &&
+        fs.existsSync(DESKTOP_CERT_PATH) &&
+        fs.existsSync(DESKTOP_KEY_PATH)) {
+        next.BRIDGE_CERT_PATH = DESKTOP_CERT_PATH;
+        next.BRIDGE_KEY_PATH = DESKTOP_KEY_PATH;
+    }
+    return next;
+}
+export function desktopTrustCommand(certPath = DESKTOP_CERT_PATH) {
+    return [
+        "sudo",
+        "security",
+        "add-trusted-cert",
+        "-d",
+        "-r",
+        "trustRoot",
+        "-k",
+        "/Library/Keychains/System.keychain",
+        certPath,
+    ];
+}
+export async function writeDesktopCertificate() {
+    if (fs.existsSync(DESKTOP_CERT_PATH) &&
+        fs.existsSync(DESKTOP_KEY_PATH) &&
+        desktopCertificateCoversHostnames(DESKTOP_CERT_PATH, [...DESKTOP_HOSTNAMES])) {
+        return {
+            certPath: DESKTOP_CERT_PATH,
+            keyPath: DESKTOP_KEY_PATH,
+            created: false,
+        };
+    }
+    fs.mkdirSync(DESKTOP_CERT_DIR, { recursive: true });
+    const tls = await generateTlsMaterial([
+        ...DESKTOP_HOSTNAMES,
+        "localhost",
+        "127.0.0.1",
+        "::1",
+    ]);
+    fs.writeFileSync(DESKTOP_CERT_PATH, tls.cert, { mode: 0o644 });
+    fs.writeFileSync(DESKTOP_KEY_PATH, tls.key, { mode: 0o600 });
+    return {
+        certPath: DESKTOP_CERT_PATH,
+        keyPath: DESKTOP_KEY_PATH,
+        created: true,
+    };
+}
+export function desktopCertificateStatus(config) {
+    if (config.certPath === undefined || config.keyPath === undefined) {
+        return "not configured; run cursorkit desktop-cert and set BRIDGE_CERT_PATH/BRIDGE_KEY_PATH";
+    }
+    if (!fs.existsSync(config.certPath) || !fs.existsSync(config.keyPath)) {
+        return "missing cert or key path";
+    }
+    try {
+        const cert = new X509Certificate(fs.readFileSync(config.certPath));
+        const altNames = cert.subjectAltName ?? "";
+        const missing = DESKTOP_HOSTNAMES.filter((hostname) => !altNames.includes(`DNS:${hostname}`));
+        return missing.length === 0
+            ? `covers ${DESKTOP_HOSTNAMES.join(", ")}`
+            : `missing ${missing.join(", ")}`;
+    }
+    catch (error) {
+        return `invalid certificate: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+function desktopCertificateCoversHostnames(certPath, hostnames) {
+    try {
+        const cert = new X509Certificate(fs.readFileSync(certPath));
+        const altNames = cert.subjectAltName ?? "";
+        return hostnames.every((hostname) => altNames.includes(`DNS:${hostname}`));
+    }
+    catch {
+        return false;
+    }
+}
+export async function desktopDnsStatus(config) {
+    try {
+        const result = await lookup(DESKTOP_HOSTNAME);
+        const localRedirect = result.address === "127.0.0.1" || result.address === "::1";
+        if (localRedirect && config.upstreamConnectHost === undefined) {
+            return `${DESKTOP_HOSTNAME} -> ${result.address}; set CURSOR_UPSTREAM_CONNECT_HOST to avoid proxy loops`;
+        }
+        return `${DESKTOP_HOSTNAME} -> ${result.address}`;
+    }
+    catch (error) {
+        return `lookup failed: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export async function upstreamReachabilityStatus(config) {
+    if (config.upstreamBaseUrl === undefined) {
+        return "not configured";
+    }
+    const upstreamUrl = new URL(config.upstreamBaseUrl);
+    const client = upstreamUrl.protocol === "https:" ? https : http;
+    const host = config.upstreamConnectHost ?? upstreamUrl.hostname;
+    const port = config.upstreamConnectPort ??
+        (upstreamUrl.port.length > 0
+            ? Number(upstreamUrl.port)
+            : upstreamUrl.protocol === "https:"
+                ? 443
+                : 80);
+    return new Promise((resolve) => {
+        const request = client.request({
+            method: "HEAD",
+            hostname: host,
+            port,
+            path: "/",
+            headers: { host: upstreamUrl.host },
+            servername: upstreamUrl.protocol === "https:" ? upstreamUrl.hostname : undefined,
+            timeout: 5_000,
+        }, (response) => {
+            response.resume();
+            resolve(`HTTP ${response.statusCode ?? 0}`);
+        });
+        request.on("timeout", () => {
+            request.destroy(new Error("timeout"));
+        });
+        request.on("error", (error) => {
+            resolve(error.message);
+        });
+        request.end();
+    });
+}
+export async function localModelBackendStatus(config) {
+    const firstModel = config.models[0];
+    if (firstModel === undefined) {
+        return "no local models configured";
+    }
+    const modelsUrl = new URL(`${firstModel.baseUrl.replace(/\/$/, "")}/models`);
+    try {
+        const response = await fetch(modelsUrl, {
+            headers: firstModel.apiKey
+                ? { authorization: `Bearer ${firstModel.apiKey}` }
+                : {},
+        });
+        return `${modelsUrl.toString()} -> HTTP ${response.status}`;
+    }
+    catch (error) {
+        return `${modelsUrl.toString()} -> ${error instanceof Error ? error.message : String(error)}`;
+    }
+}

package/dist/src/desktopConnectProxy.d.ts

@@ -0,0 +1,26 @@
+import net from "node:net";
+export interface DesktopConnectProxyOptions {
+    host: string;
+    port: number;
+    bridgeHost: string;
+    bridgePort: number;
+    logPath?: string;
+    passthrough?: boolean;
+    cursorHostnames?: readonly string[];
+    headerTimeoutMs?: number;
+}
+export interface DesktopConnectProxy {
+    server: net.Server;
+    close(): Promise<void>;
+}
+export interface DesktopConnectProxyEvent {
+    message: "desktop connect proxy";
+    event: "listening" | "connect" | "http-rejected" | "passthrough-blocked" | "header-timeout" | "upstream-error" | "client-closed";
+    host?: string;
+    port?: number;
+    targetHost?: string;
+    targetPort?: number;
+    cursorBackend?: boolean;
+    error?: string;
+}
+export declare function startDesktopConnectProxy(options: DesktopConnectProxyOptions): Promise<DesktopConnectProxy>;

package/dist/src/desktopConnectProxy.js

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import net from "node:net";
+import { DESKTOP_HOSTNAMES } from "./desktop.js";
+const CONNECT_LINE_PATTERN = /^CONNECT\s+([^\s]+)\s+HTTP\/\d(?:\.\d)?$/i;
+const DEFAULT_HEADER_TIMEOUT_MS = 5_000;
+const MAX_CONNECT_HEADER_BYTES = 32 * 1024;
+export async function startDesktopConnectProxy(options) {
+    const cursorHostnames = new Set(options.cursorHostnames ?? DESKTOP_HOSTNAMES);
+    const passthrough = options.passthrough ?? true;
+    const activeSockets = new Set();
+    const server = net.createServer((client) => {
+        activeSockets.add(client);
+        client.once("close", () => activeSockets.delete(client));
+        handleClient(client, options, cursorHostnames, passthrough, activeSockets);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            server.off("error", reject);
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "listening",
+                host: options.host,
+                port: options.port,
+                targetHost: options.bridgeHost,
+                targetPort: options.bridgePort,
+            });
+            resolve();
+        });
+    });
+    return {
+        server,
+        close: () => new Promise((resolve, reject) => {
+            for (const socket of activeSockets) {
+                socket.destroy();
+            }
+            server.close((error) => {
+                if (error !== undefined) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+    };
+}
+function handleClient(client, options, cursorHostnames, passthrough, activeSockets) {
+    let upstream;
+    let buffered = Buffer.alloc(0);
+    let tunnelEstablished = false;
+    const headerTimer = setTimeout(() => {
+        logProxyEvent(options.logPath, {
+            message: "desktop connect proxy",
+            event: "header-timeout",
+        });
+        client.end("HTTP/1.1 408 Request Timeout\r\nConnection: close\r\n\r\n");
+    }, options.headerTimeoutMs ?? DEFAULT_HEADER_TIMEOUT_MS);
+    const cleanup = () => {
+        clearTimeout(headerTimer);
+        if (upstream !== undefined) {
+            upstream.destroy();
+        }
+        if (tunnelEstablished) {
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "client-closed",
+            });
+        }
+    };
+    client.once("close", cleanup);
+    client.on("error", () => {
+        upstream?.destroy();
+    });
+    client.on("data", function onData(chunk) {
+        buffered = Buffer.concat([buffered, chunk]);
+        if (buffered.length > MAX_CONNECT_HEADER_BYTES) {
+            clearTimeout(headerTimer);
+            client.off("data", onData);
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "http-rejected",
+                error: "connect header exceeded maximum size",
+            });
+            client.end("HTTP/1.1 431 Request Header Fields Too Large\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        const endOfHeaders = buffered.indexOf("\r\n\r\n");
+        if (endOfHeaders === -1) {
+            return;
+        }
+        clearTimeout(headerTimer);
+        client.off("data", onData);
+        const headerBytes = buffered.subarray(0, endOfHeaders + 4);
+        const firstLine = headerBytes.toString("utf8").split("\r\n")[0] ?? "";
+        const match = CONNECT_LINE_PATTERN.exec(firstLine);
+        if (match === null) {
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "http-rejected",
+            });
+            client.end("HTTP/1.1 405 Method Not Allowed\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        const destination = parseConnectDestination(match[1]);
+        const cursorBackend = cursorHostnames.has(destination.host);
+        if (!cursorBackend && !passthrough) {
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "passthrough-blocked",
+                host: destination.host,
+                port: destination.port,
+            });
+            client.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        const targetHost = cursorBackend ? options.bridgeHost : destination.host;
+        const targetPort = cursorBackend ? options.bridgePort : destination.port;
+        logProxyEvent(options.logPath, {
+            message: "desktop connect proxy",
+            event: "connect",
+            host: destination.host,
+            port: destination.port,
+            targetHost,
+            targetPort,
+            cursorBackend,
+        });
+        upstream = net.connect(targetPort, targetHost, () => {
+            if (upstream !== undefined) {
+                activeSockets.add(upstream);
+                upstream.once("close", () => activeSockets.delete(upstream));
+            }
+            tunnelEstablished = true;
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            const remaining = buffered.subarray(endOfHeaders + 4);
+            if (remaining.length > 0) {
+                upstream?.write(remaining);
+            }
+            if (upstream !== undefined) {
+                client.pipe(upstream);
+                upstream.pipe(client);
+            }
+        });
+        upstream.on("error", (error) => {
+            logProxyEvent(options.logPath, {
+                message: "desktop connect proxy",
+                event: "upstream-error",
+                host: destination.host,
+                port: destination.port,
+                targetHost,
+                targetPort,
+                cursorBackend,
+                error: error.message,
+            });
+            client.destroy(error);
+        });
+    });
+}
+function parseConnectDestination(value) {
+    if (value.startsWith("[")) {
+        const closeBracket = value.indexOf("]");
+        if (closeBracket !== -1) {
+            const host = value.slice(1, closeBracket);
+            const port = Number(value.slice(closeBracket + 2)) || 443;
+            return { host, port };
+        }
+    }
+    const [host, portText] = value.split(":");
+    return { host: host ?? value, port: Number(portText ?? "443") || 443 };
+}
+function logProxyEvent(logPath, event) {
+    if (logPath === undefined) {
+        return;
+    }
+    fs.appendFileSync(logPath, `${JSON.stringify({ ts: new Date().toISOString(), ...event })}\n`);
+}

package/dist/src/extensions/index.d.ts

@@ -0,0 +1,2 @@
+export type { CursorExtension, ExtensionContext, MiddlewareRegistry, RequestMiddleware, ResponseMiddleware, RouteInterceptor, RouteRegistry, } from "./types.js";
+export { createExtensionManager } from "./registry.js";

package/dist/src/extensions/index.js

@@ -0,0 +1 @@
+export { createExtensionManager } from "./registry.js";

package/dist/src/extensions/registry.d.ts

@@ -0,0 +1,8 @@
+import type { Logger } from "../logger.js";
+import type { ModelRegistry } from "../models/registry.js";
+import type { CursorExtension, ExtensionContext } from "./types.js";
+export interface ExtensionManager {
+    context: ExtensionContext;
+    load(extension: CursorExtension): Promise<void>;
+}
+export declare function createExtensionManager(models: ModelRegistry, logger: Logger): ExtensionManager;

package/dist/src/extensions/registry.js

@@ -0,0 +1,52 @@
+class DefaultRouteRegistry {
+    routes = new Map();
+    register(route) {
+        if (this.routes.has(route.path)) {
+            throw new Error(`Route already registered: ${route.path}`);
+        }
+        this.routes.set(route.path, route);
+    }
+    list() {
+        return Array.from(this.routes.values());
+    }
+}
+class DefaultMiddlewareRegistry {
+    middleware = [];
+    register(middleware) {
+        this.middleware.push(middleware);
+    }
+    list() {
+        return [...this.middleware];
+    }
+}
+export function createExtensionManager(models, logger) {
+    const context = {
+        models,
+        routes: new DefaultRouteRegistry(),
+        middleware: new DefaultMiddlewareRegistry(),
+        logger,
+    };
+    return {
+        context,
+        async load(extension) {
+            if (extension.manifest !== undefined) {
+                validateManifest(extension.name, extension.manifest);
+            }
+            logger.info("loading trusted local extension", {
+                extension: extension.name,
+                apiVersion: extension.manifest?.apiVersion ?? "implicit-local",
+                trusted: extension.manifest?.trusted ?? "local",
+                permissions: extension.manifest?.permissions ?? ["legacy-full-local"],
+            });
+            await extension.setup(context);
+        },
+    };
+}
+function validateManifest(name, manifest) {
+    if (manifest.apiVersion !== "cursor-rpc/v1") {
+        throw new Error(`Extension ${name} declares unsupported apiVersion`);
+    }
+    if (manifest.trusted !== "local") {
+        throw new Error(`Extension ${name} must declare trusted=local`);
+    }
+}

package/dist/src/extensions/types.d.ts

@@ -0,0 +1,42 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Logger } from "../logger.js";
+import type { ModelRegistry } from "../models/registry.js";
+export interface CursorExtension {
+    name: string;
+    manifest?: CursorExtensionManifest;
+    setup(context: ExtensionContext): void | Promise<void>;
+}
+export interface CursorExtensionManifest {
+    apiVersion: "cursor-rpc/v1";
+    trusted: "local";
+    permissions: CursorExtensionPermission[];
+}
+export type CursorExtensionPermission = "models:register" | "routes:register" | "middleware:register";
+export interface ExtensionContext {
+    models: ModelRegistry;
+    routes: RouteRegistry;
+    middleware: MiddlewareRegistry;
+    logger: Logger;
+}
+export interface RouteRegistry {
+    register(route: RouteInterceptor): void;
+    list(): RouteInterceptor[];
+}
+export interface RouteInterceptor {
+    path: string;
+    bodyAccess: "metadata-only" | "consume";
+    handle(request: IncomingMessage, response: ServerResponse): Promise<boolean>;
+}
+export interface MiddlewareRegistry {
+    register(middleware: RequestMiddleware | ResponseMiddleware): void;
+    list(): Array<RequestMiddleware | ResponseMiddleware>;
+}
+export interface RequestMiddleware {
+    kind: "request";
+    bodyAccess: "metadata-only" | "consume";
+    run(request: IncomingMessage): Promise<void> | void;
+}
+export interface ResponseMiddleware {
+    kind: "response";
+    run(response: ServerResponse): Promise<void> | void;
+}

package/dist/src/extensions/types.js

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

package/dist/src/fixtures/modelFusion.d.ts

@@ -0,0 +1,103 @@
+export declare const MODEL_FUSION_SCHEMA_BUNDLE_HASH = "sha256:955da2d6891c88d4c40746a8206439e2dae2efc1e7ffefca015e84d4ce265671";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ModelFusionStatus = "pending" | "running" | "succeeded" | "failed" | "canceled" | "requires_action" | "skipped" | "unsupported";
+export type ModelFusionSideEffects = "none" | "read_only" | "writes_workspace" | "network" | "tool_execution" | "unknown";
+export type ModelFusionCapabilityStatus = "supported" | "unsupported" | "degraded" | "unknown";
+export type ModelFusionHarnessKind = "generic" | "cursor" | "claude_code" | "codex" | "openai_responses";
+export type ModelFusionArtifactKind = "transcript" | "patch" | "screenshot" | "log" | "metrics" | "worktree" | "other";
+export type ModelFusionRedactionStatus = "synthetic" | "redacted" | "raw";
+export type ContractMetadata<S extends string> = {
+    schema: S;
+    schema_version: "v1";
+    schema_bundle_hash: string;
+    producer: string;
+    producer_version: string;
+    producer_git_sha: string;
+    created_at: string;
+};
+export type ArtifactRef = {
+    artifact_id: string;
+    kind: ModelFusionArtifactKind;
+    uri?: string;
+    hash: string;
+    redaction_status?: ModelFusionRedactionStatus;
+};
+export type ModelFusionDiagnostic = {
+    kind: "capability_missing";
+    message: string;
+    retryable: boolean;
+    capability?: string;
+    status?: ModelFusionCapabilityStatus;
+    requested_status?: ModelFusionCapabilityStatus;
+};
+export type HarnessRunRequestV1 = ContractMetadata<"harness-run-request.v1"> & {
+    request_id: string;
+    harness_kind: ModelFusionHarnessKind;
+    source_repo: string;
+    base_git_sha: string;
+    prompt: string;
+    prompt_hash: string;
+    allowed_tools?: string[];
+    side_effects: ModelFusionSideEffects;
+    requested_capabilities: Record<string, ModelFusionCapabilityStatus>;
+    metadata?: Record<string, JsonValue>;
+};
+export type HarnessRunResultV1 = ContractMetadata<"harness-run-result.v1"> & {
+    result_id: string;
+    request_id: string;
+    harness_kind: ModelFusionHarnessKind;
+    status: ModelFusionStatus;
+    candidate_ids: string[];
+    output_summary?: string;
+    artifacts?: ArtifactRef[];
+    capabilities: Record<string, ModelFusionCapabilityStatus>;
+    requested_model?: string;
+    observed_model?: string;
+    model_id?: string;
+    endpoint_id?: string;
+    diagnostics?: ModelFusionDiagnostic[];
+    started_at: string;
+    finished_at?: string;
+    errors?: Array<{
+        kind: string;
+        message: string;
+        retryable: boolean;
+    }>;
+    metadata?: Record<string, JsonValue>;
+};
+export type CursorRunRequestV1 = ContractMetadata<"cursor-run-request.v1"> & {
+    cursor_run_id: string;
+    harness_request_id: string;
+    workspace_path: string;
+    prompt: string;
+    prompt_hash: string;
+    requested_model?: string;
+    allowed_tools?: string[];
+    side_effects: ModelFusionSideEffects;
+    requested_capabilities: Record<string, ModelFusionCapabilityStatus>;
+};
+export type CursorRunResultV1 = ContractMetadata<"cursor-run-result.v1"> & {
+    cursor_run_id: string;
+    harness_request_id: string;
+    mapped_harness_result_id?: string;
+    status: ModelFusionStatus;
+    output_summary: string;
+    transcript_artifact?: ArtifactRef;
+    artifacts?: ArtifactRef[];
+    capabilities: Record<string, ModelFusionCapabilityStatus>;
+    requested_model?: string;
+    observed_model?: string;
+    model_id?: string;
+    endpoint_id?: string;
+    diagnostics?: ModelFusionDiagnostic[];
+    raw_hash: string;
+    redacted_hash: string;
+};
+export declare function sha256Prefixed(value: string | Uint8Array): string;
+export declare function cursorRunResultToHarnessRunResult(cursor: CursorRunResultV1): HarnessRunResultV1;
+export declare function assertHarnessRunRequestV1(value: unknown): asserts value is HarnessRunRequestV1;
+export declare function assertHarnessRunResultV1(value: unknown): asserts value is HarnessRunResultV1;
+export declare function assertCursorRunRequestV1(value: unknown): asserts value is CursorRunRequestV1;
+export declare function assertCursorRunResultV1(value: unknown): asserts value is CursorRunResultV1;