ocx-cursor 0.5.1 → 1.0.0

package/README.md

@@ -3,16 +3,29 @@
 [![npm version](https://img.shields.io/npm/v/ocx-cursor.svg)](https://www.npmjs.com/package/ocx-cursor)
 [![CI](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml)
 
-Use your active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through a local OpenAI-compatible gateway.
+Use your active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through an authenticated HTTPS endpoint on your Mac.
 
 > [!WARNING]
-> This package edits private JavaScript files inside `Cursor.app`. The changes invalidate Cursor's vendor signature, so Cursor may report that the installation is corrupt. The installer saves original files under `~/.opencodex/cursor-bridge/cursor-app-backups`. Reinstall Cursor to restore a signed app.
+> The installer edits two private workbench files inside `Cursor.app`. This invalidates Cursor's vendor signature. Cursor may report a corrupt installation. The bridge saves the original files under `~/.opencodex/cursor-bridge/cursor-app-backups`. Reinstall Cursor to restore a signed app.
 
-## Quick start
+## Requirements
 
-You need macOS, Node.js 22.5 or newer, and Cursor at `/Applications/Cursor.app`.
+- macOS with Cursor installed at `/Applications/Cursor.app`
+- Node.js 22.5 or newer
+- OpenCodex with at least one active model
+- An HTTPS hostname that forwards to `http://127.0.0.1:10101`
 
-Install and configure OpenCodex:
+Use [Cloudflare Tunnel](https://developers.cloudflare.com/tunnel/) for the HTTPS hostname, or choose another reverse proxy that preserves the `Authorization` header.
+
+## Upgrading from 0.5.x
+
+Version 0.5.x enabled Cursor's local-agent mode and edited ten app files. Version 1.0.0 edits two workbench files and leaves local-agent mode disabled.
+
+Reinstall Cursor before upgrading so macOS replaces the old app files. Quit the new Cursor installation, then follow the setup below. Your Cursor settings remain under `~/Library/Application Support/Cursor`.
+
+## Getting started
+
+Install OpenCodex and start its login service:
 
 ```bash
 npm install --global @bitkyc08/opencodex
@@ -21,96 +34,142 @@ ocx service install
 ocx service status
 ```
 
-Check the configured models:
+OpenCodex listens on `http://127.0.0.1:10100`. Check its active models:
 
 ```bash
 ocx models --json
 ```
 
-Launch Cursor and sign in once, then quit it. Run the bridge installer:
+Install `cloudflared`, sign in, and create a named tunnel:
 
 ```bash
-npx ocx-cursor init
-~/.local/bin/ocx-cursor status
+brew install cloudflared
+cloudflared tunnel login
+cloudflared tunnel create ocx-cursor
+cloudflared tunnel list
 ```
 
-`init` registers `http://127.0.0.1:10101/v1` in Cursor. You do not need a domain or tunnel. Open Cursor after the status command reports `Service: running` and `Gateway: healthy`.
+Create `~/.cloudflared/config.yml`. Replace the UUID, username, and hostname:
 
-Add the installed command to your shell path if needed:
+```yaml
+tunnel: YOUR_TUNNEL_UUID
+credentials-file: /Users/YOUR_USERNAME/.cloudflared/YOUR_TUNNEL_UUID.json
+
+ingress:
+  - hostname: cursor-api.example.com
+    service: http://127.0.0.1:10101
+  - service: http_status:404
+```
+
+Create the DNS record and check the ingress rule:
 
 ```bash
-export PATH="$HOME/.local/bin:$PATH"
+cloudflared tunnel route dns ocx-cursor cursor-api.example.com
+cloudflared tunnel ingress validate
+cloudflared tunnel ingress rule https://cursor-api.example.com
 ```
 
-## What init changes
+Start the tunnel at login with Cloudflare's [macOS service command](https://developers.cloudflare.com/tunnel/advanced/local-management/as-a-service/macos/):
 
-| Area | Change |
-| --- | --- |
-| Cursor settings | Stores the gateway key with macOS Safe Storage and sets the local base URL. |
-| Cursor model state | Adds active models under `opencodex/*` with names, effort choices, and Fast metadata. |
-| `Cursor.app` | Enables local-agent mode in eight bundles and patches two local-agent runtimes. |
-| Login service | Installs `com.opencodex.cursor-bridge`, refreshes models, and reapplies patches after Cursor updates. |
+```bash
+cloudflared service install
+```
 
-Requests stay on loopback until OpenCodex sends them to your configured provider:
+This command reads `~/.cloudflared/config.yml`. `sudo cloudflared service install` starts the tunnel at boot and reads `/etc/cloudflared/config.yml` instead.
+
+Launch Cursor once and sign in, then quit it. Install the bridge:
+
+```bash
+npx ocx-cursor init --base-url https://cursor-api.example.com/v1
+~/.local/bin/ocx-cursor status
+```
+
+Open Cursor after `status` reports a running service and a healthy gateway.
+
+## How requests move
 
 ```text
-Cursor -> 127.0.0.1:10101 -> OpenCodex on 127.0.0.1:10100 -> provider
+Cursor
+  -> https://cursor-api.example.com/v1
+  -> Cloudflare Tunnel
+  -> OpenCodex Cursor Bridge on 127.0.0.1:10101
+  -> OpenCodex on 127.0.0.1:10100
+  -> your provider
 ```
 
-The gateway requires its generated bearer token on every `/v1/*` request. It binds to `127.0.0.1` unless you change `OCX_CURSOR_HOST`.
+The bridge generates a bearer token during `init`, stores it in Cursor with macOS Safe Storage, and checks it on each `/v1/*` request. The gateway binds to `127.0.0.1` unless you set `OCX_CURSOR_HOST`.
 
-## Model behavior
+The package does not create, edit, or remove your Cloudflare Tunnel.
 
-The bridge reads OpenCodex's active `/v1/models` response and creates stable Cursor aliases:
+## Models and Cursor metadata
+
+The bridge reads the active OpenCodex catalog and adds stable aliases to Cursor:
 
 ```text
 anthropic/claude-sonnet-5 -> opencodex/claude-sonnet-5
 gpt-5.6-sol               -> opencodex/gpt-5.6-sol
 ```
 
-Cursor shows readable names such as `GPT 5.6 Sol`. Reasoning models receive an effort selector. Models with OpenCodex's `priority` service tier receive a Fast toggle.
+Cursor displays provider prefixes where model names overlap. Examples include `Cursor Kimi K3` and `OpenCode Go Kimi K3`. Claude and GPT names stay short.
+
+Reasoning models receive an effort selector. Models that advertise OpenCodex's `priority` service tier receive a Fast toggle. The gateway maps those choices to `reasoning_effort` and `service_tier: priority`.
+
+The installer patches these files:
+
+```text
+/Applications/Cursor.app/Contents/Resources/app/out/vs/workbench/workbench.desktop.main.js
+/Applications/Cursor.app/Contents/Resources/app/out/vs/workbench/workbench.glass.main.js
+```
+
+The patch keeps the model metadata that Cursor would discard. It leaves Cursor's local-agent mode disabled and does not edit either local-agent runtime.
 
-Cursor can send `strict: true` with function schemas that fail strict validation. The gateway changes the flag to `false` before forwarding those requests. It leaves tool names, descriptions, and arguments intact.
+The login service refreshes the catalog every 15 seconds. It waits for Cursor to quit before writing the state database or reapplying a patch after a Cursor update.
 
-## Commands and configuration
+## Commands
 
-| Command | Purpose |
+| Command | Action |
 | --- | --- |
-| `ocx-cursor init` | Install the service, configure Cursor, patch the app, and sync models. Cursor must be closed. |
-| `ocx-cursor install` | Reinstall the service and check app patches. Running Cursor defers app changes until exit. |
-| `ocx-cursor update` | Install the newest npm release and run `install`. |
-| `ocx-cursor sync` | Refresh the active model list. |
-| `ocx-cursor status` | Show service health and pending model sync. |
+| `ocx-cursor init --base-url URL` | Install the service, test the HTTPS endpoint, configure Cursor, and sync models. |
+| `ocx-cursor install` | Reinstall the service and check the two metadata patches. |
+| `ocx-cursor update` | Install the current npm release and restart the service. |
+| `ocx-cursor sync` | Read the active OpenCodex catalog and update Cursor. |
+| `ocx-cursor status` | Print service, gateway, catalog, and pending-sync status. |
 | `ocx-cursor uninstall` | Remove the service, command link, and bridge state. |
 
-`uninstall` does not restore Cursor settings or patched app files. Reinstall Cursor if you want a clean vendor build.
+`uninstall` leaves Cursor's endpoint setting and patched workbench files in place. Reinstall Cursor if you want a signed app without the metadata patch.
+
+## Configuration
 
 | Variable | Default |
 | --- | --- |
-| `OCX_CURSOR_BASE_URL` | `http://127.0.0.1:10101/v1` |
+| `OCX_CURSOR_BASE_URL` | Cursor's stored endpoint |
 | `OCX_CURSOR_HOME` | `~/.opencodex/cursor-bridge` |
 | `OCX_CURSOR_HOST` | `127.0.0.1` |
 | `OCX_CURSOR_PORT` | `10101` |
 | `OCX_BIN` | `~/.local/bin/ocx` |
 
-The bridge reads an OpenCodex service token from `~/.opencodex/service-api-token` when that file exists.
+The gateway exposes `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/responses/compact`, and `POST /v1/messages`.
+
+The bridge reads `~/.opencodex/service-api-token` when OpenCodex uses service authentication.
 
 ## Troubleshooting
 
-| Symptom | Fix |
+| Symptom | Check |
 | --- | --- |
-| Cursor returns 401 | Quit Cursor and rerun `npx ocx-cursor init`. |
-| Models or effort choices are missing | Quit Cursor, run `ocx-cursor sync`, then check `ocx-cursor status`. |
-| A Cursor update removed the patches | Quit Cursor and run `ocx-cursor install`. |
-| The gateway is unavailable | Run `ocx-cursor status` and inspect the logs below. |
-| The bridge cannot find `ocx` | Run `ln -sf "$(command -v ocx)" ~/.local/bin/ocx`. |
+| Cursor returns 401 | Quit Cursor and rerun `npx ocx-cursor init --base-url https://YOUR_HOST/v1`. |
+| The hostname returns 502 | Run `ocx-cursor status`, then check that the tunnel points to port `10101`. |
+| Cloudflare returns 1016 | Run `cloudflared tunnel info ocx-cursor` and check the service. |
+| Models or controls are missing | Quit Cursor and run `ocx-cursor sync`. |
+| A Cursor update removed the patch | Quit Cursor and run `ocx-cursor install`. |
+
+Read the service logs:
 
 ```bash
 tail -n 100 ~/.opencodex/cursor-bridge/service.log
 tail -n 100 ~/.opencodex/cursor-bridge/service.error.log
 ```
 
-The patcher stops when a Cursor update no longer matches its known code structure. It reports the file and mismatch in `service.error.log` without replacing that file.
+The patcher stops if a Cursor update removes its known catalog hook. It records the file and error without replacing that file.
 
 ## Development
 

package/bin/ocx-cursor.mjs

@@ -2,10 +2,11 @@
 
 import { readFile } from "node:fs/promises";
 import process from "node:process";
-import { configureCursorOpenAI } from "../src/cursor-config.mjs";
+import { createInterface } from "node:readline/promises";
+import { configureCursorOpenAI, storedCursorOpenAIBaseUrl } from "../src/cursor-config.mjs";
 import { cursorIsRunning } from "../src/cursor-state.mjs";
 import { installService, prepareInstallSecret, serviceStatus, uninstallService, updateService } from "../src/install.mjs";
-import { cursorLocalBaseUrl, cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
+import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
 import { normalizeBaseUrl, testEndpoint } from "../src/setup.mjs";
 import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
@@ -36,7 +37,19 @@ function argumentValue(name) {
 
 async function requestedBaseUrl() {
   const supplied = argumentValue("--base-url");
-  return normalizeBaseUrl(supplied || cursorOpenAIBaseUrl || cursorLocalBaseUrl);
+  const fallback = cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl();
+  if (supplied) return normalizeBaseUrl(supplied);
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return normalizeBaseUrl(fallback);
+
+  const prompt = fallback
+    ? `HTTPS endpoint [${fallback}]: `
+    : "HTTPS endpoint (for example, https://cursor-api.example.com): ";
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return normalizeBaseUrl((await readline.question(prompt)).trim() || fallback);
+  } finally {
+    readline.close();
+  }
 }
 
 async function pendingCount() {
@@ -63,7 +76,7 @@ function printCursorPatches(result) {
     return;
   }
   const changed = result.cursorPatches.filter(({ status }) => status === "patched").length;
-  process.stdout.write(`Verified ${result.cursorPatches.length} Cursor app patches (${changed} changed).\n`);
+  process.stdout.write(`Verified ${result.cursorPatches.length} Cursor metadata patches (${changed} changed).\n`);
 }
 
 async function main() {
@@ -83,7 +96,7 @@ async function main() {
     process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
     printCursorPatches(installed);
     printSync(await syncNow());
-    process.stdout.write("Endpoint: http://127.0.0.1:10101/v1\n");
+    process.stdout.write("Local gateway: http://127.0.0.1:10101/v1\n");
     return;
   }
   if (command === "init") {
@@ -100,7 +113,7 @@ async function main() {
     try {
       endpoint = await testEndpoint(baseUrl, prepared.secret);
     } catch (error) {
-      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the endpoint and rerun ocx-cursor init.`);
+      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the HTTPS endpoint and rerun ocx-cursor init.`);
     }
     process.stdout.write(`Endpoint is ready (${endpoint.modelCount} models reachable).\n`);
     const configured = await configureCursorOpenAI({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ocx-cursor",
-  "version": "0.5.1",
-  "description": "OpenCodex companion service for Cursor custom models",
+  "version": "1.0.0",
+  "description": "Use OpenCodex models in Cursor through an authenticated HTTPS gateway",
   "keywords": [
     "opencodex",
     "cursor",

package/src/cursor-patch.mjs

@@ -5,15 +5,17 @@ import {
   cursorBundleFiles,
   cursorGlassWorkbenchFile,
   cursorLocalRuntimeFiles,
+  cursorModelMetadataFiles,
   cursorPatchBackupDirectory,
   cursorWorkbenchFile,
 } from "./paths.mjs";
 
-export const cursorPatchMarker = "/*ocx-cursor-model-metadata-v4*/";
+export const cursorPatchMarker = "/*ocx-cursor-model-metadata-v5*/";
 export const legacyCursorPatchMarker = "/*ocx-cursor-model-metadata*/";
 export const cursorLocalModeDisabled = "localMode:!1";
 export const cursorLocalModeEnabled = "localMode:!0";
-export const cursorLocalRuntimePatchMarker = "/*ocx-cursor-local-model-display*/";
+export const cursorLocalRuntimePatchMarker = "/*ocx-cursor-local-model-display-v2*/";
+export const legacyCursorLocalRuntimePatchMarker = "/*ocx-cursor-local-model-display*/";
 export const cursorLocalRuntimeCapabilitiesPatchMarker = "/*ocx-cursor-local-model-capabilities-v3*/";
 export const legacyCursorLocalRuntimeCapabilitiesPatchMarker = "/*ocx-cursor-local-model-capabilities-v2*/";
 
@@ -22,7 +24,7 @@ export function isCursorModelMetadataBundle(file) {
 }
 
 const catalogNormalization = /(?<normalization>\b(?<catalog>[A-Za-z_$][\w$]*)=\k<catalog>\.map\((?<item>[A-Za-z_$][\w$]*)=>(?<plain>[A-Za-z_$][\w$]*)\(\k<item>\)\)),(?=(?<batch>[A-Za-z_$][\w$]*)\(\(\)=>\{this\._reactiveStorageService\.setApplicationUserPersistentStorage\("availableDefaultModels2",\k<catalog>\))/g;
-const previousCatalogInjection = /\/\*ocx-cursor-model-metadata(?:-v[23])?\*\/(?<catalog>[A-Za-z_$][\w$]*)=\k<catalog>\.map\(ocxCursorModel=>\{.*?\}\),(?=(?<batch>[A-Za-z_$][\w$]*)\(\(\)=>\{this\._reactiveStorageService\.setApplicationUserPersistentStorage\("availableDefaultModels2",\k<catalog>\))/g;
+const previousCatalogInjection = /\/\*ocx-cursor-model-metadata(?:-v[234])?\*\/(?<catalog>[A-Za-z_$][\w$]*)=\k<catalog>\.map\(ocxCursorModel=>\{.*?\}\),(?=(?<batch>[A-Za-z_$][\w$]*)\(\(\)=>\{this\._reactiveStorageService\.setApplicationUserPersistentStorage\("availableDefaultModels2",\k<catalog>\))/g;
 const localModelConstructor = /function (?<functionName>[A-Za-z_$][\w$]*)\(e,t\)\{return new (?<modelType>[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*)\(\{modelId:e,displayModelId:e,displayName:null!=t\?t:e,displayNameShort:null!=t\?t:e,aliases:\[\]\}\)\}/g;
 const localRuntimeVisionCapability = /"boolean"==typeof (?<object>[A-Za-z_$][\w$]*)\.supports_vision\?\{supports_vision:\k<object>\.supports_vision\}:\{\}\)/g;
 const localRuntimePickerInput = /toPickerInput\((?<model>[A-Za-z_$][\w$]*)\)\{var [A-Za-z_$][\w$]*;const [A-Za-z_$][\w$]*=this\.modelMetadataById\.get\(\k<model>\.modelId\),(?<capabilities>[A-Za-z_$][\w$]*)=.*?;return\{.*?supportsReasoning:[^,]+,supportsVision:/g;
@@ -40,12 +42,12 @@ function replaceSingleMatch(source, pattern, replacement, label) {
 }
 
 function metadataInjection(catalog) {
-  return `${cursorPatchMarker}${catalog}=${catalog}.map(ocxCursorModel=>{if(!ocxCursorModel.name.startsWith("opencodex/"))return ocxCursorModel;const ocxCursorStored=(this._reactiveStorageService.applicationUserPersistentStorage.availableDefaultModels2??[]).find(ocxCursorCandidate=>ocxCursorCandidate?.name===ocxCursorModel.name);const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=ocxCursorModel.name.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" ");const ocxCursorPrettyLabel=ocxCursorValue=>typeof ocxCursorValue==="string"?ocxCursorValue.split(ocxCursorModel.name).join(ocxCursorDisplayName):ocxCursorValue;const ocxCursorDefinitions=Array.isArray(ocxCursorModel.parameterDefinitions)&&ocxCursorModel.parameterDefinitions.length>0?ocxCursorModel.parameterDefinitions:ocxCursorStored?.parameterDefinitions??[];const ocxCursorVariantSource=Array.isArray(ocxCursorModel.variants)&&ocxCursorModel.variants.length>0?ocxCursorModel.variants:ocxCursorStored?.variants??[];const ocxCursorVariants=ocxCursorVariantSource.map(ocxCursorVariant=>({...ocxCursorVariant,displayName:ocxCursorPrettyLabel(ocxCursorVariant.displayName),displayNameOutsidePicker:ocxCursorPrettyLabel(ocxCursorVariant.displayNameOutsidePicker)}));const ocxCursorLegacySlugs=Array.isArray(ocxCursorModel.legacySlugs)&&ocxCursorModel.legacySlugs.length>0?ocxCursorModel.legacySlugs:ocxCursorStored?.legacySlugs??[];return{...ocxCursorModel,clientDisplayName:ocxCursorDisplayName,inputboxShortModelName:ocxCursorDisplayName,parameterDefinitions:ocxCursorDefinitions,variants:ocxCursorVariants,legacySlugs:ocxCursorLegacySlugs,supportsThinking:void 0!==ocxCursorModel.supportsThinking?ocxCursorModel.supportsThinking:ocxCursorStored?.supportsThinking}}),`;
+  return `${cursorPatchMarker}${catalog}=${catalog}.map(ocxCursorModel=>{if(!ocxCursorModel.name.startsWith("opencodex/"))return ocxCursorModel;const ocxCursorStored=(this._reactiveStorageService.applicationUserPersistentStorage.availableDefaultModels2??[]).find(ocxCursorCandidate=>ocxCursorCandidate?.name===ocxCursorModel.name);const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=ocxCursorStored?.clientDisplayName??((ocxCursorModel.name.startsWith("opencodex/cursor/")?"Cursor ":"")+ocxCursorModel.name.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" "));const ocxCursorPrettyLabel=ocxCursorValue=>typeof ocxCursorValue==="string"?ocxCursorValue.split(ocxCursorModel.name).join(ocxCursorDisplayName):ocxCursorValue;const ocxCursorDefinitions=Array.isArray(ocxCursorModel.parameterDefinitions)&&ocxCursorModel.parameterDefinitions.length>0?ocxCursorModel.parameterDefinitions:ocxCursorStored?.parameterDefinitions??[];const ocxCursorVariantSource=Array.isArray(ocxCursorModel.variants)&&ocxCursorModel.variants.length>0?ocxCursorModel.variants:ocxCursorStored?.variants??[];const ocxCursorVariants=ocxCursorVariantSource.map(ocxCursorVariant=>({...ocxCursorVariant,displayName:ocxCursorPrettyLabel(ocxCursorVariant.displayName),displayNameOutsidePicker:ocxCursorPrettyLabel(ocxCursorVariant.displayNameOutsidePicker)}));const ocxCursorLegacySlugs=Array.isArray(ocxCursorModel.legacySlugs)&&ocxCursorModel.legacySlugs.length>0?ocxCursorModel.legacySlugs:ocxCursorStored?.legacySlugs??[];return{...ocxCursorModel,clientDisplayName:ocxCursorDisplayName,inputboxShortModelName:ocxCursorDisplayName,parameterDefinitions:ocxCursorDefinitions,variants:ocxCursorVariants,legacySlugs:ocxCursorLegacySlugs,supportsThinking:void 0!==ocxCursorModel.supportsThinking?ocxCursorModel.supportsThinking:ocxCursorStored?.supportsThinking}}),`;
 }
 
 export function patchCursorWorkbenchSource(source) {
   if (source.includes(cursorPatchMarker)) return { status: "already-patched", source };
-  if (source.includes(legacyCursorPatchMarker) || source.includes("/*ocx-cursor-model-metadata-v2*/") || source.includes("/*ocx-cursor-model-metadata-v3*/")) {
+  if (source.includes(legacyCursorPatchMarker) || source.includes("/*ocx-cursor-model-metadata-v2*/") || source.includes("/*ocx-cursor-model-metadata-v3*/") || source.includes("/*ocx-cursor-model-metadata-v4*/")) {
     const matches = [...source.matchAll(previousCatalogInjection)];
     if (matches.length !== 1) {
       throw new Error(`Expected one legacy Cursor model metadata hook, found ${matches.length}`);
@@ -98,13 +100,18 @@ export function patchCursorBundleSource(source, options = {}) {
 
 function patchCursorLocalRuntimeDisplayName(source) {
   if (source.includes(cursorLocalRuntimePatchMarker)) return source;
+  if (source.includes(legacyCursorLocalRuntimePatchMarker)) {
+    return source
+      .replace(legacyCursorLocalRuntimePatchMarker, cursorLocalRuntimePatchMarker)
+      .replace('e.startsWith("opencodex/")?e.split("/")', 'e.startsWith("opencodex/")?(e.startsWith("opencodex/cursor/")?"Cursor ":"")+e.split("/")');
+  }
   const matches = [...source.matchAll(localModelConstructor)];
   if (matches.length !== 1) {
     throw new Error(`Expected one Cursor local model constructor, found ${matches.length}`);
   }
   const match = matches[0];
   const { functionName, modelType } = match.groups;
-  const replacement = `function ${functionName}(e,t){${cursorLocalRuntimePatchMarker}const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=null!=t?t:e.startsWith("opencodex/")?e.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" "):e;return new ${modelType}({modelId:e,displayModelId:e,displayName:ocxCursorDisplayName,displayNameShort:ocxCursorDisplayName,aliases:[]})}`;
+  const replacement = `function ${functionName}(e,t){${cursorLocalRuntimePatchMarker}const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=null!=t?t:e.startsWith("opencodex/")?(e.startsWith("opencodex/cursor/")?"Cursor ":"")+e.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" "):e;return new ${modelType}({modelId:e,displayModelId:e,displayName:ocxCursorDisplayName,displayNameShort:ocxCursorDisplayName,aliases:[]})}`;
   return `${source.slice(0, match.index)}${replacement}${source.slice(match.index + match[0].length)}`;
 }
 
@@ -176,15 +183,17 @@ function patchCursorLocalRuntimeProviderCapabilities(source) {
 }
 
 export function patchCursorLocalRuntimeSource(source) {
-  if (source.includes(cursorLocalRuntimeCapabilitiesPatchMarker)) return { status: "already-patched", source };
-  if (source.includes(legacyCursorLocalRuntimeCapabilitiesPatchMarker)) {
-    const upgraded = patchCursorLocalRuntimeProviderCapabilities(source).replace(
+  const displayPatched = patchCursorLocalRuntimeDisplayName(source);
+  if (displayPatched.includes(cursorLocalRuntimeCapabilitiesPatchMarker)) {
+    return { status: displayPatched === source ? "already-patched" : "patched", source: displayPatched };
+  }
+  if (displayPatched.includes(legacyCursorLocalRuntimeCapabilitiesPatchMarker)) {
+    const upgraded = patchCursorLocalRuntimeProviderCapabilities(displayPatched).replace(
       legacyCursorLocalRuntimeCapabilitiesPatchMarker,
       cursorLocalRuntimeCapabilitiesPatchMarker,
     );
     return { status: "patched", source: upgraded };
   }
-  const displayPatched = patchCursorLocalRuntimeDisplayName(source);
   return { status: "patched", source: patchCursorLocalRuntimeCapabilities(displayPatched) };
 }
 
@@ -221,6 +230,13 @@ export async function ensureCursorWorkbenchPatched(options = {}) {
   return await writePatchedFile(file, source, patched, backupDirectory);
 }
 
+export async function ensureCursorModelMetadataPatched(options = {}) {
+  const file = options.file || cursorWorkbenchFile;
+  const backupDirectory = options.backupDirectory || cursorPatchBackupDirectory;
+  const source = await readFile(file, "utf8");
+  return await writePatchedFile(file, source, patchCursorWorkbenchSource(source), backupDirectory);
+}
+
 export async function ensureCursorLocalRuntimesPatched(options = {}) {
   const files = options.files || cursorLocalRuntimeFiles;
   const backupDirectory = options.backupDirectory || cursorPatchBackupDirectory;
@@ -260,6 +276,12 @@ export async function ensureCursorAppPatched(options = {}) {
 }
 
 async function ensureCursorPatchFile(file, localRuntimeFiles, options) {
+  if (options.metadataOnly) {
+    return {
+      file,
+      ...await ensureCursorModelMetadataPatched({ ...options, file }),
+    };
+  }
   if (localRuntimeFiles.has(file)) {
     const [result] = await ensureCursorLocalRuntimesPatched({
       ...options,
@@ -277,6 +299,15 @@ async function ensureCursorPatchFile(file, localRuntimeFiles, options) {
   };
 }
 
+export function startCursorModelMetadataPatchMonitor(options = {}) {
+  return startCursorPatchMonitor({
+    ...options,
+    bundleFiles: options.bundleFiles || cursorModelMetadataFiles,
+    localRuntimeFiles: [],
+    metadataOnly: true,
+  });
+}
+
 export function startCursorPatchMonitor(options = {}) {
   const intervalMs = options.intervalMs || 250;
   const bundleFiles = options.file ? [options.file] : (options.bundleFiles || options.files || cursorBundleFiles);

package/src/cursor-state.mjs

@@ -29,6 +29,11 @@ const displayWords = new Map([
   ["spark", "Spark"],
   ["terra", "Terra"],
 ]);
+const providerDisplayNames = new Map([
+  ["cursor", "Cursor"],
+  ["opencode-go", "OpenCode Go"],
+]);
+const unprefixedProviders = new Set(["anthropic", "openai"]);
 
 function displayWord(value) {
   const known = displayWords.get(value);
@@ -42,12 +47,17 @@ function displayWord(value) {
 }
 
 export function displayNameFor(model) {
-  return model.sourceId.split("/").at(-1).split("-").map(displayWord).join(" ");
+  const provider = model.provider || (model.sourceId.includes("/") ? model.sourceId.split("/", 1)[0] : "openai");
+  const providerDisplayName = providerDisplayNames.get(provider)
+    || provider.split(/[-_]/).map(displayWord).join(" ");
+  const displayName = model.sourceId.split("/").at(-1).split("-").map(displayWord).join(" ");
+  return unprefixedProviders.has(provider) ? displayName : `${providerDisplayName} ${displayName}`;
 }
 
 export function cursorIsRunning() {
   try {
-    execFileSync("pgrep", ["-f", "/Applications/Cursor.app/Contents/"], { stdio: "ignore" });
+    // Match the main binary only: orphaned crashpad helpers under Contents/ outlive the app.
+    execFileSync("pgrep", ["-f", "/Applications/Cursor.app/Contents/MacOS/Cursor"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -165,6 +175,9 @@ function syncSelectedModel(state, catalog) {
   const composer = state.aiSettings?.modelConfig?.composer;
   if (!composer || !Array.isArray(composer.selectedModels)) return;
   const byAlias = new Map(catalog.map((model) => [model.alias, model]));
+  composer.selectedModels = composer.selectedModels.filter((selected) => (
+    typeof selected?.modelId !== "string" || !selected.modelId.startsWith(managedPrefix) || byAlias.has(selected.modelId)
+  ));
   for (const selected of composer.selectedModels) {
     const model = byAlias.get(selected.modelId);
     if (!model || (model.reasoningEfforts.length === 0 && !model.supportsFast)) continue;
@@ -187,7 +200,7 @@ export function applyCatalogToState(state, catalog) {
   const keepUnmanaged = (value) => typeof value !== "string" || !value.startsWith(managedPrefix);
   const existingModels = Array.isArray(state.availableDefaultModels2) ? state.availableDefaultModels2 : [];
   state.availableDefaultModels2 = [
-    ...existingModels.filter((model) => !(model?.isUserAdded && typeof model.name === "string" && model.name.startsWith(managedPrefix))),
+    ...existingModels.filter((model) => !(typeof model?.name === "string" && model.name.startsWith(managedPrefix))),
     ...catalog.map(cursorModel),
   ];
   state.aiSettings ||= {};
@@ -199,6 +212,14 @@ export function applyCatalogToState(state, catalog) {
     ...(Array.isArray(state.aiSettings.modelOverrideEnabled) ? state.aiSettings.modelOverrideEnabled.filter(keepUnmanaged) : []),
     ...aliases,
   ];
+  if (state.aiSettings.modelParameterPreferences && typeof state.aiSettings.modelParameterPreferences === "object") {
+    const activeAliases = new Set(aliases);
+    for (const alias of Object.keys(state.aiSettings.modelParameterPreferences)) {
+      if (alias.startsWith(managedPrefix) && !activeAliases.has(alias)) {
+        delete state.aiSettings.modelParameterPreferences[alias];
+      }
+    }
+  }
   syncSelectedModel(state, catalog);
   return state;
 }

package/src/gateway.mjs

@@ -118,10 +118,15 @@ async function serviceToken() {
   }
 }
 
-function authorized(req, expected) {
-  const supplied = String(req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim();
-  const actual = Buffer.from(supplied);
-  return actual.length === expected.length && timingSafeEqual(actual, expected);
+export function authorized(req, expected) {
+  const supplied = [
+    String(req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim(),
+    String(req.headers["x-api-key"] || "").trim(),
+  ];
+  return supplied.some((value) => {
+    const actual = Buffer.from(value);
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  });
 }
 
 function json(res, status, body) {
@@ -161,7 +166,7 @@ function upstreamHeaders(req, body, token, upstream) {
 
 export function startGateway(options) {
   const host = options.host || gatewayHost;
-  const port = options.port || gatewayPort;
+  const port = options.port ?? gatewayPort;
   const expected = Buffer.from(options.secret);
   let activeRequests = 0;
 
@@ -179,16 +184,29 @@ export function startGateway(options) {
     if (activeRequests >= 8) return json(res, 429, { error: { message: "bridge concurrency limit reached", type: "rate_limit_error" } });
 
     activeRequests += 1;
-    res.once("close", () => { activeRequests = Math.max(0, activeRequests - 1); });
+    let upstreamReq;
+    let downstreamClosed = false;
+    const cancelUpstream = () => {
+      downstreamClosed = true;
+      if (upstreamReq && !upstreamReq.destroyed) upstreamReq.destroy();
+    };
+    req.once("aborted", cancelUpstream);
+    res.once("close", () => {
+      activeRequests = Math.max(0, activeRequests - 1);
+      if (!res.writableEnded) cancelUpstream();
+    });
     try {
       if (route === "GET /v1/models") {
         return json(res, 200, enrichModelList(await activeModels(), catalog));
       }
 
-      const upstream = opencodexEndpoint();
-      const body = rewriteModelAliasBody(await readBody(req), catalog);
-      const token = await serviceToken();
-      const upstreamReq = http.request({
+      const upstream = options.upstream || opencodexEndpoint();
+      const receivedBody = await readBody(req);
+      if (downstreamClosed) return;
+      const body = rewriteModelAliasBody(receivedBody, catalog);
+      const token = options.serviceToken !== undefined ? options.serviceToken : await serviceToken();
+      if (downstreamClosed) return;
+      upstreamReq = http.request({
         hostname: upstream.host,
         port: upstream.port,
         method: req.method,
@@ -204,6 +222,7 @@ export function startGateway(options) {
         });
       });
       upstreamReq.on("error", (error) => {
+        if (downstreamClosed) return;
         if (!res.headersSent) json(res, 502, { error: { message: "OpenCodex upstream unavailable", type: "upstream_error" } });
         else res.destroy(error);
       });

package/src/install.mjs

@@ -4,7 +4,7 @@ import { access, chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readlink,
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ensureCursorAppPatched } from "./cursor-patch.mjs";
+import { ensureCursorModelMetadataPatched } from "./cursor-patch.mjs";
 import { cursorIsRunning } from "./cursor-state.mjs";
 import {
   cliLinkFile,
@@ -13,6 +13,7 @@ import {
   launchAgentFile,
   legacyLaunchAgentFile,
   legacyServiceLabel,
+  cursorModelMetadataFiles,
   secretFile,
   serviceLabel,
   stderrFile,
@@ -167,7 +168,12 @@ function launchAgent(nodePath) {
 export async function installService() {
   await mkdir(dirname(launchAgentFile), { recursive: true });
   const { legacyPlist, secretStatus } = await prepareInstallSecret();
-  const cursorPatches = cursorIsRunning() ? null : await ensureCursorAppPatched();
+  const cursorPatches = cursorIsRunning()
+    ? null
+    : await Promise.all(cursorModelMetadataFiles.map(async (file) => ({
+      file,
+      ...await ensureCursorModelMetadataPatched({ file }),
+    })));
   await copyPackage();
   await installCliLink();
 

package/src/paths.mjs

@@ -17,6 +17,7 @@ export const cursorDatabaseFile = join(homedir(), "Library", "Application Suppor
 export const cursorAppOutDirectory = "/Applications/Cursor.app/Contents/Resources/app/out";
 export const cursorWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.desktop.main.js");
 export const cursorGlassWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.glass.main.js");
+export const cursorModelMetadataFiles = [cursorWorkbenchFile, cursorGlassWorkbenchFile];
 export const cursorLocalRuntimeFiles = [
   "/Applications/Cursor.app/Contents/Resources/app/extensions/cursor-local-agent-runtime/dist/main.js",
   "/Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/main.js",
@@ -39,6 +40,5 @@ export const opencodexConfigFile = join(homedir(), ".opencodex", "config.json");
 export const opencodexServiceTokenFile = join(homedir(), ".opencodex", "service-api-token");
 export const gatewayPort = Number(process.env.OCX_CURSOR_PORT || "10101");
 export const gatewayHost = process.env.OCX_CURSOR_HOST || "127.0.0.1";
-export const cursorLocalBaseUrl = `http://127.0.0.1:${gatewayPort}/v1`;
 export const cursorOpenAIBaseUrl = process.env.OCX_CURSOR_BASE_URL || "";
 export const managedPrefix = "opencodex/";

package/src/service.mjs

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { buildActiveCatalog } from "./catalog.mjs";
-import { startCursorPatchMonitor } from "./cursor-patch.mjs";
+import { startCursorModelMetadataPatchMonitor } from "./cursor-patch.mjs";
 import {
   cursorIsRunning,
   readPendingCatalog,
@@ -59,7 +59,7 @@ export async function runService(options = {}) {
   }
 
   const server = startGateway({ secret, getCatalog: () => catalog, host: options.host, port: options.port });
-  const patchMonitor = startCursorPatchMonitor({
+  const patchMonitor = startCursorModelMetadataPatchMonitor({
     intervalMs: options.cursorPatchIntervalMs,
     shouldPatch: () => !cursorIsRunning(),
     onResult: (result) => {

package/src/setup.mjs

@@ -1,6 +1,6 @@
 export function normalizeBaseUrl(value) {
   if (!value) {
-    throw new Error("Enter an endpoint URL or pass --base-url http://127.0.0.1:10101/v1");
+    throw new Error("Enter an HTTPS endpoint or pass --base-url https://cursor-api.example.com/v1");
   }
 
   const trimmed = value.trim();