@velum-labs/cursorkit 0.1.0

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { loadTlsMaterial } from "./certs.js";
+import { desktopCertificateStatus, desktopDnsStatus, desktopEnv, desktopTrustCommand, localModelBackendStatus, upstreamReachabilityStatus, writeDesktopCertificate, } from "./desktop.js";
+import { createLogger } from "./logger.js";
+import { assertCursorRunRequestV1, assertCursorRunResultV1, assertHarnessRunRequestV1, assertHarnessRunResultV1, } from "./fixtures/modelFusion.js";
+import { listProtoFiles, loadCursorProto, resolveProtoDirectory, } from "./proto.js";
+import { createBridgeRuntime, startServer } from "./server.js";
+const HELP = `cursorkit
+
+Usage:
+  cursorkit serve            Start the local bridge
+  cursorkit doctor           Check local configuration and proto availability
+  cursorkit desktop-cert     Generate local TLS material for Cursor desktop proxying
+  cursorkit desktop-proxy    Start the bridge with Cursor desktop proxy defaults
+  cursorkit desktop-doctor   Check Cursor desktop proxy prerequisites
+  cursorkit capture          Print capture-mode guidance
+  cursorkit fixtures         Validate committed fixture metadata
+  cursorkit --help           Show this help
+
+Environment:
+  BRIDGE_HOST=127.0.0.1
+  BRIDGE_PORT=9443
+  CURSOR_UPSTREAM_BASE_URL=https://example.cursor-backend.local
+  MODEL_BASE_URL=http://localhost:8080/v1
+  MODEL_NAME=local-model
+`;
+async function main(argv) {
+    const command = parseCommand(argv);
+    if (command === "help") {
+        console.log(HELP);
+        return;
+    }
+    const config = loadConfig(command === "desktop-proxy" || command === "desktop-doctor"
+        ? desktopEnv(process.env)
+        : process.env);
+    const logger = createLogger(config.logLevel);
+    switch (command) {
+        case "serve": {
+            const runtime = await createBridgeRuntime(config, logger);
+            installGracefulShutdown(await startServer(runtime), logger);
+            break;
+        }
+        case "doctor": {
+            await doctor(config);
+            break;
+        }
+        case "capture": {
+            capture(config);
+            break;
+        }
+        case "fixtures": {
+            validateFixtures(config.captureDir);
+            break;
+        }
+        case "desktop-cert": {
+            await desktopCert();
+            break;
+        }
+        case "desktop-proxy": {
+            const runtime = await createBridgeRuntime(config, logger);
+            installGracefulShutdown(await startServer(runtime), logger);
+            break;
+        }
+        case "desktop-doctor": {
+            await doctor(config);
+            await desktopDoctor(config);
+            break;
+        }
+        default: {
+            const exhaustive = command;
+            throw new Error(`Unhandled command: ${exhaustive}`);
+        }
+    }
+}
+function parseCommand(argv) {
+    const first = argv[2];
+    if (first === undefined ||
+        first === "--help" ||
+        first === "-h" ||
+        first === "help") {
+        return "help";
+    }
+    if (first === "serve" ||
+        first === "doctor" ||
+        first === "capture" ||
+        first === "fixtures" ||
+        first === "desktop-cert" ||
+        first === "desktop-proxy" ||
+        first === "desktop-doctor") {
+        return first;
+    }
+    throw new Error(`Unknown command: ${first}\n\n${HELP}`);
+}
+async function doctor(config) {
+    const checks = [];
+    const protoDir = resolveProtoDirectory();
+    checks.push(["proto directory", protoDir]);
+    checks.push(["proto files", String(listProtoFiles(protoDir).length)]);
+    const proto = await loadCursorProto();
+    checks.push([
+        "available models type",
+        proto.AvailableModelsResponse.fullName,
+    ]);
+    checks.push(["chat type", proto.StreamUnifiedChatRequestWithTools.fullName]);
+    checks.push(["bind", `${config.host}:${config.port}`]);
+    checks.push(["tls", config.useTls ? "enabled" : "disabled"]);
+    checks.push(["upstream", config.upstreamBaseUrl ?? "not configured"]);
+    checks.push([
+        "local models",
+        config.models.map((model) => model.id).join(", "),
+    ]);
+    checks.push([
+        "capture",
+        config.captureEnabled ? `enabled -> ${config.captureDir}` : "disabled",
+    ]);
+    checks.push(["fail-open", String(config.failOpen)]);
+    checks.push([
+        "auth",
+        config.authToken === undefined ? "disabled" : "enabled",
+    ]);
+    checks.push([
+        "non-localhost unsafe mode",
+        String(config.unsafeAllowNonLocalhost),
+    ]);
+    if (config.useTls) {
+        const tls = await loadTlsMaterial(config);
+        checks.push([
+            "tls material",
+            tls.generated
+                ? "generated self-signed dev certificate"
+                : "custom certificate",
+        ]);
+    }
+    for (const [name, value] of checks) {
+        console.log(`${name}: ${value}`);
+    }
+    if (config.upstreamBaseUrl === undefined) {
+        console.warn("warning: pass-through traffic needs CURSOR_UPSTREAM_BASE_URL");
+    }
+    if (config.captureEnabled) {
+        console.warn("warning: capture mode treats traffic as sensitive; sanitize before committing fixtures");
+    }
+    if (config.modelPayloadLogging === "full") {
+        console.warn("warning: BRIDGE_LOG_MODEL_PAYLOADS=full may log prompt and tool payloads; use only for local debugging");
+    }
+    if (config.unsafeAllowNonLocalhost) {
+        console.warn("warning: non-localhost unsafe mode exposes the bridge without built-in auth");
+    }
+}
+function installGracefulShutdown(server, logger) {
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown) {
+            logger.warn("forcing bridge shutdown", { signal });
+            process.exit(1);
+        }
+        shuttingDown = true;
+        logger.info("shutting down bridge", { signal });
+        const forceTimer = setTimeout(() => {
+            logger.error("bridge shutdown timed out", { signal });
+            process.exit(1);
+        }, 5_000);
+        server.close((error) => {
+            clearTimeout(forceTimer);
+            if (error !== undefined) {
+                logger.error("bridge shutdown failed", { error: error.message });
+                process.exitCode = 1;
+            }
+            process.exit();
+        });
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}
+async function desktopCert() {
+    const cert = await writeDesktopCertificate();
+    console.log(`cert: ${cert.certPath}`);
+    console.log(`key: ${cert.keyPath}`);
+    console.log("");
+    console.log("Manual macOS trust command:");
+    console.log(desktopTrustCommand(cert.certPath).join(" "));
+    console.log("");
+    console.log("Then start with:");
+    console.log(`BRIDGE_CERT_PATH=${cert.certPath} BRIDGE_KEY_PATH=${cert.keyPath} cursorkit desktop-proxy`);
+}
+async function desktopDoctor(config) {
+    const checks = [];
+    checks.push(["desktop mode", String(config.desktopMode)]);
+    checks.push(["public origin", config.publicOrigin ?? "not configured"]);
+    checks.push(["tls hostnames", config.tlsHostnames.join(", ")]);
+    checks.push(["route inventory", String(config.routeInventoryEnabled)]);
+    checks.push(["desktop upstream", config.upstreamBaseUrl ?? "not configured"]);
+    checks.push([
+        "desktop upstream connect",
+        config.upstreamConnectHost === undefined
+            ? "system DNS"
+            : `${config.upstreamConnectHost}${config.upstreamConnectPort === undefined ? "" : `:${config.upstreamConnectPort}`}`,
+    ]);
+    checks.push(["desktop cert", desktopCertificateStatus(config)]);
+    checks.push(["desktop dns", await desktopDnsStatus(config)]);
+    checks.push([
+        "upstream reachability",
+        await upstreamReachabilityStatus(config),
+    ]);
+    checks.push(["local model backend", await localModelBackendStatus(config)]);
+    for (const [name, value] of checks) {
+        console.log(`${name}: ${value}`);
+    }
+}
+function capture(config) {
+    console.log(`captureEnabled: ${config.captureEnabled}`);
+    console.log(`captureDir: ${config.captureDir}`);
+    console.log("Capture mode is explicit and sanitized fixture writing is required before committing data.");
+}
+function validateFixtures(captureDir) {
+    const modelFusionCount = validateModelFusionFixtures();
+    if (!fs.existsSync(captureDir)) {
+        console.log(`No fixture capture directory found at ${captureDir}`);
+        console.log(`Validated ${modelFusionCount} model-fusion fixture file(s)`);
+        return;
+    }
+    const files = fs
+        .readdirSync(captureDir)
+        .filter((file) => file.endsWith(".json"));
+    for (const file of files) {
+        const fullPath = path.join(captureDir, file);
+        const parsed = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+        if (parsed.redaction?.status !== "sanitized") {
+            throw new Error(`${fullPath} is missing redaction.status=sanitized`);
+        }
+    }
+    console.log(`Validated ${files.length} capture fixture file(s) and ${modelFusionCount} model-fusion fixture file(s)`);
+}
+function validateModelFusionFixtures() {
+    const root = path.resolve("fixtures", "model-fusion-contract");
+    if (!fs.existsSync(root))
+        return 0;
+    let count = 0;
+    const validators = {
+        "harness-run-request.v1": assertHarnessRunRequestV1,
+        "harness-run-result.v1": assertHarnessRunResultV1,
+        "cursor-run-request.v1": assertCursorRunRequestV1,
+        "cursor-run-result.v1": assertCursorRunResultV1,
+    };
+    for (const [schema, validate] of Object.entries(validators)) {
+        const schemaDir = path.join(root, schema);
+        if (!fs.existsSync(schemaDir))
+            continue;
+        for (const file of fs
+            .readdirSync(schemaDir)
+            .filter((item) => item.endsWith(".json"))) {
+            const fixturePath = path.join(schemaDir, file);
+            validate(JSON.parse(fs.readFileSync(fixturePath, "utf8")));
+            count++;
+        }
+    }
+    return count;
+}
+main(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/src/config.d.ts

@@ -0,0 +1,52 @@
+export interface BridgeConfig {
+    host: string;
+    port: number;
+    upstreamBaseUrl?: string;
+    upstreamConnectHost?: string;
+    upstreamConnectPort?: number;
+    desktopMode: boolean;
+    modelBaseUrl: string;
+    modelApiKey: string;
+    modelName: string;
+    models: LocalModelConfig[];
+    hardcodedResponse?: string;
+    certPath?: string;
+    keyPath?: string;
+    tlsHostnames: string[];
+    useTls: boolean;
+    publicOrigin?: string;
+    agentPublicOrigin?: string;
+    desktopAgentHttpPort?: number;
+    captureDir: string;
+    captureEnabled: boolean;
+    failOpen: boolean;
+    logLevel: LogLevel;
+    pluginPath?: string;
+    authToken?: string;
+    unsafeAllowNonLocalhost: boolean;
+    maxInterceptBodyBytes: number;
+    upstreamRequestTimeoutMs?: number;
+    agentRunSseWaitTimeoutMs?: number;
+    agentContextTimeoutMs?: number;
+    agentNativeContextEnabled: boolean;
+    toolResultTimeoutMs?: number;
+    extensionSetupTimeoutMs?: number;
+    routeInventoryEnabled: boolean;
+    modelPayloadLogging: ModelPayloadLogging;
+    agentToolPolicy: AgentToolPolicy;
+    agentToolMaxIterations: number;
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type ModelPayloadLogging = "summary" | "full";
+export type AgentToolPolicy = "safe" | "all";
+export interface LocalModelConfig {
+    id: string;
+    displayName: string;
+    providerModel: string;
+    baseUrl: string;
+    apiKey: string;
+    contextTokenLimit: number;
+    requestTimeoutMs?: number;
+    hardcodedResponse?: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): BridgeConfig;

package/dist/src/config.js

@@ -0,0 +1,210 @@
+export function loadConfig(env = process.env) {
+    const port = Number.parseInt(env.BRIDGE_PORT ?? "9443", 10);
+    if (!Number.isFinite(port) || port <= 0) {
+        throw new Error(`Invalid BRIDGE_PORT: ${env.BRIDGE_PORT}`);
+    }
+    const host = env.BRIDGE_HOST ?? "127.0.0.1";
+    const desktopMode = parseBoolean(env.BRIDGE_DESKTOP_MODE, false);
+    const unsafeAllowNonLocalhost = parseBoolean(env.BRIDGE_UNSAFE_ALLOW_NON_LOCALHOST, false);
+    const authToken = emptyToUndefined(env.BRIDGE_AUTH_TOKEN);
+    if (!unsafeAllowNonLocalhost &&
+        authToken === undefined &&
+        !isLocalhost(host)) {
+        throw new Error(`Refusing to bind bridge to non-localhost host ${host}. Set BRIDGE_AUTH_TOKEN or BRIDGE_UNSAFE_ALLOW_NON_LOCALHOST=true to override.`);
+    }
+    const modelBaseUrl = env.MODEL_BASE_URL ?? "http://localhost:8080/v1";
+    const modelApiKey = env.MODEL_API_KEY ?? "";
+    const modelName = env.MODEL_NAME ?? "local-model";
+    const providerModel = env.MODEL_PROVIDER_MODEL ?? modelName;
+    const hardcodedResponse = env.BRIDGE_HARDCODED_RESPONSE;
+    const models = parseModels(env, {
+        id: modelName,
+        displayName: modelName,
+        providerModel,
+        baseUrl: modelBaseUrl,
+        apiKey: modelApiKey,
+        contextTokenLimit: parseInteger(env.MODEL_CONTEXT_TOKEN_LIMIT, 128000),
+        requestTimeoutMs: parseOptionalPositiveInteger(env.MODEL_REQUEST_TIMEOUT_MS),
+        hardcodedResponse,
+    });
+    return {
+        host,
+        port,
+        upstreamBaseUrl: emptyToUndefined(env.CURSOR_UPSTREAM_BASE_URL) ??
+            (desktopMode ? "https://api2.cursor.sh" : undefined),
+        upstreamConnectHost: emptyToUndefined(env.CURSOR_UPSTREAM_CONNECT_HOST),
+        upstreamConnectPort: emptyToUndefined(env.CURSOR_UPSTREAM_CONNECT_PORT) === undefined
+            ? undefined
+            : parseInteger(env.CURSOR_UPSTREAM_CONNECT_PORT, 443),
+        desktopMode,
+        modelBaseUrl,
+        modelApiKey,
+        modelName,
+        models,
+        hardcodedResponse,
+        certPath: emptyToUndefined(env.BRIDGE_CERT_PATH),
+        keyPath: emptyToUndefined(env.BRIDGE_KEY_PATH),
+        tlsHostnames: parseCsv(env.BRIDGE_TLS_HOSTNAMES, desktopMode
+            ? [
+                "api2.cursor.sh",
+                "api3.cursor.sh",
+                "agent.api5.cursor.sh",
+                "agentn.api5.cursor.sh",
+                "agentn.global.api5.cursor.sh",
+                "localhost",
+                "127.0.0.1",
+                "::1",
+            ]
+            : ["localhost", "127.0.0.1", "::1"]),
+        useTls: parseBoolean(env.BRIDGE_USE_TLS, false),
+        publicOrigin: emptyToUndefined(env.BRIDGE_PUBLIC_ORIGIN) ??
+            (desktopMode ? "https://api2.cursor.sh" : undefined),
+        agentPublicOrigin: emptyToUndefined(env.BRIDGE_AGENT_PUBLIC_ORIGIN),
+        desktopAgentHttpPort: emptyToUndefined(env.BRIDGE_DESKTOP_AGENT_HTTP_PORT) === undefined
+            ? undefined
+            : parseInteger(env.BRIDGE_DESKTOP_AGENT_HTTP_PORT, 0),
+        captureDir: env.BRIDGE_CAPTURE_DIR ?? "fixtures/captures",
+        captureEnabled: parseBoolean(env.BRIDGE_CAPTURE_ENABLED, false),
+        failOpen: parseBoolean(env.BRIDGE_FAIL_OPEN, true),
+        logLevel: parseLogLevel(env.BRIDGE_LOG_LEVEL),
+        pluginPath: emptyToUndefined(env.BRIDGE_PLUGIN_PATH),
+        authToken,
+        unsafeAllowNonLocalhost,
+        maxInterceptBodyBytes: parseInteger(env.BRIDGE_MAX_INTERCEPT_BODY_BYTES, 50 * 1024 * 1024),
+        upstreamRequestTimeoutMs: parseOptionalPositiveInteger(env.BRIDGE_UPSTREAM_REQUEST_TIMEOUT_MS),
+        agentRunSseWaitTimeoutMs: parseOptionalPositiveInteger(env.BRIDGE_AGENT_RUN_SSE_WAIT_TIMEOUT_MS),
+        agentContextTimeoutMs: parseOptionalPositiveInteger(env.BRIDGE_AGENT_CONTEXT_TIMEOUT_MS),
+        agentNativeContextEnabled: parseBoolean(env.BRIDGE_AGENT_NATIVE_CONTEXT, true),
+        toolResultTimeoutMs: parseOptionalPositiveInteger(env.BRIDGE_AGENT_TOOL_RESULT_TIMEOUT_MS),
+        extensionSetupTimeoutMs: parseOptionalPositiveInteger(env.BRIDGE_EXTENSION_SETUP_TIMEOUT_MS),
+        routeInventoryEnabled: desktopMode || parseBoolean(env.BRIDGE_ROUTE_INVENTORY, false),
+        modelPayloadLogging: parseModelPayloadLogging(env.BRIDGE_LOG_MODEL_PAYLOADS),
+        agentToolPolicy: parseAgentToolPolicy(env.BRIDGE_AGENT_TOOL_POLICY),
+        agentToolMaxIterations: parseInteger(env.BRIDGE_AGENT_TOOL_MAX_ITERATIONS, 8),
+    };
+}
+function parseModelPayloadLogging(value) {
+    if (value === "full") {
+        return "full";
+    }
+    return "summary";
+}
+function parseAgentToolPolicy(value) {
+    if (value === undefined || value === "") {
+        return "safe";
+    }
+    if (value === "safe" || value === "all") {
+        return value;
+    }
+    throw new Error("BRIDGE_AGENT_TOOL_POLICY must be safe or all");
+}
+function parseModels(env, fallback) {
+    const raw = emptyToUndefined(env.BRIDGE_MODELS_JSON);
+    if (raw === undefined) {
+        return [fallback];
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error("BRIDGE_MODELS_JSON must be a JSON array");
+    }
+    return parsed.map((item, index) => {
+        if (!isRecord(item)) {
+            throw new Error(`BRIDGE_MODELS_JSON[${index}] must be an object`);
+        }
+        const id = requiredString(item.id, `BRIDGE_MODELS_JSON[${index}].id`);
+        const baseUrl = requiredString(item.baseUrl, `BRIDGE_MODELS_JSON[${index}].baseUrl`);
+        return {
+            id,
+            displayName: typeof item.displayName === "string" ? item.displayName : id,
+            providerModel: typeof item.providerModel === "string" ? item.providerModel : id,
+            baseUrl,
+            apiKey: typeof item.apiKey === "string" ? item.apiKey : "",
+            contextTokenLimit: typeof item.contextTokenLimit === "number" &&
+                Number.isFinite(item.contextTokenLimit)
+                ? item.contextTokenLimit
+                : fallback.contextTokenLimit,
+            requestTimeoutMs: typeof item.requestTimeoutMs === "number" &&
+                Number.isFinite(item.requestTimeoutMs) &&
+                item.requestTimeoutMs > 0
+                ? item.requestTimeoutMs
+                : fallback.requestTimeoutMs,
+            hardcodedResponse: typeof item.hardcodedResponse === "string"
+                ? item.hardcodedResponse
+                : undefined,
+        };
+    });
+}
+function parseLogLevel(value) {
+    switch (value) {
+        case undefined:
+        case "":
+            return "info";
+        case "debug":
+        case "info":
+        case "warn":
+        case "error":
+            return value;
+        default:
+            throw new Error(`Invalid BRIDGE_LOG_LEVEL: ${value}`);
+    }
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    if (value === "true" || value === "1") {
+        return true;
+    }
+    if (value === "false" || value === "0") {
+        return false;
+    }
+    throw new Error(`Invalid boolean value: ${value}`);
+}
+function parseInteger(value, fallback) {
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid integer value: ${value}`);
+    }
+    return parsed;
+}
+function parseOptionalPositiveInteger(value) {
+    if (value === undefined || value === "") {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid integer value: ${value}`);
+    }
+    return parsed;
+}
+function parseCsv(value, fallback) {
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    const parsed = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    if (parsed.length === 0) {
+        throw new Error("CSV value must contain at least one non-empty item");
+    }
+    return parsed;
+}
+function isLocalhost(host) {
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+function emptyToUndefined(value) {
+    return value === undefined || value.length === 0 ? undefined : value;
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/src/connectEnvelope.d.ts

@@ -0,0 +1,16 @@
+export interface ConnectEnvelope {
+    flags: number;
+    payload: Buffer;
+}
+export interface EnvelopeParseResult {
+    envelopes: ConnectEnvelope[];
+    remainder: Buffer;
+}
+export declare function encodeEnvelope(payload: Uint8Array, flags?: number): Buffer;
+export declare function encodeEndStream(metadata?: Record<string, string>): Buffer;
+export declare function isCompressedEnvelope(envelope: ConnectEnvelope): boolean;
+export declare function isEndStreamEnvelope(envelope: ConnectEnvelope): boolean;
+export declare function decodeEnvelopes(input: Buffer): ConnectEnvelope[];
+export declare function parseEnvelopes(input: Buffer): EnvelopeParseResult;
+export declare function firstMessagePayload(input: Buffer): Buffer;
+export declare function firstMessageEnvelope(input: Buffer): ConnectEnvelope | undefined;

package/dist/src/connectEnvelope.js

@@ -0,0 +1,70 @@
+const HEADER_LENGTH = 5;
+const COMPRESSED_FLAG = 0x01;
+const END_STREAM_FLAG = 0x02;
+export function encodeEnvelope(payload, flags = 0) {
+    const body = Buffer.from(payload);
+    const frame = Buffer.allocUnsafe(HEADER_LENGTH + body.length);
+    frame.writeUInt8(flags, 0);
+    frame.writeUInt32BE(body.length, 1);
+    body.copy(frame, HEADER_LENGTH);
+    return frame;
+}
+export function encodeEndStream(metadata = {}) {
+    return encodeEnvelope(Buffer.from(JSON.stringify({ metadata }), "utf8"), END_STREAM_FLAG);
+}
+export function isCompressedEnvelope(envelope) {
+    return (envelope.flags & COMPRESSED_FLAG) === COMPRESSED_FLAG;
+}
+export function isEndStreamEnvelope(envelope) {
+    return (envelope.flags & END_STREAM_FLAG) === END_STREAM_FLAG;
+}
+export function decodeEnvelopes(input) {
+    const result = parseEnvelopes(input);
+    if (result.remainder.length > 0) {
+        if (result.remainder.length < HEADER_LENGTH) {
+            throw new Error("Truncated Connect envelope header");
+        }
+        throw new Error("Truncated Connect envelope payload");
+    }
+    return result.envelopes;
+}
+export function parseEnvelopes(input) {
+    const envelopes = [];
+    let offset = 0;
+    while (offset < input.length) {
+        if (input.length - offset < HEADER_LENGTH) {
+            break;
+        }
+        const flags = input.readUInt8(offset);
+        const length = input.readUInt32BE(offset + 1);
+        const payloadStart = offset + HEADER_LENGTH;
+        const payloadEnd = payloadStart + length;
+        if (payloadEnd > input.length) {
+            break;
+        }
+        envelopes.push({
+            flags,
+            payload: input.subarray(payloadStart, payloadEnd),
+        });
+        offset = payloadEnd;
+    }
+    return { envelopes, remainder: input.subarray(offset) };
+}
+export function firstMessagePayload(input) {
+    if (input.length < HEADER_LENGTH) {
+        return input;
+    }
+    const declaredLength = input.readUInt32BE(1);
+    if (declaredLength <= input.length - HEADER_LENGTH) {
+        try {
+            return decodeEnvelopes(input)[0]?.payload ?? Buffer.alloc(0);
+        }
+        catch {
+            return input;
+        }
+    }
+    return input;
+}
+export function firstMessageEnvelope(input) {
+    return decodeEnvelopes(input).find((envelope) => !isEndStreamEnvelope(envelope));
+}

package/dist/src/desktop.d.ts

@@ -0,0 +1,19 @@
+import type { loadConfig } from "./config.js";
+export declare const DESKTOP_HOSTNAME = "api2.cursor.sh";
+export declare const DESKTOP_HOSTNAMES: readonly ["api2.cursor.sh", "api3.cursor.sh", "agent.api5.cursor.sh", "agentn.api5.cursor.sh", "agentn.global.api5.cursor.sh"];
+export declare const DESKTOP_CERT_DIR: string;
+export declare const DESKTOP_CERT_PATH: string;
+export declare const DESKTOP_KEY_PATH: string;
+type Config = ReturnType<typeof loadConfig>;
+export declare function desktopEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function desktopTrustCommand(certPath?: string): string[];
+export declare function writeDesktopCertificate(): Promise<{
+    certPath: string;
+    keyPath: string;
+    created: boolean;
+}>;
+export declare function desktopCertificateStatus(config: Config): string;
+export declare function desktopDnsStatus(config: Config): Promise<string>;
+export declare function upstreamReachabilityStatus(config: Config): Promise<string>;
+export declare function localModelBackendStatus(config: Config): Promise<string>;
+export {};