clawdex-mobile 5.1.3-internal.10 → 5.1.3-internal.12

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.10",
-  "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
+  "version": "5.1.3-internal.12",
+  "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-secure-dev.sh

@@ -13,7 +13,12 @@ MOBILE_ENV_EXAMPLE="$ROOT_DIR/apps/mobile/.env.example"
 BRIDGE_ACTIVE_ENGINE="${BRIDGE_ACTIVE_ENGINE:-codex}"
 BRIDGE_ENABLED_ENGINES="${BRIDGE_ENABLED_ENGINES:-$BRIDGE_ACTIVE_ENGINE}"
 OPENCODE_CLI_BIN="${OPENCODE_CLI_BIN:-opencode}"
-CURSOR_APP_SERVER_BIN="${CURSOR_APP_SERVER_BIN:-cursor-app-server}"
+BUNDLED_CURSOR_APP_SERVER_BIN="$PACKAGE_ROOT/services/cursor-app-server/dist/stdio.js"
+if [[ -z "${CURSOR_APP_SERVER_BIN:-}" && -x "$BUNDLED_CURSOR_APP_SERVER_BIN" ]]; then
+  CURSOR_APP_SERVER_BIN="$BUNDLED_CURSOR_APP_SERVER_BIN"
+else
+  CURSOR_APP_SERVER_BIN="${CURSOR_APP_SERVER_BIN:-cursor-app-server}"
+fi
 CURSOR_API_KEY="${CURSOR_API_KEY:-}"
 CURSOR_MODEL="${CURSOR_MODEL:-}"
 BRIDGE_CONNECT_URL=""
@@ -353,6 +358,7 @@ if has_local_mobile_workspace; then
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_MAC_BRIDGE_TOKEN" "$BRIDGE_TOKEN"
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_ALLOW_QUERY_TOKEN_AUTH" "true"
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE" "true"
+  chmod 600 "$MOBILE_ENV_FILE"
 fi
 
 echo "Secure dev setup complete."

package/scripts/setup-wizard.sh

@@ -1296,29 +1296,39 @@ ensure_cursor_app_server() {
   local existing_api_key=""
   local existing_model=""
   local provided_api_key="${CURSOR_API_KEY:-}"
+  local bundled_cursor_app_server_bin="$PACKAGE_ROOT/services/cursor-app-server/dist/stdio.js"
+  local resolved_cursor_app_server_bin=""
 
-  if [[ -f "$ROOT_DIR/services/cursor-app-server/package.json" ]]; then
+  if [[ -f "$PACKAGE_ROOT/services/cursor-app-server/src/stdio.ts" ]]; then
     info "Building Cursor app-server package."
     npm run build -w @clawdex/cursor-app-server
     hash -r
   fi
 
-  while ! command -v cursor-app-server >/dev/null 2>&1; do
+  if command -v cursor-app-server >/dev/null 2>&1; then
+    resolved_cursor_app_server_bin="$(command -v cursor-app-server)"
+  elif [[ -x "$bundled_cursor_app_server_bin" ]]; then
+    resolved_cursor_app_server_bin="$bundled_cursor_app_server_bin"
+  fi
+
+  while [[ -z "$resolved_cursor_app_server_bin" ]]; 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
+    warn "Cursor app-server is bundled with clawdex-mobile. Reinstall or upgrade clawdex-mobile, then rerun setup."
+
+    if ! confirm_prompt "Retry Cursor app-server check?" "Y"; then
+      abort_wizard "Install or upgrade clawdex-mobile and rerun: clawdex init --engine cursor"
     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"
+    hash -r
+    if command -v cursor-app-server >/dev/null 2>&1; then
+      resolved_cursor_app_server_bin="$(command -v cursor-app-server)"
+    elif [[ -x "$bundled_cursor_app_server_bin" ]]; then
+      resolved_cursor_app_server_bin="$bundled_cursor_app_server_bin"
     fi
   done
 
-  ok "Found cursor-app-server: $(command -v cursor-app-server)"
+  CURSOR_APP_SERVER_BIN="${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")"

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 {};