clawdex-mobile 5.1.3-internal.8 → 5.2.0

package/scripts/setup-wizard.sh

@@ -1129,11 +1129,7 @@ choose_config_action() {
 }
 
 choose_bridge_network_mode() {
-  if [[ "${CODESPACES:-}" == "true" ]]; then
-    menu_select "Bridge network mode" "GitHub Codespaces" "Local (LAN)" "Tailscale"
-  else
-    menu_select "Bridge network mode" "Local (LAN)" "Tailscale" "GitHub Codespaces"
-  fi
+  menu_select "Bridge network mode" "Local (LAN)" "Tailscale"
   case "$MENU_RESULT" in
     "Local (LAN)")
       NETWORK_MODE="local"
@@ -1143,10 +1139,6 @@ choose_bridge_network_mode() {
       NETWORK_MODE="tailscale"
       info "Tailscale mode selected."
       ;;
-    "GitHub Codespaces")
-      NETWORK_MODE="codespaces"
-      info "GitHub Codespaces mode selected."
-      ;;
     *)
       abort_wizard "Unexpected bridge network mode."
       ;;
@@ -1196,12 +1188,6 @@ infer_network_mode_from_host() {
 
 infer_network_mode() {
   local host="$1"
-  local connect_url="$2"
-  connect_url="$(printf '%s' "$connect_url" | tr -d '[:space:]')"
-  if [[ "$connect_url" == https://*.app.github.dev* ]]; then
-    printf '%s' "codespaces"
-    return 0
-  fi
   infer_network_mode_from_host "$host"
 }
 
@@ -1307,32 +1293,40 @@ ensure_opencode_cli() {
 }
 
 ensure_cursor_app_server() {
+  local existing_app_server_bin=""
   local existing_api_key=""
   local existing_model=""
+  local provided_app_server_bin="${CURSOR_APP_SERVER_BIN:-}"
   local provided_api_key="${CURSOR_API_KEY:-}"
+  local resolved_cursor_app_server_bin=""
+
+  existing_app_server_bin="$(extract_env_value "$SECURE_ENV_FILE" "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 "$provided_app_server_bin" ]]; then
+    resolved_cursor_app_server_bin="$CURSOR_APP_SERVER_BIN"
+  elif [[ -n "$existing_app_server_bin" ]]; then
+    resolved_cursor_app_server_bin="$existing_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 [[ -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
 
-    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"
+  if [[ "$resolved_cursor_app_server_bin" == */* ]]; then
+    if [[ ! -x "$resolved_cursor_app_server_bin" ]]; then
+      abort_wizard "cursor-app-server was configured as '$resolved_cursor_app_server_bin', but that file is not executable."
     fi
-  done
+  elif ! command -v "$resolved_cursor_app_server_bin" >/dev/null 2>&1; then
+    abort_wizard "cursor-app-server command '$resolved_cursor_app_server_bin' was not found in PATH."
+  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"
+  if [[ "$CURSOR_APP_SERVER_BIN" != "$existing_app_server_bin" ]]; then
+    CURSOR_CONFIG_NEEDS_WRITE="true"
+  fi
 
   existing_api_key="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_API_KEY")"
   existing_model="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_MODEL")"
@@ -1349,12 +1343,20 @@ ensure_cursor_app_server() {
       ok "Cursor API key: configured in secure bridge config."
     fi
     if [[ "$FLOW" == "manual" ]] && confirm_prompt "Replace saved Cursor API key now?" "N"; then
+      print_note_box "Cursor API key" "Create a Cursor account API key from Cursor Dashboard > Integrations > User API Keys, then paste it here.
+Cursor docs: https://docs.cursor.com/en/cli/reference/authentication
+
+This is the Cursor agent/SDK key used by Clawdex. It is not the OpenAI, Anthropic, or other provider key configured inside the Cursor editor."
       CURSOR_API_KEY="$(prompt_secret_value "Enter Cursor API key:")"
       CURSOR_CONFIG_NEEDS_WRITE="true"
       ok "Cursor API key will be updated in $SECURE_ENV_FILE."
     fi
   else
     warn "Cursor requires a Cursor API key on the bridge host."
+    print_note_box "Cursor API key" "Create a Cursor account API key from Cursor Dashboard > Integrations > User API Keys, then paste it here.
+Cursor docs: https://docs.cursor.com/en/cli/reference/authentication
+
+This is the Cursor agent/SDK key used by Clawdex. It is not the OpenAI, Anthropic, or other provider key configured inside the Cursor editor."
     if ! confirm_prompt "Add Cursor API key now?" "Y"; then
       abort_wizard "Cursor was selected but CURSOR_API_KEY is missing. Re-run clawdex init after creating a Cursor API key."
     fi
@@ -1363,7 +1365,7 @@ ensure_cursor_app_server() {
     ok "Cursor API key will be saved in $SECURE_ENV_FILE."
   fi
 
-  export CURSOR_API_KEY CURSOR_MODEL
+  export CURSOR_APP_SERVER_BIN CURSOR_API_KEY CURSOR_MODEL
 }
 
 ensure_selected_engine_clis() {
@@ -1641,16 +1643,6 @@ Steps:
 - Scan the bridge token QR from the bridge terminal."
 }
 
-print_phone_codespaces_note() {
-  print_note_box "Phone setup (GitHub Codespaces)" "Use the forwarded HTTPS bridge URL from this codespace.
-
-Steps:
-- Keep the codespace running while using Clawdex.
-- The bridge startup script will try to make bridge ports public automatically on each start.
-- Pair in the mobile app with the shown HTTPS bridge URL and bridge token.
-- If pairing fails after a codespace restart, rerun the bridge start command or set the bridge + preview forwarded ports public again with 'gh codespace ports visibility ...'."
-}
-
 confirm_phone_local_quickstart() {
   local note_shown="false"
 
@@ -1721,34 +1713,6 @@ confirm_phone_local_ready() {
   confirm_phone_local_manual
 }
 
-confirm_phone_codespaces_ready() {
-  print_phone_codespaces_note
-  if [[ "$FLOW" == "quickstart" ]]; then
-    if ! confirm_prompt "Will you pair from the forwarded HTTPS bridge URL shown after startup?" "Y"; then
-      abort_wizard "Use the forwarded GitHub Codespaces bridge URL, then rerun: npm run setup:wizard"
-    fi
-    return 0
-  fi
-
-  menu_select "Phone Codespaces status" \
-    "Ready to pair from forwarded URL" \
-    "Show instructions again" \
-    "Abort"
-
-  case "$MENU_RESULT" in
-    "Ready to pair from forwarded URL")
-      return 0
-      ;;
-    "Show instructions again")
-      confirm_phone_codespaces_ready
-      return 0
-      ;;
-    *)
-      abort_wizard "Use the forwarded GitHub Codespaces bridge URL, then rerun: npm run setup:wizard"
-      ;;
-  esac
-}
-
 confirm_phone_network_ready() {
   case "$NETWORK_MODE" in
     tailscale)
@@ -1757,9 +1721,6 @@ confirm_phone_network_ready() {
     local)
       confirm_phone_local_ready
       ;;
-    codespaces)
-      confirm_phone_codespaces_ready
-      ;;
     *)
       abort_wizard "Unknown network mode '$NETWORK_MODE'."
       ;;
@@ -1798,8 +1759,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"
@@ -1846,14 +1806,6 @@ if [[ "$CONFIG_ACTION" != "keep" ]]; then
       BRIDGE_HOST="$(resolve_local_ip)"
       ok "Local LAN IPv4 detected: $BRIDGE_HOST"
       ;;
-    codespaces)
-      section "GitHub Codespaces connectivity"
-      if [[ "${CODESPACES:-}" != "true" ]]; then
-        warn "GitHub Codespaces env was not detected. This mode expects to run inside an active codespace."
-      fi
-      BRIDGE_HOST="127.0.0.1"
-      ok "Codespaces mode will use forwarded HTTPS bridge URLs."
-      ;;
     *)
       abort_wizard "Unknown network mode '$NETWORK_MODE'."
       ;;
@@ -1870,7 +1822,7 @@ else
     NETWORK_MODE="$(infer_network_mode "$BRIDGE_HOST" "$BRIDGE_CONNECT_URL")"
   fi
 
-  if ([[ "$BRIDGE_HOST" == "0.0.0.0" ]] || [[ "$BRIDGE_HOST" == "::" ]] || [[ "$BRIDGE_HOST" == "[::]" ]]) && [[ "$NETWORK_MODE" != "codespaces" ]]; then
+  if [[ "$BRIDGE_HOST" == "0.0.0.0" ]] || [[ "$BRIDGE_HOST" == "::" ]] || [[ "$BRIDGE_HOST" == "[::]" ]]; then
     warn "Existing BRIDGE_HOST=$BRIDGE_HOST is a bind address, not a phone-connectable host."
     if [[ "$NETWORK_MODE" == "tailscale" ]]; then
       section "Tailscale connectivity"
@@ -1900,8 +1852,6 @@ section "Phone pairing"
 confirm_phone_network_ready
 if [[ "$NETWORK_MODE" == "tailscale" ]]; then
   ok "Phone Tailscale readiness confirmed."
-elif [[ "$NETWORK_MODE" == "codespaces" ]]; then
-  ok "Phone Codespaces pairing readiness confirmed."
 else
   ok "Phone local network readiness confirmed."
 fi

package/scripts/start-bridge-secure.js

@@ -128,33 +128,13 @@ function normalizeBaseUrl(rawUrl) {
   }
 }
 
-function isCodespacesMode(env) {
-  const networkMode = readNonEmptyEnv(env, "BRIDGE_NETWORK_MODE").toLowerCase();
-  const rawCodespaces = readNonEmptyEnv(env, "CODESPACES").toLowerCase();
-  return networkMode === "codespaces" || rawCodespaces === "true";
-}
-
 function resolveBridgeBuildProfile(env) {
   const explicitProfile = readNonEmptyEnv(env, "CLAWDEX_BRIDGE_BUILD_PROFILE").toLowerCase();
   if (explicitProfile === "debug" || explicitProfile === "release") {
     return explicitProfile;
   }
 
-  return isCodespacesMode(env) ? "debug" : "release";
-}
-
-function isCodespacesAutoPublicEnabled(env) {
-  const raw = readNonEmptyEnv(env, "BRIDGE_CODESPACES_AUTO_PUBLIC").toLowerCase();
-  return raw ? raw !== "false" : true;
-}
-
-function buildCodespacesForwardedUrl(env, port) {
-  const codespaceName = readNonEmptyEnv(env, "CODESPACE_NAME");
-  const forwardingDomain = readNonEmptyEnv(env, "GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN");
-  if (!codespaceName || !forwardingDomain) {
-    return "";
-  }
-  return `https://${codespaceName}-${port}.${forwardingDomain}`;
+  return "release";
 }
 
 function resolveBridgeAccessUrl(env, endpoint) {
@@ -163,13 +143,6 @@ function resolveBridgeAccessUrl(env, endpoint) {
     return configured;
   }
 
-  if (isCodespacesMode(env)) {
-    const forwarded = normalizeBaseUrl(buildCodespacesForwardedUrl(env, endpoint.port));
-    if (forwarded) {
-      return forwarded;
-    }
-  }
-
   if (isUnspecifiedBindHost(endpoint.host)) {
     return "";
   }
@@ -309,148 +282,9 @@ function printBridgeAccessDetails(env, endpoint) {
     console.log(`Bridge bind: ${buildBridgeUrl(endpoint.host, endpoint.port)}`);
   }
 
-  if (readNonEmptyEnv(env, "BRIDGE_GITHUB_CODESPACES_AUTH").toLowerCase() === "true") {
-    console.log("GitHub auth: enabled for Codespaces direct sign-in");
-  }
-
   return bridgeUrl;
 }
 
-function ghAuthEnv(env) {
-  const githubToken =
-    readNonEmptyEnv(process.env, "GH_TOKEN") ||
-    readNonEmptyEnv(process.env, "GITHUB_TOKEN") ||
-    readNonEmptyEnv(env, "GH_TOKEN") ||
-    readNonEmptyEnv(env, "GITHUB_TOKEN");
-
-  if (!githubToken) {
-    return { ...process.env, ...env };
-  }
-
-  return {
-    ...process.env,
-    ...env,
-    GH_TOKEN: githubToken,
-  };
-}
-
-function codespaceSelectionArgs(env) {
-  const name = readNonEmptyEnv(env, "CODESPACE_NAME");
-  return name ? ["-c", name] : [];
-}
-
-function formatCodespacesVisibilityCommand(env, ports) {
-  const uniquePorts = [...new Set(ports.filter((value) => Number.isFinite(value) && value > 0))];
-  const visibilityArgs = uniquePorts.map((port) => `${port}:public`);
-  const selectionArgs = codespaceSelectionArgs(env);
-  return ["gh", "codespace", "ports", "visibility", ...visibilityArgs, ...selectionArgs].join(" ");
-}
-
-function updateCodespacesBrowseUrls(env, ports) {
-  if (!commandExists("gh")) {
-    return;
-  }
-
-  const result = spawnSync(
-    "gh",
-    ["codespace", "ports", "--json", "sourcePort,browseUrl", ...codespaceSelectionArgs(env)],
-    {
-      encoding: "utf8",
-      env: ghAuthEnv(env),
-      stdio: ["ignore", "pipe", "pipe"],
-    }
-  );
-  if ((result.status ?? 1) !== 0 || !result.stdout) {
-    return;
-  }
-
-  let rows;
-  try {
-    rows = JSON.parse(result.stdout);
-  } catch {
-    return;
-  }
-
-  if (!Array.isArray(rows)) {
-    return;
-  }
-
-  for (const row of rows) {
-    if (!row || typeof row !== "object") {
-      continue;
-    }
-    const sourcePort = parsePort(row.sourcePort, 0);
-    const browseUrl = normalizeBaseUrl(row.browseUrl);
-    if (!sourcePort || !browseUrl || !ports.includes(sourcePort)) {
-      continue;
-    }
-
-    if (sourcePort === parsePort(env.BRIDGE_PORT, 8787)) {
-      env.BRIDGE_CONNECT_URL = browseUrl;
-    }
-    if (sourcePort === parsePort(env.BRIDGE_PREVIEW_PORT, sourcePort + 1)) {
-      env.BRIDGE_PREVIEW_CONNECT_URL = browseUrl;
-    }
-  }
-}
-
-function ensureCodespacesPortsArePublic(env, ports) {
-  if (!isCodespacesMode(env) || !isCodespacesAutoPublicEnabled(env)) {
-    return [];
-  }
-
-  const uniquePorts = [...new Set(ports.filter((value) => Number.isFinite(value) && value > 0))];
-  const notes = [];
-
-  if (uniquePorts.length === 0) {
-    return notes;
-  }
-
-  if (!commandExists("gh")) {
-    notes.push(
-      `Codespaces mode detected, but GitHub CLI is unavailable. Run '${formatCodespacesVisibilityCommand(
-        env,
-        uniquePorts
-      )}' or mark those forwarded ports public in the Ports panel.`
-    );
-    return notes;
-  }
-
-  const result = spawnSync(
-    "gh",
-    [
-      "codespace",
-      "ports",
-      "visibility",
-      ...uniquePorts.map((port) => `${port}:public`),
-      ...codespaceSelectionArgs(env),
-    ],
-    {
-      encoding: "utf8",
-      env: ghAuthEnv(env),
-      stdio: ["ignore", "pipe", "pipe"],
-    }
-  );
-
-  if ((result.status ?? 1) !== 0) {
-    const detail = (result.stderr || result.stdout || "").trim();
-    const suffix = detail ? ` (${detail.split(/\r?\n/, 1)[0]})` : "";
-    notes.push(
-      `Could not set Codespaces forwarded ports public automatically${suffix}. Run '${formatCodespacesVisibilityCommand(
-        env,
-        uniquePorts
-      )}' or update the Ports panel manually.`
-    );
-    return notes;
-  }
-
-  updateCodespacesBrowseUrls(env, uniquePorts);
-  notes.push(
-    `Codespaces forwarded ports are set to public for bridge access: ${uniquePorts.join(", ")}.`
-  );
-  return notes;
-}
-
 function bridgePidFile(rootDir) {
   return path.join(rootDir, ".bridge.pid");
 }
@@ -543,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.");
@@ -626,16 +418,7 @@ function spawnAndRelay(command, args, options) {
   });
 
   if (child.pid) {
-    const bridgePort = parsePort(env.BRIDGE_PORT, 8787);
-    const previewPort = parsePort(env.BRIDGE_PREVIEW_PORT, bridgePort + 1);
-    void waitForHealth(env, child.pid, healthTimeoutMs)
-      .then(() => {
-        const notes = ensureCodespacesPortsArePublic(env, [bridgePort, previewPort]);
-        for (const note of notes) {
-          console.log(note);
-        }
-      })
-      .catch(() => {});
+    void waitForHealth(env, child.pid, healthTimeoutMs).catch(() => {});
   }
 
   child.on("exit", (code, signal) => {
@@ -652,7 +435,6 @@ async function spawnDetachedAndWait(command, args, options) {
   const logPath = bridgeLogFile(rootDir);
   const host = env.BRIDGE_HOST || "127.0.0.1";
   const port = env.BRIDGE_PORT || "8787";
-  const previewPort = parsePort(env.BRIDGE_PREVIEW_PORT, parsePort(port, 8787) + 1);
   const healthUrl = new URL(`http://${formatHostForUrl(host)}:${port}/health`);
   const existingPid = readPidFile(rootDir);
 
@@ -662,11 +444,7 @@ async function spawnDetachedAndWait(command, args, options) {
       console.log(`Logs: ${logPath}`);
       console.log("Bridge is healthy.");
       const endpoint = { host, port };
-      const notes = ensureCodespacesPortsArePublic(env, [parsePort(port, 8787), previewPort]);
       printBridgeAccessDetails(env, endpoint);
-      for (const note of notes) {
-        console.log(note);
-      }
       if (shouldShowPairingQr(env) && !printPairingQr(env, endpoint)) {
         printPairingQrUnavailableMessage(env);
       }
@@ -713,11 +491,7 @@ async function spawnDetachedAndWait(command, args, options) {
   try {
     const endpoint = await waitForHealth(env, child.pid, healthTimeoutMs);
     console.log("Bridge is healthy.");
-    const notes = ensureCodespacesPortsArePublic(env, [parsePort(endpoint.port, 8787), previewPort]);
     printBridgeAccessDetails(env, endpoint);
-    for (const note of notes) {
-      console.log(note);
-    }
 
     if (shouldShowPairingQr(env) && !printPairingQr(env, endpoint)) {
       printPairingQrUnavailableMessage(env);
@@ -752,6 +526,8 @@ function buildBridgeFromSource(packageDir, env, profile) {
 }
 
 function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuild }) {
+  const defaultHealthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS;
+
   if (devMode) {
     if (!commandExists("cargo")) {
       console.error("error: missing Rust/Cargo toolchain for dev bridge mode.");
@@ -779,7 +555,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
       args: [],
       cwd: workspaceDir,
       env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+      healthTimeoutMs: defaultHealthTimeoutMs,
     };
   }
 
@@ -792,25 +568,20 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
       args: [],
       cwd: workspaceDir,
       env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+      healthTimeoutMs: defaultHealthTimeoutMs,
     };
   }
 
   const builtBinary = builtBinaryPath(packageDir, os.platform(), buildProfile);
-  if (isBuiltBinaryFresh(packageDir, builtBinary)) {
-    ensureExecutable(builtBinary);
-    return {
-      command: builtBinary,
-      args: [],
-      cwd: workspaceDir,
-      env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
-    };
+
+  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);
   }
 
@@ -833,7 +604,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
     args: [],
     cwd: workspaceDir,
     env,
-    healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+    healthTimeoutMs: defaultHealthTimeoutMs,
   };
 }
 

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