@velum-labs/cursorkit 0.1.0

package/DISCLAIMER.md

@@ -0,0 +1,12 @@
+# Disclaimer
+
+This is an unofficial and unsupported interoperability research project.
+
+It attempts to emulate enough of Cursor's backend protocol for personal,
+experimental use with a self-hosted model. Reverse-engineering a client protocol
+to run your own models may conflict with Cursor's Terms of Service. Do not
+deploy this project as a hosted service, do not represent it as affiliated with
+Cursor, and do not rely on it for production workloads.
+
+Use it only for local research where you understand the legal, security, and
+compatibility risks.

package/README.md

@@ -0,0 +1,157 @@
+# cursorkit
+
+Unofficial research bridge for experimenting with Cursor's backend protocol from
+the server side: keep Cursor's existing UX, but route model inference to a
+self-hosted OpenAI-compatible endpoint.
+
+This is personal interoperability research, not a supported Cursor integration.
+Read `DISCLAIMER.md` before running it.
+
+## First Run
+
+```bash
+pnpm install
+pnpm build
+pnpm dev -- serve
+```
+
+In another terminal:
+
+```bash
+pnpm exec tsx src/cli.ts doctor
+```
+
+The bridge binds to `127.0.0.1:9443` by default. Set
+`CURSOR_UPSTREAM_BASE_URL` before expecting unknown Cursor backend traffic to
+pass through to an upstream. See `docs/configuration.md` for all config.
+
+## CLI
+
+```bash
+ck
+ck test
+ck --use-default-profile
+ck --print
+ck doctor
+ck cert
+ck route
+ck route status
+ck route rollback
+ck stop
+cursorkit serve
+cursorkit doctor
+cursorkit desktop-cert
+cursorkit desktop-proxy
+cursorkit desktop-doctor
+cursorkit capture
+cursorkit fixtures
+cursorkit --help
+```
+
+`serve` starts the local bridge. `doctor` checks proto loading, upstream config,
+TLS status, capture status, and local model registration. The `desktop-*`
+commands support explicit Cursor desktop app proxy experiments; see
+`docs/cursor-app.md`.
+
+The committed `fixtures/model-fusion-contract/` records are synthetic
+compatibility fixtures for the model-fusion roadmap. They validate Cursor-specific
+`cursor-run-*` records and generic `harness-run-*` records locally without adding
+`handoffkit` as a runtime dependency or changing live Cursor routing behavior.
+The importable `@velum-labs/cursorkit/model-fusion` subpath exposes the same fixture-backed
+surface as a small structural API: `cursorHarness(...)` and
+`runCursorCandidate(...)` produce Cursor-specific records plus mapped generic
+harness results. Those records keep requested and observed model IDs separate,
+can attach redacted route-inventory artifact refs, and record unsupported Cursor
+capabilities explicitly. It does not own fan-out, judge synthesis, lifecycle,
+receipts, or live Cursor tool-call replay; desktop routes remain observed-only
+until fixture-backed evidence proves stability.
+
+`ck` is the recommended desktop test launcher. It starts the desktop bridge plus
+a local HTTP CONNECT proxy, opens an isolated Cursor profile with
+`--proxy-server`, and reports whether route inventory traffic reaches the
+bridge. For isolated desktop UI tests, it also seeds/activates local models
+additively in Cursor's settings-backed model picker state. It does not install
+certificates, edit `/etc/hosts`, modify `pf`, or kill your normal Cursor app.
+Inside this repo, use `pnpm ck`; when installed or linked as a package, use
+`ck` directly. If the isolated profile cannot complete browser login,
+`ck --use-default-profile` reuses your current Cursor auth state while keeping
+the same non-privileged routing attempt.
+Use `ck test --use-default-profile` for a bounded desktop smoke test that reports
+whether route inventory and the known model-list RPCs reached the bridge.
+
+The project knowledge base for observed Cursor behavior is `docs/learnings.md`.
+Read it before changing route interception, model metadata, or desktop proxy
+behavior.
+Use `docs/protocol-surface-audit.md` to see which parts of the full generated
+proto are implemented, which are only pass-through, and what is missing for full
+tool/context support.
+
+Use `docs/testing-harness.md` for the unified test runner that orchestrates
+static checks, bridge protocol tests, cursor-agent e2e, local backend probes,
+real `cursor-agent` traffic discovery, ACP JSON-RPC probes, and desktop
+route-inventory smoke tests.
+
+For app-level evidence, run the experimental desktop UI probe:
+
+```bash
+pnpm test:harness -- \
+  --suite desktop-ui-experimental \
+  --include-experimental \
+  --base-url http://127.0.0.1:8080/v1 \
+  --model local-qwen \
+  --provider-model mlx-community/Qwen3.5-4B-8bit \
+  --display-name local-qwen \
+  --api-key local
+```
+
+It launches an isolated Cursor instance with auth seeded from the logged-in
+default profile, waits for Cursor to initialize settings, activates the local
+model, opens this repo, attaches to the renderer over CDP, opens the Agent model
+picker, and fails unless both the configured local model and built-in Cursor
+models are visible.
+
+## Proto Extraction
+
+The proto extraction logic is vendored in `vendor/extract-cursor-protos`.
+
+```bash
+pnpm install
+pnpm extract:protos
+pnpm proto:inventory
+pnpm codegen
+```
+
+That refreshes the full default proto files under `proto/` from the installed
+Cursor app, regenerates `docs/proto-inventory.md`,
+`docs/service-manifest.json`, `docs/type-manifest-summary.json`, and writes
+generated TypeScript schemas and service descriptors under `src/gen/`.
+
+The extractor normalizes nested and foreign type references so the full
+discovered surface is codegen-valid. It does not hand-maintain a reduced route
+slice; runtime interception is still controlled by route policy.
+See `docs/refreshing-protos.md` for provenance, custom app paths, and the
+fixture workflow required after refreshing.
+See `docs/proto-inventory.md` for the generated service inventory.
+
+## Extension Surface
+
+The current typed extension surface is deliberately narrow:
+
+- Unknown routes proxy upstream by default.
+- `AvailableModels` can append conservative local model entries.
+- `StreamUnifiedChatWithTools` is intercepted only when the selected model is
+  registered locally; normal Cursor models pass upstream.
+- Cursor desktop app support starts in route-inventory mode so app-specific
+  RPCs can be observed before adding typed interceptors.
+
+See `docs/plugin-authoring.md` and the source-checkout `examples/` directory for
+the experimental local plugin shape. Examples are typechecked by
+`pnpm examples:check`, but they are intentionally excluded from packed tarballs.
+
+## Release Gates
+
+This package remains private and local-only. See `docs/release-gates.md` for the
+checks required before sharing a tarball or changing the API stability posture.
+Use `pnpm baseline:check` to verify generated route/config/docs drift and
+`pnpm release:check` for the authoritative deterministic local release gate,
+including package artifact smoke validation.

package/dist/src/agentTools/diff.d.ts

@@ -0,0 +1,11 @@
+export interface DiffStats {
+    added: number;
+    removed: number;
+}
+export declare function diffStats(before: string, after: string): DiffStats;
+/**
+ * Produce a git-style unified diff with a single hunk covering the whole file.
+ * The bridge synthesizes apply_patch from a read + write round trip, so this is
+ * the evidence we surface back to the model (and to model-fusion artifacts).
+ */
+export declare function unifiedDiff(path: string, before: string, after: string): string;

package/dist/src/agentTools/diff.js

@@ -0,0 +1,88 @@
+function splitLines(text) {
+    return text.length === 0 ? [] : text.split("\n");
+}
+function diffLines(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i][j] =
+                a[i] === b[j]
+                    ? dp[i + 1][j + 1] + 1
+                    : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ type: "equal", line: a[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            ops.push({ type: "delete", line: a[i] });
+            i += 1;
+        }
+        else {
+            ops.push({ type: "insert", line: b[j] });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        ops.push({ type: "delete", line: a[i] });
+        i += 1;
+    }
+    while (j < m) {
+        ops.push({ type: "insert", line: b[j] });
+        j += 1;
+    }
+    return ops;
+}
+export function diffStats(before, after) {
+    let added = 0;
+    let removed = 0;
+    for (const op of diffLines(splitLines(before), splitLines(after))) {
+        if (op.type === "insert") {
+            added += 1;
+        }
+        else if (op.type === "delete") {
+            removed += 1;
+        }
+    }
+    return { added, removed };
+}
+/**
+ * Produce a git-style unified diff with a single hunk covering the whole file.
+ * The bridge synthesizes apply_patch from a read + write round trip, so this is
+ * the evidence we surface back to the model (and to model-fusion artifacts).
+ */
+export function unifiedDiff(path, before, after) {
+    const a = splitLines(before);
+    const b = splitLines(after);
+    const ops = diffLines(a, b);
+    const lines = [`--- a/${path}`, `+++ b/${path}`];
+    const aStart = a.length === 0 ? 0 : 1;
+    const bStart = b.length === 0 ? 0 : 1;
+    lines.push(`@@ -${aStart},${a.length} +${bStart},${b.length} @@`);
+    for (const op of ops) {
+        switch (op.type) {
+            case "equal":
+                lines.push(` ${op.line}`);
+                break;
+            case "delete":
+                lines.push(`-${op.line}`);
+                break;
+            case "insert":
+                lines.push(`+${op.line}`);
+                break;
+            default: {
+                const exhaustive = op.type;
+                throw new Error(`unreachable diff op: ${String(exhaustive)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/src/agentTools/policy.d.ts

@@ -0,0 +1,3 @@
+import type { AgentToolPolicy } from "../config.js";
+import type { CursorToolSurfaceEntry } from "./surface.js";
+export declare function toolEnabledByPolicy(entry: CursorToolSurfaceEntry, policy: AgentToolPolicy): boolean;

package/dist/src/agentTools/policy.js

@@ -0,0 +1,12 @@
+export function toolEnabledByPolicy(entry, policy) {
+    if (entry.openAIToolName === undefined) {
+        return false;
+    }
+    if (entry.support === "supported") {
+        return true;
+    }
+    if (entry.support === "policy-gated") {
+        return policy === "all";
+    }
+    return false;
+}

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

@@ -0,0 +1,114 @@
+import type { ServerResponse } from "node:http";
+import { create } from "@bufbuild/protobuf";
+import type { AgentToolPolicy } from "../config.js";
+import { ExecServerMessageSchema } from "../gen/agent/v1/agent_pb.js";
+import type { Logger } from "../logger.js";
+import type { OpenAIToolCall } from "../providers/openai.js";
+import { type CursorToolError } from "./results.js";
+export { cursorOpenAITools } from "./schemas.js";
+export { agentExecClientMessageFields } from "./results.js";
+export interface CursorToolRuntime {
+    logger: Logger;
+    nextAgentExecId: number;
+    config: {
+        agentToolPolicy: AgentToolPolicy;
+        toolResultTimeoutMs?: number;
+    };
+}
+interface CursorToolExecutionOptions {
+    signal?: AbortSignal;
+}
+declare const TOOL_ARGUMENT_SCHEMAS: {
+    read_file: {
+        properties: {
+            path: "string";
+            offset: "integer";
+            limit: "integer";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    list_dir: {
+        properties: {
+            path: "string";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    grep: {
+        properties: {
+            pattern: "string";
+            path: "string";
+            glob: "string";
+            head_limit: "integer";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    run_shell: {
+        properties: {
+            command: "string";
+            working_directory: "string";
+            timeout: "integer";
+            description: "string";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    write_file: {
+        properties: {
+            path: "string";
+            content: "string";
+            return_file_content_after_write: "boolean";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    apply_patch: {
+        properties: {
+            path: "string";
+            old_string: "string";
+            new_string: "string";
+            replace_all: "boolean";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    delete_path: {
+        properties: {
+            path: "string";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    fetch_url: {
+        properties: {
+            url: "string";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+    mcp_tool: {
+        properties: {
+            provider_identifier: "string";
+            tool_name: "string";
+            name: "string";
+            arguments: "object";
+        };
+        required: string[];
+        nonEmpty: string[];
+    };
+};
+type SupportedOpenAIToolName = keyof typeof TOOL_ARGUMENT_SCHEMAS;
+export type CursorToolValidationResult = {
+    ok: true;
+    name: SupportedOpenAIToolName;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    error: CursorToolError;
+};
+export declare function executeCursorToolCall(response: ServerResponse, runtime: CursorToolRuntime, payloads: AsyncIterator<Buffer>, toolCall: OpenAIToolCall, options?: CursorToolExecutionOptions): Promise<string>;
+export declare function validateCursorToolCall(toolCall: OpenAIToolCall, policy: AgentToolPolicy): CursorToolValidationResult;
+export declare function cursorToolCallToExecServerMessage(id: number, execId: string, name: SupportedOpenAIToolName, toolCallId: string, args: Record<string, unknown>): ReturnType<typeof create<typeof ExecServerMessageSchema>> | undefined;
+export declare function summarizeToolArgs(args: Record<string, unknown>): Record<string, unknown>;