@velum-labs/cursorkit 0.1.0

package/docs/protocol-surface-audit.md

@@ -0,0 +1,92 @@
+# Protocol Surface Audit
+
+The repo has the full generated Cursor proto, but runtime coverage is still a
+small allowlist. This file separates schema visibility from implemented bridge
+surface. The machine-readable baseline is generated in
+`docs/route-contract-manifest.json` and `docs/implementation-inventory.json`.
+
+## Implemented Interceptors
+
+- Model discovery:
+  `/aiserver.v1.AiService/AvailableModels`,
+  `/aiserver.v1.AiService/GetUsableModels`,
+  `/aiserver.v1.AiService/GetDefaultModelForCli`,
+  `/aiserver.v1.AiService/GetDefaultModel`
+- Session naming/config:
+  `/aiserver.v1.AiService/NameAgent`,
+  `/aiserver.v1.ServerConfigService/GetServerConfig`
+- Agent run path:
+  `/agent.v1.AgentService/Run`,
+  `/agent.v1.AgentService/RunSSE`,
+  `/aiserver.v1.BidiService/BidiAppend`
+- Chat path:
+  `/aiserver.v1.ChatService/StreamUnifiedChatWithTools`
+- Desktop/auth diagnostics:
+  `/auth/full_stripe_profile`, `/auth/stripe_profile`,
+  `/aiserver.v1.AnalyticsService/UploadIssueTrace`
+
+Everything else is byte-preserving pass-through unless a plugin explicitly owns a
+route.
+
+## High-Value Gaps
+
+- `agent.v1.AgentService/RunPoll`: alternate agent transport. The current bridge
+  has conditional local handling for `Run` and `RunSSE`, but poll semantics stay
+  pass-through until observed and decoded.
+- `agent.v1.ControlService/*`: filesystem, shell, diff, artifact, skill reload,
+  and plugin reload APIs. This is the major missing surface for local models to
+  truly use Cursor tools.
+- `agent.v1.AgentServerMessage` tool-call updates: the generated proto has
+  `ToolCallStartedUpdate`, `ToolCallDeltaUpdate`, `ToolCallCompletedUpdate`, and
+  many concrete tool-call messages. Local OpenAI tool calls need to be translated
+  into these messages, then resumed with client tool results.
+- `ChatService/StreamUnifiedChatWithToolsSSE`: visible in the proto but not yet
+  captured with fixtures. It should stay pass-through until framing and response
+  shape are verified.
+- Desktop model picker routes: current desktop traffic has not reached the bridge
+  without manual routing. Do not guess desktop-specific routes until
+  route-inventory logs prove them.
+- Dashboard/plugin/skills routes: observed as healthy pass-through in CLI/ACP
+  traffic. These are likely extension-management surfaces, but should not be
+  intercepted without decoded fixtures and a product reason.
+
+## Current Context/Tool State
+
+The previous local agent implementation forwarded only
+`UserMessage.text` to the OpenAI-compatible backend. That made local runs appear
+to lack repository context and tool access.
+
+The bridge now forwards already-materialized context when Cursor sends it:
+
+- custom system prompt
+- user selected files/code/terminal/context snippets
+- hook context
+- inline prompt-context tree nodes
+- MCP tool names/descriptions as metadata
+
+The bridge also logs `local agent run diagnostics` with body-free counts for
+context, MCP tools, and injected context messages. Real traffic currently shows:
+
+- `cursor-agent --print`: no MCP tools and no context in the probe.
+- `cursor-agent acp`: 59 MCP tool definitions and one injected context/tool
+  metadata message in the probe.
+
+This is not full tool execution. Full tool support needs a loop:
+
+1. Send OpenAI-compatible `tools` definitions for Cursor/MCP tools.
+2. Parse streaming `tool_calls` from the local model.
+3. Emit Cursor `AgentServerMessage` tool-call started/delta/completed updates.
+4. Receive the client-side tool result through the agent protocol.
+5. Continue the local model conversation with tool results.
+
+## Desktop Test State
+
+`desktop-ui-experimental` now launches an isolated Cursor app with a Chromium
+remote debugging port and captures renderer DOM text through CDP. On this
+machine, isolated CDP works and reaches the real Cursor workbench renderer, but
+the isolated profile stops at login, so model-picker assertions are blocked by
+auth state.
+
+Default-profile launches can reuse auth, but may attach to an already-running
+Cursor process and ignore a new debug port. A fully automated picker test needs a
+logged-in debuggable profile or a reliable isolated-profile auth flow.

package/docs/protocol.md

@@ -0,0 +1,52 @@
+# Observed Protocol
+
+This document records the transport assumptions that the bridge is allowed to rely on. Unknown or unverified behavior must stay on the byte-preserving pass-through path.
+
+See `docs/learnings.md` for the broader set of implementation observations,
+debugging lessons, and known unknowns behind these protocol rules.
+See `docs/protocol-surface-audit.md` for the gap analysis between the full proto
+surface and the routes currently implemented by the bridge. The generated
+baseline files `docs/route-contract-manifest.json`,
+`docs/implementation-inventory.json`, `docs/test-manifest.json`, and
+`docs/release-summary.json` are checked by `pnpm baseline:check`.
+
+## Current Verified Surface
+
+- The default proto files are package-preserving outputs under `proto/`.
+- `docs/service-manifest.json` and `docs/type-manifest-summary.json` are generated from the full default proto files.
+- Runtime interception is allowlisted in `src/routes.ts`.
+- The route/proto contract manifest is generated from `docs/service-manifest.json`, `src/routes.ts`, and `src/config.ts`.
+- Cursor Agent CLI model-listing RPCs use raw `application/proto` framing, not Connect envelopes. Model interceptors must preserve the incoming protobuf framing.
+- The current interceptable routes are:
+  - `/aiserver.v1.AiService/AvailableModels`
+  - `/aiserver.v1.AiService/GetUsableModels`
+  - `/aiserver.v1.AiService/GetDefaultModelForCli`
+  - `/aiserver.v1.AiService/GetDefaultModel`
+  - `/aiserver.v1.AiService/NameAgent`
+  - `/aiserver.v1.ServerConfigService/GetServerConfig`
+  - `/auth/full_stripe_profile`
+  - `/auth/stripe_profile`
+  - `/agent.v1.AgentService/Run`
+  - `/agent.v1.AgentService/RunSSE`
+  - `/aiserver.v1.BidiService/BidiAppend`
+  - `/aiserver.v1.ChatService/StreamUnifiedChatWithTools`
+  - `/aiserver.v1.AnalyticsService/UploadIssueTrace`
+- Cursor desktop app support is observe-first. Desktop mode enables redacted route inventory logging, but it does not add desktop-only interceptors until traffic proves the exact RPC and framing.
+
+## Transport Behavior To Capture
+
+Before enabling additional typed routes, capture and sanitize:
+
+- HTTP version and ALPN.
+- TLS, SNI, Host, and certificate expectations.
+- Exact endpoint path and query strings.
+- Request and response content types.
+- Connect envelope flags, compressed-frame behavior, and end-stream metadata.
+- Response streaming behavior and whether first bytes arrive before the full response is buffered.
+- Request abort behavior and upstream cancellation.
+- Trailer or trailer-like metadata.
+- SSE behavior for `StreamUnifiedChatWithToolsSSE`.
+
+## Default Policy
+
+Every route starts as pass-through-only. A route can become interceptable only when a sanitized fixture proves its method path, body envelope, decoded message type, response shape, and failure behavior.

package/docs/refreshing-protos.md

@@ -0,0 +1,78 @@
+# Refreshing Protos
+
+This repo vendors the proto extraction logic under `vendor/extract-cursor-protos`.
+The checked-in `proto/` directory is the full extracted proto surface used for
+endpoint visibility, runtime decoding, and TypeScript codegen. When Cursor
+version drift breaks the bridge, refresh from the installed Cursor app and
+update the runtime code against captured fixtures.
+
+## Source
+
+The extractor was vendored from the public research repository
+`unkn0wncode/extract-cursor-protos`, tree
+`1932c41e1e53adc8b118fe73cfe462828682a802`. See
+`vendor/extract-cursor-protos/UPSTREAM.md`.
+
+No upstream license file was present when vendored, so keep attribution intact
+and treat the code as experimental research material.
+
+## Refresh Stable Cursor
+
+```bash
+pnpm install
+pnpm extract:protos
+```
+
+That command runs:
+
+```bash
+cd vendor/extract-cursor-protos
+go run . /Applications/Cursor.app ../../proto
+```
+
+The output path is the default proto directory used by the project:
+
+```text
+proto/
+```
+
+The current extraction is summarized in `docs/proto-inventory.md`. Regenerate
+the inventory, manifests, and TypeScript code after extraction:
+
+```bash
+pnpm proto:inventory
+pnpm codegen
+```
+
+The Cursor bundle exposes runtime descriptors with package and type names, but
+not original `.proto` file metadata. Some descriptors include foreign package
+references and nested names that would create invalid protoc import cycles if
+written one-file-per-package. The extractor therefore normalizes the full
+discovered graph for codegen: nested types are flattened, foreign message shapes
+are copied into the consuming package with provenance comments, and service
+paths keep their source package names.
+
+## Refresh Cursor Nightly Or A Custom App Path
+
+```bash
+cd vendor/extract-cursor-protos
+go run . "/Applications/Cursor Nightly.app" ../../proto
+```
+
+The extractor treats app paths containing `nightly` as Nightly builds and uses
+the upstream Nightly compatibility path.
+
+## After Refreshing
+
+1. Capture real Cursor traffic again for `AvailableModels` and
+   `StreamUnifiedChatWithTools`.
+2. Decode the captures with the refreshed proto.
+3. Run `pnpm proto:inventory`.
+4. Run `pnpm codegen`.
+5. Update `fixtures/` and `docs/protocol.md`.
+6. Update bridge routing or translation code only after fixtures prove the field tags
+   and streaming event order.
+
+Do not assume a generated proto is sufficient by itself. Cursor’s server
+expectations also include headers, Connect envelope framing, endpoint selection,
+and version-specific streaming behavior.

package/docs/release-gates.md

@@ -0,0 +1,110 @@
+# Release Gates
+
+This package publishes to public npm as `@velum-labs/cursorkit` through CI; there are no
+manual deploys. `pnpm release:check` is the authoritative deterministic local
+release gate. It runs generated baseline drift checks, build, deterministic
+tests, formatting, examples typecheck, and package artifact smoke validation,
+then writes `.cursor-rpc/release-check/release-summary.json`.
+
+GitHub Actions release automation lives in `.github/workflows/release-packages.yml`. It
+validates, tests, and packs the package on a published GitHub Release (and on
+`workflow_dispatch` dry runs). Publishing is gated behind a published GitHub
+Release (not a bare tag push) so the release notes and tag are reviewed before
+anything ships, and the publish step uploads the packed tarball as a workflow
+artifact for provenance.
+
+Before publishing or sharing a tarball, all gates must pass:
+
+- `pnpm install --frozen-lockfile`
+- `pnpm release:publish:check`
+- `pnpm release:check`
+- `pnpm baseline:check`
+- `pnpm build`
+- `pnpm test`
+- `pnpm format:check`
+- `pnpm examples:check`
+- `pnpm audit --audit-level moderate`
+- `pnpm pack`
+- `node dist/src/cli.js --help`
+- `go test ./...` from `vendor/extract-cursor-protos`
+
+## Release publish workflow
+
+Triggers:
+
+- a published GitHub Release whose tag matches `cursorkit-v*`
+  (for example `cursorkit-v0.1.0`) or `v*` (for example `v0.1.0`)
+- manual `workflow_dispatch` dry runs, with `dry_run: true` by default
+
+Safety guards:
+
+- The release job only runs when
+  `github.repository == 'velum-labs/cursorkit'`, so forks cannot publish.
+- The publish step only runs on the `release: published` event (reviewed release
+  notes + tag) and only when `package.json` has `"private": false`.
+- `pnpm release:publish:check` requires:
+  - `publishConfig.registry` to be `https://registry.npmjs.org`;
+  - `publishConfig.access` to be `public`;
+  - `publishConfig.provenance` to be `true`;
+  - `package.json` `private` to be `false`;
+  - the model-fusion protocol package pin to name
+    `@velum-labs/model-fusion-protocol`;
+  - the pinned model-fusion protocol schema bundle hash to match the local
+    JSON Schema/OpenAPI protocol manifest.
+- Model-fusion service clients/types must come from the generated
+  `@velum-labs/model-fusion-protocol` OpenAPI package once fusionkit publishes it.
+- Durable record validators/types must come from the fusionkit JSON Schema bundle
+  in the generated protocol package. Cursorkit's local record validators are
+  temporary fixture validators with schema-bundle provenance until that package
+  is published.
+- `@velum-labs/model-fusion-protocol` must be installable from GitHub Packages,
+  and its installed protocol metadata must match the pinned schema bundle hash.
+- Protobuf/Buf remains outside the v1 release path; the release check expects
+  JSON Schema durable records and OpenAPI 3.1 HTTP/API contracts.
+
+Secrets and permissions:
+
+- Dry runs require no custom secret. Publishing to public npm uses OIDC trusted
+  publishing (`id-token: write` + `npm publish --provenance`); once a Trusted
+  Publisher is configured on npmjs.com no token is needed, and `NPM_TOKEN` is the
+  bootstrap fallback for the first publish.
+- Installing the `@velum-labs/model-fusion-protocol` devDep from GitHub Packages
+  uses `PACKAGES_READ_TOKEN` (falling back to the built-in `GITHUB_TOKEN`).
+- Python/private PyPI secrets such as `PRIVATE_PYPI_*` are intentionally not used
+  in cursorkit. They belong in fusionkit's protocol-package release workflow.
+
+`pnpm release:check` is the command to trust for deterministic readiness. The
+other commands are listed so an operator can reproduce a failing layer directly
+or run extra non-deterministic checks before final-gate validation.
+
+Package smoke validates:
+
+- `pnpm pack` succeeds after a build.
+- The tarball contains the required `dist/src`, `proto`, `docs`, `README.md`,
+  and `DISCLAIMER.md` files.
+- `examples/` is intentionally excluded from the tarball; source examples are
+  typechecked by `pnpm examples:check` against the built package exports.
+- A temporary clean project can install the tarball with `pnpm add --offline`.
+- The installed `cursorkit` binary can execute `--help`.
+
+Optional live suites are not part of deterministic release readiness. The
+release summary reports them as `skipped_with_reason` until prerequisites such
+as a running MLX backend, Cursor auth, or Cursor desktop are available.
+
+Generated baseline artifacts:
+
+- `docs/route-contract-manifest.json`: route/proto contract entries generated
+  from `docs/service-manifest.json`, `src/routes.ts`, and `src/config.ts`.
+- `docs/implementation-inventory.json`: route, config, and uncertainty
+  inventory for the current implementation.
+- `docs/test-manifest.json`: deterministic and optional-live suite inventory,
+  release-check behavior, prerequisites, and artifact outputs.
+- `docs/release-summary.json`: baseline completion metrics and remaining
+  blockers for the next production phases, grouped by protocol, MLX, tool,
+  desktop optional-live, reliability/security, packaging, and final gate status.
+
+API stability policy:
+
+- `@velum-labs/cursorkit/extensions` and `@velum-labs/cursorkit/providers/openai` are experimental.
+- Breaking plugin API changes are allowed while these subpaths remain experimental.
+- Add semver guarantees and deprecation windows before marking extension APIs stable.

package/docs/release-summary.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": 1,
+  "generatedBy": "src/tools/baselineInventory.ts",
+  "phase": "baseline-drift",
+  "status": "ci-release-scaffolded",
+  "deterministicGate": "pnpm release:check",
+  "categories": [
+    {
+      "id": "baseline-drift",
+      "deterministicSuites": ["baseline-drift"],
+      "optionalLiveSuites": [],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "static",
+      "deterministicSuites": ["build", "format-check"],
+      "optionalLiveSuites": [],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "protocol",
+      "deterministicSuites": ["baseline-drift", "unit-tests"],
+      "optionalLiveSuites": ["real-client-live"],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "mlx",
+      "deterministicSuites": ["unit-tests"],
+      "optionalLiveSuites": ["mlx-live", "real-client-live"],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "tool",
+      "deterministicSuites": ["unit-tests"],
+      "optionalLiveSuites": ["real-client-live"],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "desktop-optional-live",
+      "deterministicSuites": [],
+      "optionalLiveSuites": ["desktop-live"],
+      "releaseCheckStatus": "skipped_with_reason_until_prerequisites_available"
+    },
+    {
+      "id": "reliability-security",
+      "deterministicSuites": ["unit-tests"],
+      "optionalLiveSuites": [],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "packaging",
+      "deterministicSuites": ["examples-typecheck", "pack-smoke"],
+      "optionalLiveSuites": [],
+      "releaseCheckStatus": "required"
+    },
+    {
+      "id": "final-gate",
+      "deterministicSuites": [
+        "baseline-drift",
+        "build",
+        "unit-tests",
+        "format-check",
+        "examples-typecheck",
+        "pack-smoke"
+      ],
+      "optionalLiveSuites": [],
+      "releaseCheckStatus": "required"
+    }
+  ],
+  "metrics": {
+    "routeContractCoverage": "13/13",
+    "interceptRouteCount": 13,
+    "protoBackedRouteCount": 11,
+    "configEnvVarCount": 39,
+    "uncertaintyCount": 7,
+    "implementedDeterministicSuites": 6,
+    "placeholderSuites": 0,
+    "optionalLiveSuites": 3
+  },
+  "remainingBlockers": [
+    "Captured fixture replay for conditional intercept routes.",
+    "Live cursor-agent, ACP, and desktop acceptance gates.",
+    "Final reliability/security hardening validation.",
+    "Final full-gate run with optional live MLX and desktop prerequisites available."
+  ]
+}