clawdex-mobile 5.1.3-internal.11 → 5.1.3-internal.13

package/README.md

@@ -25,7 +25,7 @@ Before you start:
 - `git`
 - `codex` in `PATH` for the default Codex flow
 - `opencode` in `PATH` if you want the OpenCode flow
-- `cursor-app-server` in `PATH` if you want the Cursor SDK flow
+- Cursor app-server is bundled with `clawdex-mobile` for the Cursor SDK flow
 
 Install the mobile app:
 
@@ -59,12 +59,11 @@ OpenCode and Cursor can run beside Codex from the same bridge.
 
 ```bash
 npm install -g opencode-ai
-npm install -g @clawdex/cursor-app-server
 npm install -g clawdex-mobile@latest
 clawdex init --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` to `.env.secure`, so the mobile app can control the selected harnesses from one bridge. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` to `.env.secure`, so the mobile app can control the selected harnesses from one bridge. When Cursor is selected, `clawdex init` uses the bundled `cursor-app-server`, asks for the Cursor API key, and saves it in `.env.secure`.
 
 Notes:
 

package/bin/clawdex.js

@@ -10,11 +10,11 @@ function printUsage() {
   console.log(`Usage: clawdex <command> [options]
 
 Commands:
-  init [--no-start] [--engine codex|opencode]
+  init [--no-start] [--engine codex|opencode|cursor] [--engines codex,opencode,cursor]
       Run interactive bridge onboarding and secure setup.
       By default, this also starts the secure bridge in the background.
       Use --no-start to configure only.
-      Use --engine to set the preferred backend written to .env.secure.
+      Use --engine or --engines to choose the backend harnesses written to .env.secure.
 
   stop
       Stop bridge services for this project.

package/docs/setup-and-operations.md

@@ -18,7 +18,7 @@ From a source checkout, the equivalent command is:
 npm run setup:wizard -- --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` into `.env.secure`, so the bridge starts the selected backends and the mobile app can control them from one UI. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` into `.env.secure`, so the bridge starts the selected backends and the mobile app can control them from one UI. When Cursor is selected, `clawdex init` uses the bundled `cursor-app-server`, asks for the Cursor API key, and saves it in `.env.secure`.
 
 If you want only one harness, use `--engine codex`, `--engine opencode`, or `--engine cursor`.
 
@@ -199,7 +199,7 @@ npm run teardown -- --yes
 | `BRIDGE_ACTIVE_ENGINE` | internal preferred routing backend used when multiple harnesses are enabled |
 | `BRIDGE_ENABLED_ENGINES` | selected harnesses to expose (`codex`, `opencode`, `cursor`, or a comma-separated mix) |
 | `OPENCODE_CLI_BIN` | opencode executable for dual-engine startup |
-| `CURSOR_APP_SERVER_BIN` | Cursor app-server executable, usually `cursor-app-server` |
+| `CURSOR_APP_SERVER_BIN` | Cursor app-server executable, usually the `cursor-app-server` binary bundled with `clawdex-mobile` |
 | `CURSOR_API_KEY` | Cursor API key used by the Cursor SDK harness; collected by `clawdex init` when Cursor is selected |
 | `CURSOR_MODEL` | optional Cursor model id for non-interactive host defaults; normal mobile chats send the selected model |
 | `BRIDGE_OPENCODE_HOST` | loopback host for spawned opencode server |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.1.3-internal.11",
-  "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
+  "version": "5.1.3-internal.13",
+  "description": "Private-network mobile bridge and CLI for Codex, OpenCode, and Cursor",
   "keywords": [
     "codex",
     "opencode",
@@ -20,10 +20,13 @@
     "access": "public"
   },
   "dependencies": {
-    "qrcode-terminal": "^0.12.0"
+    "@cursor/sdk": "1.0.11",
+    "qrcode-terminal": "^0.12.0",
+    "zod": "^3.25.0"
   },
   "bin": {
-    "clawdex": "./bin/clawdex.js"
+    "clawdex": "bin/clawdex.js",
+    "cursor-app-server": "services/cursor-app-server/dist/stdio.js"
   },
   "files": [
     "CHANGELOG.md",
@@ -38,6 +41,9 @@
     "scripts/setup-wizard.sh",
     "scripts/start-bridge-secure.js",
     "scripts/stop-services.sh",
+    "services/cursor-app-server/dist",
+    "services/cursor-app-server/README.md",
+    "services/cursor-app-server/package.json",
     "services/rust-bridge/Cargo.lock",
     "services/rust-bridge/Cargo.toml",
     "services/rust-bridge/src",
@@ -67,6 +73,7 @@
     "secure:bridge:dev": "node ./scripts/start-bridge-secure.js --dev",
     "bridge:ts": "BRIDGE_WORKDIR=$(pwd) npm run -w @codex/mac-bridge dev",
     "version:sync": "node scripts/sync-versions.js",
+    "prepack": "npm run build -w @clawdex/cursor-app-server",
     "build": "npm run --workspaces build",
     "typecheck": "npm run --workspaces typecheck",
     "lint": "npm run --workspaces lint",

package/scripts/setup-wizard.sh

@@ -1296,29 +1296,20 @@ ensure_cursor_app_server() {
   local existing_api_key=""
   local existing_model=""
   local provided_api_key="${CURSOR_API_KEY:-}"
+  local resolved_cursor_app_server_bin=""
 
-  if [[ -f "$ROOT_DIR/services/cursor-app-server/package.json" ]]; then
-    info "Building Cursor app-server package."
-    npm run build -w @clawdex/cursor-app-server
-    hash -r
+  if [[ -n "${CURSOR_APP_SERVER_BIN:-}" ]]; then
+    resolved_cursor_app_server_bin="$CURSOR_APP_SERVER_BIN"
+  elif command -v cursor-app-server >/dev/null 2>&1; then
+    resolved_cursor_app_server_bin="$(command -v cursor-app-server)"
   fi
 
-  while ! command -v cursor-app-server >/dev/null 2>&1; do
-    warn "Cursor app-server command not found in PATH."
-    if confirm_prompt "Try installing @clawdex/cursor-app-server via npm now?" "N"; then
-      if npm install -g @clawdex/cursor-app-server; then
-        hash -r
-      else
-        warn "Automatic install failed."
-      fi
-    fi
-
-    if ! command -v cursor-app-server >/dev/null 2>&1 && ! confirm_prompt "Retry Cursor app-server check?" "Y"; then
-      abort_wizard "Install @clawdex/cursor-app-server and rerun: clawdex init --engine cursor"
-    fi
-  done
+  if [[ -z "$resolved_cursor_app_server_bin" ]]; then
+    abort_wizard "cursor-app-server was not found. Upgrade clawdex-mobile so npm links the bundled command, then rerun: clawdex init --engine cursor"
+  fi
 
-  ok "Found cursor-app-server: $(command -v cursor-app-server)"
+  CURSOR_APP_SERVER_BIN="$resolved_cursor_app_server_bin"
+  ok "Found cursor-app-server: $CURSOR_APP_SERVER_BIN"
 
   existing_api_key="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_API_KEY")"
   existing_model="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_MODEL")"
@@ -1743,8 +1734,7 @@ ensure_core_tools
 if has_packaged_bridge_binary; then
   ok "Found packaged Rust bridge binary for this host."
 else
-  info "No packaged bridge binary found for this host. Falling back to local Rust build."
-  ensure_local_rust_build_toolchain
+  abort_wizard "No packaged bridge binary found for this host. Reinstall clawdex-mobile so npm installs the bundled bridge binary, then rerun setup."
 fi
 
 section "Config handling"

package/scripts/start-bridge-secure.js

@@ -377,48 +377,6 @@ function commandExists(command) {
   return result.status === 0;
 }
 
-function walkFiles(directory) {
-  const entries = fs.readdirSync(directory, { withFileTypes: true });
-  const files = [];
-
-  for (const entry of entries) {
-    const entryPath = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...walkFiles(entryPath));
-      continue;
-    }
-    if (entry.isFile()) {
-      files.push(entryPath);
-    }
-  }
-
-  return files;
-}
-
-function isBuiltBinaryFresh(packageDir, binaryPath) {
-  if (!fs.existsSync(binaryPath)) {
-    return false;
-  }
-
-  const binaryMtime = fs.statSync(binaryPath).mtimeMs;
-  const watchPaths = [
-    path.join(packageDir, "services", "rust-bridge", "Cargo.toml"),
-    path.join(packageDir, "services", "rust-bridge", "Cargo.lock"),
-  ];
-  const sourceDir = path.join(packageDir, "services", "rust-bridge", "src");
-
-  if (fs.existsSync(sourceDir)) {
-    watchPaths.push(...walkFiles(sourceDir));
-  }
-
-  return watchPaths.every((watchPath) => {
-    if (!fs.existsSync(watchPath)) {
-      return true;
-    }
-    return fs.statSync(watchPath).mtimeMs <= binaryMtime;
-  });
-}
-
 function printMissingCompilerHint() {
   if (process.platform === "win32") {
     console.error("Install Visual Studio Build Tools (Desktop development with C++) and Rust, then retry.");
@@ -615,20 +573,15 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
   }
 
   const builtBinary = builtBinaryPath(packageDir, os.platform(), buildProfile);
-  if (isBuiltBinaryFresh(packageDir, builtBinary)) {
-    ensureExecutable(builtBinary);
-    return {
-      command: builtBinary,
-      args: [],
-      cwd: workspaceDir,
-      env,
-      healthTimeoutMs: defaultHealthTimeoutMs,
-    };
+
+  if (!forceSourceBuild) {
+    console.error("error: no packaged bridge binary was found for this host.");
+    console.error("Reinstall a published clawdex-mobile package with bundled bridge binaries.");
+    process.exit(1);
   }
 
   if (!commandExists("cargo")) {
-    console.error("error: no packaged bridge binary was found for this host, and cargo is not installed.");
-    console.error("Reinstall a published clawdex-mobile package with bundled bridge binaries, or install Rust and retry.");
+    console.error("error: CLAWDEX_BRIDGE_FORCE_SOURCE_BUILD=true was set, but cargo is not installed.");
     process.exit(1);
   }
 

package/services/cursor-app-server/README.md

@@ -0,0 +1,39 @@
+# @clawdex/cursor-app-server
+
+App-server shaped JSON-RPC adapter for Cursor agents.
+
+This package is intentionally strict. It does not fall back to Codex, OpenCode,
+mock agents, empty model lists, or implicit workspace directories. Missing
+Cursor runtime configuration is surfaced as an error.
+
+## Contract
+
+Supported JSON-RPC methods:
+
+- `thread/list`
+- `thread/loaded/list`
+- `thread/read`
+- `thread/start`
+- `turn/start`
+- `turn/interrupt`
+- `model/list`
+
+Emitted notifications:
+
+- `thread/started`
+- `thread/status/changed`
+- `turn/started`
+- `item/agentMessage/delta`
+- `item/reasoning/textDelta`
+- `item/started`
+- `turn/completed`
+
+## Run
+
+```bash
+CURSOR_WORKDIR="$PWD" CURSOR_MODEL="cursor-small" CURSOR_API_KEY="..." cursor-app-server
+```
+
+`CURSOR_WORKDIR` is required for local agents. `CURSOR_MODEL` is required unless
+a request provides an explicit model. `CURSOR_API_KEY` is required for Cursor SDK
+operations and model listing.

package/services/cursor-app-server/dist/appServer.d.ts

@@ -0,0 +1,52 @@
+import type { AppServerNotification, CursorAppServerOptions, CursorStreamMessage } from './types.js';
+type NotificationListener = (notification: AppServerNotification) => void;
+export declare class CursorAppServer {
+    private readonly runtime;
+    private readonly driver;
+    private readonly configuredCwd;
+    private readonly apiKey;
+    private readonly defaultModel;
+    private readonly cursorProjectsDir;
+    private readonly events;
+    private readonly liveThreads;
+    private readonly knownThreadCwds;
+    private readonly knownThreadStoreCwds;
+    constructor(options: CursorAppServerOptions);
+    onNotification(listener: NotificationListener): () => void;
+    request(method: string, params?: unknown): Promise<Record<string, unknown>>;
+    private listThreads;
+    private readThread;
+    private listLoadedThreads;
+    private startThread;
+    private startTurn;
+    private interruptTurn;
+    private listModels;
+    private initialize;
+    private getOrResumeLiveThread;
+    private consumeRun;
+    private applyStreamMessage;
+    private applyRunResult;
+    private findOrCreateTextItem;
+    private upsertToolCallItem;
+    private findAssistantItem;
+    private requireCwd;
+    private resolveKnownThreadWorkspace;
+    private rememberAgentCwd;
+    private listKnownWorkspaceCwds;
+    private resolveAgentEffectiveCwd;
+    private readPersistedThread;
+    private resumePersistedThread;
+    private candidateStoreCwds;
+    private requireModel;
+    private requireTurnModel;
+    private configuredModelOrUndefined;
+    private latestPersistedRunModel;
+    private requireApiKey;
+    private buildUserMessage;
+    private buildUserThreadContent;
+    private toModelSelection;
+    private emit;
+}
+export declare function createCursorAppServerFromEnv(env?: NodeJS.ProcessEnv): CursorAppServer;
+export declare function cursorStreamMessageText(message: CursorStreamMessage): string;
+export {};