@velum-labs/cursorkit 0.1.0

package/dist/src/testing/localBackend.js

@@ -0,0 +1,310 @@
+import { parseOpenAIStream } from "../providers/openai.js";
+export async function probeLocalBackend(options) {
+    const models = await fetchModels(options);
+    if (!models.ok) {
+        return models;
+    }
+    if (!models.models.includes(options.model)) {
+        return {
+            ok: false,
+            failureCode: "backend_unreachable",
+            message: `Model ${options.model} was not returned by /models`,
+            modelsStatus: models.modelsStatus,
+            models: models.models,
+            selectedModelFound: false,
+        };
+    }
+    const chat = await fetchChatCompletion(options);
+    if (!chat.ok) {
+        return {
+            ...chat,
+            modelsStatus: models.modelsStatus,
+            models: models.models,
+            selectedModelFound: true,
+        };
+    }
+    if (options.checkToolCalls === true) {
+        const toolCall = await fetchToolCallCompletion(options);
+        if (!toolCall.ok) {
+            return {
+                ...toolCall,
+                modelsStatus: models.modelsStatus,
+                chatStatus: chat.chatStatus,
+                streamingChatStatus: chat.streamingChatStatus,
+                models: models.models,
+                selectedModelFound: true,
+                nonStreamingSupported: chat.nonStreamingSupported,
+                streamingSupported: chat.streamingSupported,
+            };
+        }
+        return {
+            ok: true,
+            message: "Local backend returned the selected model, completed a chat probe, and streamed a tool call",
+            modelsStatus: models.modelsStatus,
+            chatStatus: chat.chatStatus,
+            streamingChatStatus: chat.streamingChatStatus,
+            toolChatStatus: toolCall.toolChatStatus,
+            models: models.models,
+            selectedModelFound: true,
+            nonStreamingSupported: chat.nonStreamingSupported,
+            streamingSupported: chat.streamingSupported,
+            toolCallsSupported: true,
+            completionPreview: chat.completionPreview,
+        };
+    }
+    return {
+        ok: true,
+        message: `Local backend returned ${options.model} and completed a chat probe`,
+        modelsStatus: models.modelsStatus,
+        chatStatus: chat.chatStatus,
+        streamingChatStatus: chat.streamingChatStatus,
+        models: models.models,
+        selectedModelFound: true,
+        nonStreamingSupported: chat.nonStreamingSupported,
+        streamingSupported: chat.streamingSupported,
+        completionPreview: chat.completionPreview,
+    };
+}
+async function fetchModels(options) {
+    const url = `${trimTrailingSlash(options.baseUrl)}/models`;
+    try {
+        const response = await fetchWithTimeout(url, {
+            method: "GET",
+            headers: authHeaders(options.apiKey),
+            timeoutMs: options.timeoutMs,
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                failureCode: "backend_unreachable",
+                message: `/models returned HTTP ${response.status}`,
+                modelsStatus: response.status,
+                models: [],
+            };
+        }
+        const json = (await response.json());
+        return {
+            ok: true,
+            message: "/models returned model data",
+            modelsStatus: response.status,
+            models: (json.data ?? [])
+                .map((model) => model.id)
+                .filter((id) => id !== undefined),
+            selectedModelFound: (json.data ?? []).some((model) => model.id === options.model),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "backend_unreachable",
+            message: `/models request failed: ${errorMessage(error)}`,
+            models: [],
+        };
+    }
+}
+async function fetchChatCompletion(options) {
+    const url = `${trimTrailingSlash(options.baseUrl)}/chat/completions`;
+    try {
+        const response = await fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+                ...authHeaders(options.apiKey),
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: options.model,
+                messages: [{ role: "user", content: "Reply with exactly: ok" }],
+                max_tokens: 128,
+                stream: false,
+            }),
+            timeoutMs: options.timeoutMs,
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                failureCode: "local_completion_failed",
+                message: `/chat/completions returned HTTP ${response.status}`,
+                chatStatus: response.status,
+                models: [],
+            };
+        }
+        const json = (await response.json());
+        const content = json.choices?.[0]?.message?.content ?? "";
+        if (content.length === 0) {
+            return fetchStreamingChatCompletion(options);
+        }
+        return {
+            ok: true,
+            message: "/chat/completions returned a response",
+            chatStatus: response.status,
+            models: [],
+            nonStreamingSupported: true,
+            streamingSupported: false,
+            completionPreview: content.slice(0, 120),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "local_completion_failed",
+            message: `/chat/completions request failed: ${errorMessage(error)}`,
+            models: [],
+        };
+    }
+}
+async function fetchStreamingChatCompletion(options) {
+    const url = `${trimTrailingSlash(options.baseUrl)}/chat/completions`;
+    try {
+        const response = await fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+                ...authHeaders(options.apiKey),
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: options.model,
+                messages: [{ role: "user", content: "Reply with exactly: ok" }],
+                max_tokens: 128,
+                stream: true,
+            }),
+            timeoutMs: options.timeoutMs,
+        });
+        if (!response.ok || response.body === null) {
+            return {
+                ok: false,
+                failureCode: "local_completion_failed",
+                message: `/chat/completions streaming returned HTTP ${response.status}`,
+                streamingChatStatus: response.status,
+                models: [],
+            };
+        }
+        let content = "";
+        for await (const chunk of parseOpenAIStream(response.body)) {
+            if (typeof chunk !== "string") {
+                continue;
+            }
+            content += chunk;
+            if (content.length >= 120) {
+                break;
+            }
+        }
+        if (content.length === 0) {
+            return {
+                ok: false,
+                failureCode: "local_completion_failed",
+                message: "/chat/completions returned an empty or malformed non-streaming and streaming completion",
+                streamingChatStatus: response.status,
+                models: [],
+            };
+        }
+        return {
+            ok: true,
+            message: "/chat/completions returned a streaming response",
+            streamingChatStatus: response.status,
+            models: [],
+            nonStreamingSupported: false,
+            streamingSupported: true,
+            completionPreview: content.slice(0, 120),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "local_completion_failed",
+            message: `/chat/completions streaming request failed: ${errorMessage(error)}`,
+            models: [],
+        };
+    }
+}
+async function fetchToolCallCompletion(options) {
+    const url = `${trimTrailingSlash(options.baseUrl)}/chat/completions`;
+    try {
+        const response = await fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+                ...authHeaders(options.apiKey),
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: options.model,
+                messages: [{ role: "user", content: "Call the probe_tool function." }],
+                stream: true,
+                tools: [
+                    {
+                        type: "function",
+                        function: {
+                            name: "probe_tool",
+                            description: "A deterministic probe tool.",
+                            parameters: {
+                                type: "object",
+                                properties: { value: { type: "string" } },
+                                required: ["value"],
+                            },
+                        },
+                    },
+                ],
+            }),
+            timeoutMs: options.timeoutMs,
+        });
+        if (!response.ok || response.body === null) {
+            return {
+                ok: false,
+                failureCode: "local_completion_failed",
+                message: `/chat/completions tool-call streaming returned HTTP ${response.status}`,
+                toolChatStatus: response.status,
+                models: [],
+            };
+        }
+        for await (const chunk of parseOpenAIStream(response.body)) {
+            if (typeof chunk !== "string" &&
+                chunk.toolCalls.some((toolCall) => toolCall.function.name === "probe_tool")) {
+                return {
+                    ok: true,
+                    message: "/chat/completions streamed a tool call",
+                    toolChatStatus: response.status,
+                    models: [],
+                    toolCallsSupported: true,
+                };
+            }
+        }
+        return {
+            ok: false,
+            failureCode: "local_completion_failed",
+            message: "/chat/completions did not stream a probe tool call",
+            toolChatStatus: response.status,
+            models: [],
+            toolCallsSupported: false,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "local_completion_failed",
+            message: `/chat/completions tool-call streaming request failed: ${errorMessage(error)}`,
+            models: [],
+            toolCallsSupported: false,
+        };
+    }
+}
+async function fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        return await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function authHeaders(apiKey) {
+    return apiKey.length === 0 ? {} : { authorization: `Bearer ${apiKey}` };
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/$/, "");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,7 @@
+import type { ArtifactWriter, ProcessRunOptions, ProcessRunResult, ProcessRunner } from "./types.js";
+export declare class ChildProcessRunner implements ProcessRunner {
+    private readonly cwd;
+    private readonly artifacts;
+    constructor(cwd: string, artifacts: ArtifactWriter);
+    run(options: ProcessRunOptions): Promise<ProcessRunResult>;
+}

package/dist/src/testing/processRunner.js

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+export class ChildProcessRunner {
+    cwd;
+    artifacts;
+    constructor(cwd, artifacts) {
+        this.cwd = cwd;
+        this.artifacts = artifacts;
+    }
+    async run(options) {
+        const started = Date.now();
+        const commandLine = [options.command, ...options.args].join(" ");
+        const child = spawn(options.command, options.args, {
+            cwd: this.cwd,
+            env: mergeEnv(process.env, options.env ?? {}),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = options.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+            }, options.timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        const exit = await new Promise((resolve, reject) => {
+            child.on("error", reject);
+            child.on("exit", (exitCode, signal) => resolve({ exitCode, signal }));
+        });
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        const result = {
+            command: options.command,
+            args: options.args,
+            exitCode: exit.exitCode,
+            signal: exit.signal,
+            timedOut,
+            durationMs: Date.now() - started,
+            stdout,
+            stderr,
+            logPath: "",
+        };
+        result.logPath = this.artifacts.writeText(`logs/${options.logName}.log`, [
+            `$ ${commandLine}`,
+            "",
+            "## stdout",
+            stdout,
+            "",
+            "## stderr",
+            stderr,
+            "",
+        ].join("\n"));
+        return result;
+    }
+}
+function mergeEnv(base, overrides) {
+    const env = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            delete env[key];
+        }
+        else {
+            env[key] = value;
+        }
+    }
+    return env;
+}

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

@@ -0,0 +1,9 @@
+import type { ArtifactWriter, HarnessOptions, HarnessSuite, HarnessSuiteInput, ProcessRunner, Scenario, ScenarioResult } from "./types.js";
+export declare class ScenarioRunner {
+    private readonly scenarios;
+    private readonly artifacts;
+    private readonly processRunner;
+    constructor(scenarios: Scenario[], artifacts: ArtifactWriter, processRunner: ProcessRunner);
+    run(options: HarnessOptions): Promise<ScenarioResult[]>;
+}
+export declare function expandSuites(inputs: HarnessSuiteInput[], options: Pick<HarnessOptions, "includeExperimental">): HarnessSuite[];

package/dist/src/testing/runner.js

@@ -0,0 +1,85 @@
+export class ScenarioRunner {
+    scenarios;
+    artifacts;
+    processRunner;
+    constructor(scenarios, artifacts, processRunner) {
+        this.scenarios = scenarios;
+        this.artifacts = artifacts;
+        this.processRunner = processRunner;
+    }
+    async run(options) {
+        const suites = expandSuites(options.suites, options);
+        const selected = this.scenarios.filter((scenario) => suites.includes(scenario.suite));
+        const context = {
+            options,
+            artifacts: this.artifacts,
+            processRunner: this.processRunner,
+        };
+        const results = [];
+        for (const scenario of selected) {
+            const started = Date.now();
+            try {
+                results.push(await scenario.run(context));
+            }
+            catch (error) {
+                results.push({
+                    id: scenario.id,
+                    suite: scenario.suite,
+                    status: "failed",
+                    durationMs: Date.now() - started,
+                    message: error instanceof Error ? error.message : String(error),
+                    failureCode: "command_failed",
+                });
+            }
+        }
+        return results;
+    }
+}
+export function expandSuites(inputs, options) {
+    const expanded = [];
+    for (const input of inputs.length === 0 ? ["all"] : inputs) {
+        switch (input) {
+            case "all":
+                pushUnique(expanded, "static");
+                pushUnique(expanded, "bridge-protocol");
+                pushUnique(expanded, "cursor-agent");
+                if (options.includeExperimental) {
+                    pushUnique(expanded, "cursor-agent-acp-experimental");
+                    pushUnique(expanded, "desktop-ui-experimental");
+                }
+                break;
+            case "acp":
+                pushUnique(expanded, "cursor-agent-acp-experimental");
+                break;
+            case "cli":
+                pushUnique(expanded, "cursor-agent");
+                break;
+            case "traffic":
+                pushUnique(expanded, "cursor-agent-traffic");
+                break;
+            case "desktop":
+                pushUnique(expanded, "desktop-route");
+                break;
+            case "static":
+            case "bridge-protocol":
+            case "local-backend":
+            case "cursor-agent":
+            case "cursor-agent-traffic":
+            case "cursor-agent-acp-experimental":
+            case "desktop-route":
+            case "desktop-ui-experimental":
+                pushUnique(expanded, input);
+                break;
+            default: {
+                const exhaustive = input;
+                throw new Error(`Unhandled suite: ${exhaustive}`);
+            }
+        }
+    }
+    return expanded;
+}
+function pushUnique(suites, suite) {
+    if (!suites.includes(suite)) {
+        suites.push(suite);
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { HarnessOptions, Scenario } from "./types.js";
+export declare function createScenarios(): Scenario[];
+export declare function desktopUiCkArgs(options: Pick<HarnessOptions, "timeoutMs" | "useDefaultProfile">, debugPort: number, instanceId: string): string[];