ocx-cursor 0.3.2 → 0.4.0

package/README.md

@@ -212,6 +212,7 @@ The gateway API key is generated during `init` and stored in Cursor with macOS S
 | `ocx-cursor install` | Reinstall or restart the LaunchAgent without changing Cursor's API settings. |
 | `ocx-cursor update` | Download the latest `ocx-cursor` release from npm, reinstall the service, and sync models. |
 | `ocx-cursor sync` | Refresh the active model catalog. The service queues the update while Cursor runs. |
+| `ocx-cursor launch` | Experimentally launch Cursor with live effort and Fast metadata injection. Keep the command running. |
 | `ocx-cursor status` | Show service health, model count, and pending sync state. |
 | `ocx-cursor uninstall` | Remove the LaunchAgent, command link, and bridge home directory. |
 
@@ -232,6 +233,16 @@ The catalog includes models returned by OpenCodex's active `/v1/models` endpoint
 
 Cursor removes custom effort metadata from its database during startup. The LaunchAgent writes that metadata back after Cursor exits, once all Cursor Helper processes have stopped.
 
+### Experimental live model metadata
+
+`ocx-cursor launch` starts Cursor with a random loopback-only debugging port and keeps `opencodex/*` effort and Fast metadata in the live model catalog:
+
+```bash
+ocx-cursor launch
+```
+
+Keep the command running for the lifetime of Cursor. This does not modify `Cursor.app`, but it depends on Cursor's private workbench code and currently supports Cursor 3.14.7. The command stops with a compatibility error when it cannot find the expected catalog hook.
+
 ## Configuration
 
 | Variable | Default | Purpose |

package/bin/ocx-cursor.mjs

@@ -10,6 +10,7 @@ import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
 import { normalizeBaseUrl, testTunnel } from "../src/setup.mjs";
 import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
+import { findAvailableDebugPort, launchCursorForInjection, runRuntimeInjector } from "../src/runtime-injector.mjs";
 
 const usage = `OpenCodex Cursor Bridge
 
@@ -20,6 +21,10 @@ Usage:
   ocx-cursor install    Install and start the macOS companion service
   ocx-cursor update     Install the latest companion release and restart it
   ocx-cursor sync       Sync active OpenCodex models into Cursor
+  ocx-cursor launch [--port <port>]
+                        Launch Cursor with the experimental runtime model hook
+  ocx-cursor inject --port <port> [--reload]
+                        Attach the experimental hook to a debug-enabled Cursor
   ocx-cursor status     Show service and model-sync status
   ocx-cursor uninstall  Stop and remove the companion service
   ocx-cursor service    Run the service in the foreground (internal)
@@ -119,6 +124,30 @@ async function main() {
     printSync(await syncNow());
     return;
   }
+  if (command === "launch") {
+    if (cursorIsRunning()) throw new Error("Quit Cursor before running ocx-cursor launch");
+    const requestedPort = argumentValue("--port");
+    const port = requestedPort ? Number(requestedPort) : await findAvailableDebugPort();
+    const pid = launchCursorForInjection(port);
+    process.stdout.write(`Launched Cursor ${pid} with runtime injection on 127.0.0.1:${port}. Keep this command running.\n`);
+    await runRuntimeInjector({
+      port,
+      onInjection: (count) => process.stdout.write(`Injected ${count} OpenCodex model definitions.\n`),
+      onError: (error) => process.stderr.write(`Runtime injection failed: ${error.message}\n`),
+    });
+    return;
+  }
+  if (command === "inject") {
+    const port = Number(argumentValue("--port"));
+    process.stdout.write(`Attaching runtime injection to Cursor on 127.0.0.1:${port}. Keep this command running.\n`);
+    await runRuntimeInjector({
+      port,
+      reloadExisting: process.argv.includes("--reload"),
+      onInjection: (count) => process.stdout.write(`Injected ${count} OpenCodex model definitions.\n`),
+      onError: (error) => process.stderr.write(`Runtime injection failed: ${error.message}\n`),
+    });
+    return;
+  }
   if (command === "status") {
     const [status, catalog, pending] = await Promise.all([
       serviceStatus(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocx-cursor",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "OpenCodex companion service for Cursor custom models",
   "keywords": [
     "opencodex",

package/src/runtime-injector.mjs

@@ -0,0 +1,209 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { cursorModel } from "./cursor-state.mjs";
+import { loadCatalogSnapshot } from "./sync.mjs";
+
+export const cursorBinary = "/Applications/Cursor.app/Contents/MacOS/Cursor";
+export const cursorWorkbenchBundle = "/Applications/Cursor.app/Contents/Resources/app/out/vs/workbench/workbench.desktop.main.js";
+export const cursorWorkbenchUrl = "vscode-file://vscode-app/Applications/Cursor.app/Contents/Resources/app/out/vs/workbench/workbench.desktop.main.js";
+
+const catalogStorageAnchor = "c=c.map(z=>XTt(z)),bp(()=>{this._reactiveStorageService.setApplicationUserPersistentStorage(\"availableDefaultModels2\",c)";
+const breakpointOffset = "c=c.map(z=>XTt(z)),".length;
+
+export function findCatalogHookLocation(source) {
+  const index = source.indexOf(catalogStorageAnchor);
+  if (index === -1) throw new Error("This Cursor version does not contain the supported model catalog hook");
+  if (source.indexOf(catalogStorageAnchor, index + 1) !== -1) {
+    throw new Error("Cursor model catalog hook is ambiguous");
+  }
+  const lines = source.slice(0, index + breakpointOffset).split("\n");
+  return {
+    lineNumber: lines.length - 1,
+    columnNumber: lines.at(-1).length,
+  };
+}
+
+export function buildRuntimeModelPatches(catalog) {
+  return Object.fromEntries(catalog.map((model) => {
+    const value = cursorModel(model);
+    return [value.name, value];
+  }));
+}
+
+export function catalogPatchExpression(patches) {
+  return `(() => {
+    const patches = ${JSON.stringify(patches)};
+    let count = 0;
+    for (const model of c) {
+      const patch = patches[model.name];
+      if (!patch) continue;
+      count += 1;
+      Object.assign(model, patch);
+    }
+    return count;
+  })()`;
+}
+
+class CdpConnection {
+  constructor(url) {
+    this.url = url;
+    this.nextId = 0;
+    this.pending = new Map();
+    this.listeners = new Set();
+  }
+
+  async open() {
+    this.socket = new WebSocket(this.url);
+    this.socket.onmessage = ({ data }) => this.handleMessage(JSON.parse(data));
+    await new Promise((resolve, reject) => {
+      this.socket.onopen = resolve;
+      this.socket.onerror = reject;
+    });
+    this.socket.onclose = () => {
+      for (const { reject } of this.pending.values()) reject(new Error("Cursor debugger disconnected"));
+      this.pending.clear();
+    };
+    return this;
+  }
+
+  call(method, params = {}) {
+    return new Promise((resolve, reject) => {
+      const id = ++this.nextId;
+      this.pending.set(id, { resolve, reject });
+      this.socket.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  onEvent(listener) {
+    this.listeners.add(listener);
+  }
+
+  handleMessage(message) {
+    if (message.id) {
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+      if (message.error) pending.reject(new Error(message.error.message));
+      else pending.resolve(message.result);
+      return;
+    }
+    for (const listener of this.listeners) listener(message);
+  }
+
+  close() {
+    this.socket?.close();
+  }
+}
+
+async function cursorTargets(port) {
+  const response = await fetch(`http://127.0.0.1:${port}/json/list`, {
+    signal: AbortSignal.timeout(1000),
+  });
+  if (!response.ok) throw new Error(`Cursor debugger returned HTTP ${response.status}`);
+  return await response.json();
+}
+
+async function attachCatalogHook(target, options) {
+  const connection = await new CdpConnection(target.webSocketDebuggerUrl).open();
+  let breakpointId;
+  connection.onEvent((message) => {
+    if (message.method !== "Debugger.paused" || !message.params.hitBreakpoints.includes(breakpointId)) return;
+    const frame = message.params.callFrames[0];
+    void (async () => {
+      try {
+        const patches = buildRuntimeModelPatches(await loadCatalogSnapshot());
+        const result = await connection.call("Debugger.evaluateOnCallFrame", {
+          callFrameId: frame.callFrameId,
+          expression: catalogPatchExpression(patches),
+          returnByValue: true,
+        });
+        if (result.exceptionDetails) throw new Error(result.exceptionDetails.text || "Catalog injection failed");
+        options.onInjection?.(Number(result.result.value || 0), target);
+      } catch (error) {
+        options.onError?.(error, target);
+      } finally {
+        await connection.call("Debugger.resume").catch(() => {});
+      }
+    })();
+  });
+
+  await connection.call("Debugger.enable");
+  const breakpoint = await connection.call("Debugger.setBreakpointByUrl", {
+    url: cursorWorkbenchUrl,
+    lineNumber: options.location.lineNumber,
+    columnNumber: options.location.columnNumber,
+  });
+  breakpointId = breakpoint.breakpointId;
+  if (options.reload) await connection.call("Page.reload");
+  return connection;
+}
+
+export async function runRuntimeInjector(options = {}) {
+  const port = Number(options.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("A valid Cursor debugging port is required");
+  const source = await readFile(options.bundleFile || cursorWorkbenchBundle, "utf8");
+  const location = findCatalogHookLocation(source);
+  const connections = new Map();
+  let foundTarget = false;
+  let missingPolls = 0;
+
+  try {
+    while (missingPolls < (options.maxMissingPolls || 10)) {
+      let targets = [];
+      try {
+        targets = await cursorTargets(port);
+        missingPolls = 0;
+      } catch {
+        missingPolls += 1;
+      }
+
+      for (const target of targets.filter(({ type }) => type === "page")) {
+        if (connections.has(target.id)) continue;
+        const connection = await attachCatalogHook(target, {
+          location,
+          reload: options.reloadExisting === true && !foundTarget,
+          onInjection: options.onInjection,
+          onError: options.onError,
+        });
+        connections.set(target.id, connection);
+        foundTarget = true;
+      }
+
+      for (const [id, connection] of connections) {
+        if (targets.some((target) => target.id === id)) continue;
+        connection.close();
+        connections.delete(id);
+      }
+      await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs || 500));
+    }
+  } finally {
+    for (const connection of connections.values()) connection.close();
+  }
+
+  if (!foundTarget) throw new Error(`No Cursor renderer appeared on debugging port ${port}`);
+}
+
+export function launchCursorForInjection(port, options = {}) {
+  const child = spawn(options.cursorBinary || cursorBinary, [
+    "--remote-debugging-address=127.0.0.1",
+    `--remote-debugging-port=${port}`,
+  ], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  return child.pid;
+}
+
+export async function findAvailableDebugPort() {
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  if (!address || typeof address === "string") throw new Error("Could not allocate a Cursor debugging port");
+  return address.port;
+}