ocx-cursor 0.5.2 → 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,98 +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
+```
+
+Create `~/.cloudflared/config.yml`. Replace the UUID, username, and hostname:
+
+```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
 ```
 
-`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 the DNS record and check the ingress rule:
 
-Add the installed command to your shell path if needed:
+```bash
+cloudflared tunnel route dns ocx-cursor cursor-api.example.com
+cloudflared tunnel ingress validate
+cloudflared tunnel ingress rule https://cursor-api.example.com
+```
+
+Start the tunnel at login with Cloudflare's [macOS service command](https://developers.cloudflare.com/tunnel/advanced/local-management/as-a-service/macos/):
 
 ```bash
-export PATH="$HOME/.local/bin:$PATH"
+cloudflared service install
 ```
 
-## What init changes
+This command reads `~/.cloudflared/config.yml`. `sudo cloudflared service install` starts the tunnel at boot and reads `/etc/cloudflared/config.yml` instead.
 
-| 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. |
+Launch Cursor once and sign in, then quit it. Install the bridge:
 
-Requests stay on loopback until OpenCodex sends them to your configured provider:
+```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`.
 
-Active OpenCodex `cursor/*` models are exposed under `opencodex/cursor/*`. The provider is experimental; the bridge cancels its upstream request when Cursor ends the matching client request.
+The package does not create, edit, or remove your Cloudflare Tunnel.
 
-## Model behavior
+## Models and Cursor metadata
 
-The bridge reads OpenCodex's active `/v1/models` response and creates stable Cursor aliases:
+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.2",
-  "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,6 +5,7 @@ import {
   cursorBundleFiles,
   cursorGlassWorkbenchFile,
   cursorLocalRuntimeFiles,
+  cursorModelMetadataFiles,
   cursorPatchBackupDirectory,
   cursorWorkbenchFile,
 } from "./paths.mjs";
@@ -229,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;
@@ -268,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,
@@ -285,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,8 +47,11 @@ function displayWord(value) {
 }
 
 export function displayNameFor(model) {
+  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 model.provider === "cursor" || model.sourceId.startsWith("cursor/") ? `Cursor ${displayName}` : displayName;
+  return unprefixedProviders.has(provider) ? displayName : `${providerDisplayName} ${displayName}`;
 }
 
 export function cursorIsRunning() {

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();