@gakim-digital/dexter-bridge 0.11.19 → 0.11.21

package/README.md

@@ -166,11 +166,18 @@ for support and automation:
 npx @gakim-digital/dexter-bridge pair 123456 --api http://localhost:3800/iwm-api/0.0.1
 npx @gakim-digital/dexter-bridge start --agent claude-code
 npx @gakim-digital/dexter-bridge start --agent codex
+npx @gakim-digital/dexter-bridge start --agent cursor
 npx @gakim-digital/dexter-bridge status
 npx @gakim-digital/dexter-bridge doctor
 npx @gakim-digital/dexter-bridge logout
 ```
 
+Cursor needs the Cursor CLI signed in on the same computer
+(`curl https://cursor.com/install -fsS | bash`, then `cursor-agent login`).
+The bridge runs `cursor-agent acp` with Cursor's shell, file, and web tools
+denied, so Cursor can use only Dexter's Framer tools. Set
+`DEXTER_BRIDGE_CURSOR_BIN` if `cursor-agent` is installed elsewhere.
+
 On Windows, the bridge checks the native Claude Code install at
 `%USERPROFILE%\.local\bin\claude.exe` in addition to `PATH`. Before pairing,
 verify the same PowerShell window can run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.11.19",
+  "version": "0.11.21",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -52,6 +52,7 @@ import {
 } from './nativeSkills.js';
 import { createLocalAgentAdapter } from './providers/index.js';
 import { discoverClaudeCodeModels } from './providers/claudeAgentSdk.js';
+import { cursorInstallCommand, cursorLauncher, readCursorVersion } from './providers/cursorAcp.js';
 import {
   collectOutcomeWorkspaceChanges,
   materializeModelTurnImages,
@@ -174,6 +175,15 @@ export const AGENT_DEFINITIONS = {
     model: 'codex:gpt-5.5',
     statusStage: 'codex_start',
   },
+  cursor: {
+    id: 'cursor',
+    label: 'Cursor',
+    commandEnv: 'DEXTER_BRIDGE_CURSOR_BIN',
+    fallbackCommand: 'cursor-agent',
+    promptMode: 'stdin',
+    model: 'cursor:grok-4.7',
+    statusStage: 'cursor_start',
+  },
 };
 
 export const AGENT_AUTHENTICATION_REQUIRED_CODE = 'DEXTER_AGENT_AUTHENTICATION_REQUIRED';
@@ -887,7 +897,15 @@ export function processEnvWithCliPath(baseEnv = process.env, platform = process.
           baseEnv.APPDATA ? pathApi.join(baseEnv.APPDATA, 'npm') : '',
           baseEnv.LOCALAPPDATA ? pathApi.join(baseEnv.LOCALAPPDATA, 'Programs') : '',
         ]
-      : ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+      : [
+          homeDirectory ? pathApi.join(homeDirectory, '.local', 'bin') : '',
+          '/opt/homebrew/bin',
+          '/usr/local/bin',
+          '/usr/bin',
+          '/bin',
+          '/usr/sbin',
+          '/sbin',
+        ];
   const shellEnv = platform === 'win32' ? {} : loginShellEnv();
   const existingPath = String(baseEnv.PATH || '');
   const mergedPath = mergePathEntries([shellEnv.PATH, existingPath, ...fallbackPath], platform);
@@ -1416,6 +1434,7 @@ function definitionForRuntimeProfile(profile, fallbackAgent) {
   if (!profile) return definitionForAgent(fallbackAgent);
   if (profile.driver === 'claude-code-cli') return AGENT_DEFINITIONS['claude-code'];
   if (profile.driver === 'codex-app-server') return AGENT_DEFINITIONS.codex;
+  if (profile.driver === 'cursor-acp') return AGENT_DEFINITIONS.cursor;
   return {
     id: profile.id || profile.driver,
     label: profile.label || profile.driver || 'Local runtime',
@@ -1716,6 +1735,26 @@ async function callProviderAdapter(
   }
 }
 
+// Cursor starts through its own launcher (on Windows, the bundled node.exe
+// behind cursor-agent.cmd), so its version is read through that launcher.
+async function resolveCursorRuntime(options = {}) {
+  const platform = options.platform || process.platform;
+  const launcher = cursorLauncher({
+    env: processEnvWithCliPath(options.env || process.env, platform),
+    platform,
+  });
+  const { error, output } = await readCursorVersion(launcher);
+  if (error) {
+    return {
+      ok: false,
+      command: launcher?.command || 'cursor-agent',
+      code: 'DEXTER_AGENT_NOT_FOUND',
+      error: `Cursor CLI is not installed. Run \`${cursorInstallCommand(platform)}\`, then \`cursor-agent login\`.`,
+    };
+  }
+  return { ok: true, command: launcher.command, output, version: parseAgentVersion(output) };
+}
+
 export async function resolveAgentRuntime(definition, modelDefinition, options = {}) {
   const platform = options.platform || process.platform;
   const childEnv = processEnvWithCliPath(options.env || process.env, platform);
@@ -3144,7 +3183,8 @@ export async function executeRun(
   });
   const runtimeProfile = run?.runtimeProfile || suppliedRuntimeProfile || null;
   const normalizedAgent = normalizeAgentName(
-    run?.companion?.agent || (runtimeProfile?.driver === 'claude-code-cli' ? 'claude-code' : agent),
+    run?.companion?.agent
+      || ({ 'claude-code-cli': 'claude-code', 'cursor-acp': 'cursor' }[runtimeProfile?.driver] || agent),
   );
   const runModel = runtimeProfile?.model?.id || run?.companion?.model?.id || run?.model || selectedModel;
   const usageAccumulator = createCompanionUsageAccumulator(normalizedAgent);
@@ -3312,12 +3352,14 @@ export async function checkAgentAvailability(agent, model, options = {}) {
   }
   const definition = definitionForAgent(normalizedAgent);
   const selectedModel = model ? companionModelDefinition(model?.id || model, normalizedAgent) : undefined;
-  const runtime = await resolveAgentRuntime(definition, selectedModel, {
-    env: options.env,
-    platform: options.platform,
-    existsSync: options.existsSync,
-    inspect: options.inspectRuntime,
-  });
+  const runtime = normalizedAgent === 'cursor' && !options.inspectRuntime
+    ? await resolveCursorRuntime(options)
+    : await resolveAgentRuntime(definition, selectedModel, {
+      env: options.env,
+      platform: options.platform,
+      existsSync: options.existsSync,
+      inspect: options.inspectRuntime,
+    });
   const supportedModels = companionModelsForAgent(normalizedAgent).filter((candidate) =>
     modelSupportsAgentVersion(candidate, runtime.version),
   );
@@ -3335,10 +3377,10 @@ export async function checkAgentAvailability(agent, model, options = {}) {
       modelCatalogRefreshedAt,
     };
   }
-  if (normalizedAgent === 'codex') {
+  if (normalizedAgent === 'codex' || normalizedAgent === 'cursor') {
     const adapter =
       options.providerAdapter
-      || createLocalAgentAdapter('codex', {
+      || createLocalAgentAdapter(normalizedAgent, {
         env: options.env,
       });
     try {
@@ -3358,7 +3400,7 @@ export async function checkAgentAvailability(agent, model, options = {}) {
           code: detection.installed === false ? 'DEXTER_AGENT_NOT_FOUND' : AGENT_AUTHENTICATION_REQUIRED_CODE,
           error:
             detection.error
-            || 'Codex is not signed in. Run `codex login` on this computer, then run the bridge command again.',
+            || `${definition.label} is not signed in. Sign in on this computer, then run the bridge command again.`,
           modelCatalogSource: 'fallback',
           modelCatalogRefreshedAt,
         };
@@ -3438,6 +3480,7 @@ export async function checkAllAgents(options = {}) {
   const agents = await Promise.all([
     checkAgentAvailability('claude-code', undefined, options),
     checkAgentAvailability('codex', undefined, options),
+    checkAgentAvailability('cursor', undefined, options),
   ]);
   return {
     agents,

package/src/cli.js

@@ -16,7 +16,8 @@ import {
   resolveCompanionModelName,
   saveConfigPatch,
 } from './config.js';
-import { checkAgentAvailability, checkAllAgents, executeRun } from './agent.js';
+import { checkAgentAvailability, checkAllAgents, executeRun, processEnvWithCliPath } from './agent.js';
+import { setUpCursorCli } from './providers/cursorAcp.js';
 import {
   claimPairing,
   heartbeat,
@@ -55,11 +56,12 @@ function usage() {
     'Environment:',
     '  DEXTER_API_URL              API base URL, e.g. https://api.example.com/iwm-api/0.0.1',
     '  DEXTER_BRIDGE_RUNTIME       codex, claude-code, or opencode',
-    '  DEXTER_BRIDGE_AGENT         claude-code, codex, opencode, or dry-run',
+    '  DEXTER_BRIDGE_AGENT         claude-code, codex, cursor, opencode, or dry-run',
     '  DEXTER_BRIDGE_MODEL         Companion model, e.g. claude-code:sonnet or codex:gpt-5.5',
     '  DEXTER_BRIDGE_CLAUDE_BIN    Claude CLI binary name/path',
     '  DEXTER_BRIDGE_CLAUDE_ARGS   Claude CLI args, default: -p',
     '  DEXTER_BRIDGE_CODEX_BIN     Codex CLI binary name/path',
+    '  DEXTER_BRIDGE_CURSOR_BIN    Cursor CLI binary name/path, default: cursor-agent',
     '  DEXTER_BRIDGE_CODEX_MAX_THREADS Maximum retained App Server threads, default: 32',
     '  DEXTER_BRIDGE_LOG_DIR       Log directory, default: ~/.dexter-bridge/logs',
   ].join('\n');
@@ -134,6 +136,28 @@ function requireDeviceToken(config) {
   return config.deviceToken;
 }
 
+async function confirmPrompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    return answer === '' || answer === 'y' || answer === 'yes';
+  } catch {
+    return false;
+  } finally {
+    rl.close();
+  }
+}
+
+// One `connect --agent cursor` command installs and signs in to the Cursor CLI
+// when needed, so the Cursor setup has no separate steps.
+async function prepareRequestedAgent(flags, config) {
+  if (normalizeAgentName(flags.agent || config.agent) !== 'cursor') return;
+  await setUpCursorCli({
+    env: processEnvWithCliPath(agentEnvironment(config)),
+    confirm: process.stdin.isTTY ? confirmPrompt : null,
+  });
+}
+
 async function promptForPairingCode() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -309,6 +333,9 @@ function agentEnvironment(config = {}, baseEnv = process.env) {
   if (!env.DEXTER_BRIDGE_CODEX_BIN && commands.codex) {
     env.DEXTER_BRIDGE_CODEX_BIN = commands.codex;
   }
+  if (!env.DEXTER_BRIDGE_CURSOR_BIN && commands.cursor) {
+    env.DEXTER_BRIDGE_CURSOR_BIN = commands.cursor;
+  }
   return env;
 }
 
@@ -316,11 +343,11 @@ function modelCatalogStatus(runtimeProfiles = []) {
   return Object.fromEntries(
     runtimeProfiles.flatMap((profile) => {
       const agent =
-        profile.driver === 'codex-app-server'
-          ? 'codex'
-          : profile.driver === 'claude-code-cli'
-            ? 'claude-code'
-            : null;
+        {
+          'codex-app-server': 'codex',
+          'claude-code-cli': 'claude-code',
+          'cursor-acp': 'cursor',
+        }[profile.driver] || null;
       return agent ? [[agent, profile.modelCatalog]] : [];
     }),
   );
@@ -466,7 +493,8 @@ function requireAvailableAgent(availability, agent, platform = process.platform)
   const check = selectedAgentCheck(availability, agent);
   if (check?.ok) return check;
 
-  const label = agent === 'claude-code' ? 'Claude Code' : agent === 'codex' ? 'Codex' : 'The selected agent';
+  const label = { 'claude-code': 'Claude Code', codex: 'Codex', cursor: 'Cursor' }[agent]
+    || 'The selected agent';
   let message = check?.error || `${label} is not installed or could not be started.`;
   if (agent === 'claude-code' && check?.status === 'authentication_required') {
     message = check.error || 'Claude Code is not signed in. Run `claude auth login`, then try again.';
@@ -778,11 +806,11 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
         const runAgent = normalizeAgentName(
           poll.run?.companion?.agent
           || (
-            runtimeProfile?.driver === 'claude-code-cli'
-              ? 'claude-code'
-              : runtimeProfile?.driver === 'opencode'
-                ? 'opencode'
-                : 'codex'
+            {
+              'claude-code-cli': 'claude-code',
+              'cursor-acp': 'cursor',
+              opencode: 'opencode',
+            }[runtimeProfile?.driver] || 'codex'
           ),
         );
         await executeClaimedRun({
@@ -865,6 +893,7 @@ export async function runCli(argv) {
     // The one-command production path: claim the pairing code (when given or
     // not yet paired), save config, and go straight into the polling loop.
     case 'connect':
+      await prepareRequestedAgent(parsed.flags, config);
       if (parsed.args[0]) {
         await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
       }

package/src/config.js

@@ -31,6 +31,7 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
     './providers/directByok.js',
     './providers/openCode.js',
     './providers/acp.js',
+    './providers/cursorAcp.js',
   ].map((relativePath) => {
     const url = new URL(relativePath, import.meta.url);
     return `${relativePath}\u0000${fs.readFileSync(url, 'utf8')}`;
@@ -52,6 +53,7 @@ export const BRIDGE_CAPABILITIES = [
   'native-skills-v1',
   'model-progress-v1',
   'model-catalog-refresh-v1',
+  'cursor-acp-v1',
 ];
 export const BRIDGE_PRODUCTS = {
   dexter: {
@@ -69,7 +71,7 @@ export const BRIDGE_PRODUCTS = {
 // user explicitly connects the locally installed CLI and chooses one of its
 // reported models.
 export const DEFAULT_BRIDGE_AGENT = 'codex';
-export const BRIDGE_AGENTS = ['claude-code', 'codex', 'opencode', 'dry-run'];
+export const BRIDGE_AGENTS = ['claude-code', 'codex', 'cursor', 'opencode', 'dry-run'];
 export const COMPANION_MODEL_DEFINITIONS = [
   {
     id: 'claude-code:fable',
@@ -162,6 +164,63 @@ export const COMPANION_MODEL_DEFINITIONS = [
     costTier: '$',
     description: 'Low-latency Codex model for quick coding iterations.',
   },
+  // Cursor lists every model it offers, whatever the user's plan; Dexter
+  // shows frontier models plus Composer. Paid Cursor plans include Grok and
+  // Composer; Claude, GPT and Gemini are billed from Cursor credits.
+  {
+    id: 'cursor:grok-4.7',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'Grok 4.7',
+    invocationName: 'grok-4.7',
+    costTier: '$$$',
+    description: 'Grok 4.7, included in paid Cursor plans.',
+  },
+  {
+    id: 'cursor:composer-2.5',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'Composer 2.5',
+    invocationName: 'composer-2.5',
+    costTier: '$$',
+    description: "Cursor's fast model, included in paid Cursor plans.",
+  },
+  {
+    id: 'cursor:claude-opus-5-5',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'Claude Opus 5.5',
+    invocationName: 'claude-opus-5-5',
+    costTier: '$$$',
+    description: 'Claude Opus 5.5 via your Cursor plan.',
+  },
+  {
+    id: 'cursor:claude-fable-5-1',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'Claude Fable 5.1',
+    invocationName: 'claude-fable-5-1',
+    costTier: '$$$',
+    description: 'Claude Fable 5.1 via your Cursor plan.',
+  },
+  {
+    id: 'cursor:gpt-5.6-sol',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'GPT-5.6 Sol',
+    invocationName: 'gpt-5.6-sol',
+    costTier: '$$$',
+    description: 'GPT-5.6 Sol via your Cursor plan.',
+  },
+  {
+    id: 'cursor:gemini-4-argon',
+    agent: 'cursor',
+    provider: 'cursor',
+    displayName: 'Gemini 4 Argon',
+    invocationName: 'gemini-4-argon',
+    costTier: '$$$',
+    description: 'Gemini 4 Argon via your Cursor plan.',
+  },
   {
     id: 'dry-run:default',
     agent: 'dry-run',
@@ -176,6 +235,7 @@ export const COMPANION_MODEL_DEFINITIONS = [
 const DEFAULT_MODEL_BY_AGENT = {
   'claude-code': 'claude-code:sonnet',
   codex: 'codex:gpt-5.5',
+  cursor: 'cursor:grok-4.7',
   'dry-run': 'dry-run:default',
 };
 
@@ -237,6 +297,7 @@ export function normalizeAgentName(value, fallback = DEFAULT_BRIDGE_AGENT) {
   const raw = String(value || '').trim().toLowerCase();
   if (raw === 'claude' || raw === 'claude_code' || raw === 'claude-code') return 'claude-code';
   if (raw === 'openai-codex' || raw === 'openai_codex' || raw === 'codex') return 'codex';
+  if (raw === 'cursor' || raw === 'cursor-agent' || raw === 'cursor_agent') return 'cursor';
   if (raw === 'open-code' || raw === 'open_code' || raw === 'opencode') return 'opencode';
   if (raw === 'dryrun' || raw === 'dry_run' || raw === 'dry-run') return 'dry-run';
   return BRIDGE_AGENTS.includes(fallback) ? fallback : DEFAULT_BRIDGE_AGENT;
@@ -269,11 +330,11 @@ export function companionModelDefinition(value, agent = DEFAULT_BRIDGE_AGENT) {
       return {
         id: `${normalizedAgent}:${invocationName}`,
         agent: normalizedAgent,
-        provider: normalizedAgent === 'codex' ? 'openai' : normalizedAgent === 'claude-code' ? 'anthropic' : 'companion',
+        provider: normalizedAgent === 'codex' ? 'openai' : normalizedAgent === 'claude-code' ? 'anthropic' : normalizedAgent === 'cursor' ? 'cursor' : 'companion',
         displayName: invocationName,
         invocationName,
         costTier: '$$',
-        description: `${normalizedAgent === 'codex' ? 'Codex' : 'Claude Code'} model reported by the connected bridge.`,
+        description: `${{ codex: 'Codex', cursor: 'Cursor' }[normalizedAgent] || 'Claude Code'} model reported by the connected bridge.`,
       };
     }
   }

package/src/protocol.js

@@ -496,6 +496,7 @@ export function buildFramerOutcomePrompt(outcome = {}, product, promptContext =
     'You decide when the run is complete. Avoid repeated inspection of unchanged evidence and stop when the requested outcome has been implemented and verified.',
     'Dexter will not perform a second design verification after you finish. Structural verification must be described honestly and must never be called runtime-tested unless an interaction was actually exercised.',
     'If Framer authorization or a required user decision is missing, return blocked with a concise explanation. Otherwise return completed only after you have finished and verified the work.',
+    'A greeting, thanks, or question that needs no project change is not blocked: answer it in summary without reading or editing the project and return completed.',
     'When finished, return exactly one JSON object and no markdown.',
     '{"status":"completed|blocked|failed","summary":"one or two short, non-technical sentences for the designer","checks":[{"command":"what you verified","status":"passed|failed|skipped","output":"short result"}],"blockedReason":null}',
     doctrine

package/src/providers/cursorAcp.js

@@ -0,0 +1,557 @@
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createJsonRpcClient } from './jsonRpcClient.js';
+
+// Cursor runs its built-in tools (shell, file read/write, web fetch) inside
+// `cursor-agent` itself and ignores the ACP client capabilities, so every
+// session runs in a workspace whose Cursor permissions deny them and allow
+// only the InstaWebAI MCP server. Verified against cursor-agent 2026.10.16.
+export const CURSOR_WORKSPACE_PERMISSIONS = {
+  permissions: {
+    allow: ['Mcp(instawebai:*)'],
+    deny: ['Shell(*)', 'Read(**)', 'Write(**)', 'WebFetch(*)'],
+  },
+};
+
+export const CURSOR_PLAN_REQUIRED_CODE = 'CURSOR_PLAN_REQUIRED';
+// Cursor reports plan and billing refusals as a short assistant reply that
+// ends the turn, e.g. "Upgrade your plan to continue" or "Add a payment
+// method to continue".
+const PLAN_LIMIT_PATTERN =
+  /upgrade your plan|payment method|billing|free plans can only use auto|named models unavailable|usage limit|spend limit/i;
+
+export function isCursorPlanRefusal(text) {
+  const reply = String(text || '').trim();
+  return reply.length > 0 && reply.length < 400 && !reply.includes('{') && PLAN_LIMIT_PATTERN.test(reply);
+}
+
+const IMAGE_MIME_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+export function cursorBaseModelId(modelId) {
+  return String(modelId || '').split('[')[0].trim();
+}
+
+export function writeCursorWorkspacePermissions(directory) {
+  fs.mkdirSync(path.join(directory, '.cursor'), { recursive: true });
+  fs.writeFileSync(
+    path.join(directory, '.cursor', 'cli.json'),
+    `${JSON.stringify(CURSOR_WORKSPACE_PERMISSIONS, null, 2)}\n`,
+  );
+}
+
+function cursorMcpServers(mcpServer) {
+  if (!mcpServer?.command) return [];
+  return [{
+    name: 'instawebai',
+    command: mcpServer.command,
+    args: mcpServer.args || [],
+    env: Object.entries(mcpServer.environment || {}).map(([name, value]) => ({
+      name,
+      value: String(value),
+    })),
+  }];
+}
+
+function imageBlocks(imageFiles = []) {
+  return imageFiles.flatMap((file) => {
+    const mimeType = IMAGE_MIME_TYPES[path.extname(file).toLowerCase()];
+    if (!mimeType) return [];
+    try {
+      return [{ type: 'image', mimeType, data: fs.readFileSync(file).toString('base64') }];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function withOutputContract(prompt, outputSchema) {
+  if (!outputSchema) return String(prompt || '');
+  return [
+    String(prompt || ''),
+    '',
+    'Your final message must be exactly one JSON object, with no markdown, that matches this JSON Schema:',
+    JSON.stringify(outputSchema),
+  ].join('\n');
+}
+
+function isOwnTool(toolCall) {
+  return /instawebai/i.test(JSON.stringify(toolCall || {}));
+}
+
+function toolName(update) {
+  return update?.rawInput?.toolName || null;
+}
+
+export function planRequiredError(model, reply) {
+  return Object.assign(
+    new Error(
+      `Cursor would not run ${model || 'this model'}${reply ? `: "${reply}"` : '.'} Cursor bills Claude, GPT and Gemini models from credits or additional usage, not your plan's included usage. Buy credits or set an additional usage limit in Cursor's billing settings, or pick a model your plan includes.`,
+    ),
+    { code: CURSOR_PLAN_REQUIRED_CODE, retryable: false },
+  );
+}
+
+export function parseCursorStatus(output) {
+  const text = String(output || '');
+  const match = text.match(/logged in as\s+(\S+)/i);
+  return {
+    signedIn: Boolean(match) && !/not logged in/i.test(text),
+    account: match ? match[1] : null,
+  };
+}
+
+export const CURSOR_INSTALL_COMMAND = 'curl https://cursor.com/install -fsS | bash';
+export const CURSOR_WINDOWS_INSTALL_COMMAND = "irm 'https://cursor.com/install?win32=true' | iex";
+
+export function cursorInstallCommand(platform = process.platform) {
+  return platform === 'win32' ? CURSOR_WINDOWS_INSTALL_COMMAND : CURSOR_INSTALL_COMMAND;
+}
+
+const CURSOR_VERSION_DIRECTORY = /^(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-\d{2}-\d{2}-\d{2})?-[a-f0-9]+$/;
+
+function cursorVersionRank(name) {
+  const [, year, month, day] = name.match(CURSOR_VERSION_DIRECTORY);
+  return Number(`${year}${month.padStart(2, '0')}${day.padStart(2, '0')}`);
+}
+
+// Same choice as Cursor's own cursor-agent.ps1: a build next to the launcher,
+// otherwise the newest build under versions\.
+function newestCursorBuild(root, fileSystem) {
+  const hasBuild = (directory) =>
+    fileSystem.existsSync(path.win32.join(directory, 'node.exe'))
+    && fileSystem.existsSync(path.win32.join(directory, 'index.js'));
+  if (hasBuild(root)) return root;
+  let names = [];
+  try {
+    names = fileSystem.readdirSync(path.win32.join(root, 'versions'));
+  } catch {
+    return null;
+  }
+  return names
+    .filter((name) => CURSOR_VERSION_DIRECTORY.test(name))
+    .sort((left, right) => cursorVersionRank(right) - cursorVersionRank(left) || right.localeCompare(left))
+    .map((name) => path.win32.join(root, 'versions', name))
+    .find(hasBuild) || null;
+}
+
+/**
+ * The command and leading arguments that start the Cursor CLI, or null when
+ * it is not installed. On Windows the CLI is a cursor-agent.cmd shim that runs
+ * PowerShell, which runs the node.exe bundled with the newest installed build.
+ * Node can start a .cmd only through a shell, and stopping that shell leaves
+ * Cursor running, so the bridge starts the bundled node.exe directly, as the
+ * shim does. The installer's folder is checked by path because a bridge that
+ * was already running does not see the PATH change the installer makes.
+ */
+export function cursorLauncher({ env = process.env, platform = process.platform, fileSystem = fs } = {}) {
+  const override = String(env.DEXTER_BRIDGE_CURSOR_BIN || '').trim();
+  if (platform !== 'win32') return { command: override || 'cursor-agent', args: [], env };
+  if (override && !/\.(cmd|bat|ps1)$/i.test(override)) return { command: override, args: [], env };
+  const roots = [
+    ...(override ? [path.win32.dirname(override)] : []),
+    ...String(env.PATH || env.Path || '')
+      .split(';')
+      .filter((directory) => directory && fileSystem.existsSync(path.win32.join(directory, 'cursor-agent.cmd'))),
+    ...(env.LOCALAPPDATA ? [path.win32.join(env.LOCALAPPDATA, 'cursor-agent')] : []),
+  ];
+  for (const root of new Set(roots)) {
+    const build = newestCursorBuild(root, fileSystem);
+    if (build) {
+      return {
+        command: path.win32.join(build, 'node.exe'),
+        args: [path.win32.join(build, 'index.js')],
+        env: { ...env, CURSOR_INVOKED_AS: 'cursor-agent.cmd' },
+      };
+    }
+  }
+  return null;
+}
+
+function notInstalledError(code = 'ENOENT') {
+  return Object.assign(new Error('Cursor CLI not found.'), { code });
+}
+
+function runCommand(launcher, args, timeoutMs = 15_000) {
+  if (!launcher) return Promise.resolve({ error: notInstalledError(), output: '' });
+  return new Promise((resolve) => {
+    execFile(
+      launcher.command,
+      [...launcher.args, ...args],
+      { env: launcher.env, timeout: timeoutMs, windowsHide: true },
+      (error, stdout, stderr) => {
+        resolve({ error, output: `${stdout || ''}${stderr || ''}`.trim() });
+      },
+    );
+  });
+}
+
+export function readCursorVersion(launcher) {
+  return runCommand(launcher, ['--version']);
+}
+
+function runInteractive(command, args, env, spawnImpl) {
+  return new Promise((resolve) => {
+    const child = spawnImpl(command, args, { env, stdio: 'inherit' });
+    child.once('error', () => resolve(false));
+    child.once('exit', (code) => resolve(code === 0));
+  });
+}
+
+function installCursorCli(platform, env, spawnImpl) {
+  return platform === 'win32'
+    ? runInteractive(
+      'powershell.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', CURSOR_WINDOWS_INSTALL_COMMAND],
+      env,
+      spawnImpl,
+    )
+    : runInteractive('bash', ['-c', CURSOR_INSTALL_COMMAND], env, spawnImpl);
+}
+
+function setupError(message) {
+  return Object.assign(new Error(message), { code: 'CURSOR_SETUP_INCOMPLETE', exitCode: 2 });
+}
+
+/**
+ * Gets the Cursor CLI installed and signed in so one `connect` command is the
+ * whole Cursor setup. Installing asks first; sign-in opens Cursor's own
+ * browser login. Does nothing when Cursor is already ready.
+ */
+export async function setUpCursorCli({
+  env = process.env,
+  confirm,
+  log = console.log,
+  platform = process.platform,
+  findCursor = () => cursorLauncher({ env, platform }),
+  run = runCommand,
+  spawnImpl = spawn,
+} = {}) {
+  const installCommand = cursorInstallCommand(platform);
+  let launcher = null;
+  const readStatus = async () => {
+    launcher = findCursor();
+    const result = await run(launcher, ['status']);
+    if (!launcher || result.error?.code === 'ENOENT') return { installed: false, signedIn: false };
+    return { installed: true, ...parseCursorStatus(result.output) };
+  };
+  let status = await readStatus();
+  if (!status.installed) {
+    if (!confirm) {
+      throw setupError(`Cursor CLI is not installed. Run \`${installCommand}\`, then run this command again.`);
+    }
+    if (!(await confirm('Cursor CLI is not installed. Install it now? (Y/n) '))) {
+      throw setupError('Cursor CLI is required to connect Cursor to Dexter.');
+    }
+    if (!(await installCursorCli(platform, env, spawnImpl))) {
+      throw setupError(`Cursor CLI install failed. Run \`${installCommand}\` yourself, then run this command again.`);
+    }
+    status = await readStatus();
+    if (!status.installed) {
+      throw setupError('Cursor CLI was installed but could not be found. Open a new terminal and run this command again.');
+    }
+  }
+  if (!status.signedIn) {
+    if (!confirm) {
+      throw setupError('Cursor is not signed in. Run `cursor-agent login`, then run this command again.');
+    }
+    log('Sign in to Cursor in your browser…');
+    await runInteractive(launcher.command, [...launcher.args, 'login'], launcher.env, spawnImpl);
+    status = await readStatus();
+    if (!status.signedIn) {
+      throw setupError('Cursor sign-in did not finish. Run this command again to retry.');
+    }
+  }
+  log(`Cursor is ready${status.account ? ` (${status.account})` : ''}.`);
+  return status;
+}
+
+export function createCursorAcpAdapter({
+  env = process.env,
+  trace,
+  platform = process.platform,
+  findCursor = () => cursorLauncher({ env, platform }),
+  models = [],
+  createClient = createJsonRpcClient,
+} = {}) {
+  const activeTurns = new Map();
+  const notInstalledMessage =
+    `Cursor CLI is not installed. Run \`${cursorInstallCommand(platform)}\`, then \`cursor-agent login\`.`;
+
+  async function detect() {
+    const launcher = findCursor();
+    const version = await runCommand(launcher, ['--version']);
+    if (version.error) {
+      return {
+        ok: false,
+        installed: false,
+        signedIn: false,
+        agent: 'cursor',
+        error: notInstalledMessage,
+      };
+    }
+    const status = parseCursorStatus((await runCommand(launcher, ['status'])).output);
+    return {
+      ok: status.signedIn,
+      installed: true,
+      signedIn: status.signedIn,
+      agent: 'cursor',
+      version: version.output || null,
+      ...(status.signedIn
+        ? {}
+        : { error: 'Cursor is not signed in. Run `cursor-agent login` on this computer, then try again.' }),
+    };
+  }
+
+  async function runTurn({
+    runId,
+    sessionId,
+    prompt,
+    model,
+    cwd,
+    outputSchema,
+    imageFiles = [],
+    mcpServer = null,
+    timeoutMs = 10 * 60_000,
+    maxDurationMs = 20 * 60_000,
+    onProgress,
+  }) {
+    const turnKey = sessionId || runId;
+    if (!turnKey) throw new Error('A Cursor turn requires a session id.');
+    const launcher = findCursor();
+    if (!launcher) {
+      throw Object.assign(new Error(notInstalledMessage), { code: 'DEXTER_AGENT_NOT_FOUND', retryable: false });
+    }
+    const temporaryWorkspace = cwd
+      ? null
+      : fs.mkdtempSync(path.join(os.tmpdir(), 'dexter-cursor-'));
+    const workspace = cwd || temporaryWorkspace;
+    writeCursorWorkspacePermissions(workspace);
+
+    let segment = '';
+    let narrationIndex = 0;
+    let inactivityTimer = null;
+    let deadlineTimer = null;
+    let failTurn;
+    const failure = new Promise((_, reject) => {
+      failTurn = reject;
+    });
+    const timeOut = (code, message) =>
+      failTurn(Object.assign(new Error(message), { code, retryable: true }));
+    const touch = () => {
+      clearTimeout(inactivityTimer);
+      inactivityTimer = setTimeout(
+        () => timeOut('APP_AGENT_TURN_INACTIVITY_TIMEOUT', `Cursor was inactive for ${timeoutMs}ms.`),
+        timeoutMs,
+      );
+      inactivityTimer.unref?.();
+    };
+    const flushNarration = () => {
+      const message = segment.trim();
+      segment = '';
+      if (!message) return;
+      narrationIndex += 1;
+      onProgress?.({
+        kind: 'output_delta',
+        provider: 'cursor',
+        occurredAt: new Date().toISOString(),
+        message,
+        activity: `assistant:${turnKey}:${narrationIndex}`,
+      });
+    };
+
+    const client = createClient({
+      command: launcher.command,
+      args: [...launcher.args, 'acp'],
+      env: launcher.env,
+      cwd: workspace,
+      onServerRequest: async (message) => {
+        if (message.method === 'session/request_permission') {
+          const options = message.params?.options || [];
+          const kind = isOwnTool(message.params?.toolCall) ? 'allow_once' : 'reject_once';
+          const option = options.find((candidate) => candidate.kind === kind);
+          return option
+            ? { outcome: { outcome: 'selected', optionId: option.optionId } }
+            : { outcome: { outcome: 'cancelled' } };
+        }
+        throw new Error(`Cursor request "${message.method}" is disabled for Dexter runs.`);
+      },
+      onNotification: (message) => {
+        if (message.method !== 'session/update') return;
+        touch();
+        const update = message.params?.update || {};
+        switch (update.sessionUpdate) {
+          case 'agent_message_chunk':
+            segment += update.content?.text || '';
+            break;
+          case 'agent_thought_chunk':
+            onProgress?.({ kind: 'reasoning_delta', provider: 'cursor', occurredAt: new Date().toISOString() });
+            break;
+          case 'tool_call':
+            flushNarration();
+            break;
+          case 'tool_call_update': {
+            const name = toolName(update);
+            if (name) {
+              onProgress?.({
+                kind: 'item_started',
+                provider: 'cursor',
+                occurredAt: new Date().toISOString(),
+                name,
+                phase: 'started',
+              });
+            } else if (update.status === 'completed' || update.status === 'failed') {
+              onProgress?.({
+                kind: 'item_completed',
+                provider: 'cursor',
+                occurredAt: new Date().toISOString(),
+              });
+            }
+            break;
+          }
+          default:
+            break;
+        }
+      },
+    });
+
+    const turn = { client, nativeSessionId: null };
+    activeTurns.set(turnKey, turn);
+    deadlineTimer = setTimeout(
+      () => timeOut('APP_AGENT_TURN_HARD_TIMEOUT', `The Cursor turn exceeded the ${maxDurationMs}ms safety limit.`),
+      maxDurationMs,
+    );
+    deadlineTimer.unref?.();
+    touch();
+
+    let restoreModelId = null;
+    try {
+      const run = async () => {
+        await client.request('initialize', {
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+          },
+          clientInfo: { name: 'instawebai-dexter-bridge', version: '1' },
+        }, { timeoutMs: 30_000 });
+        const session = await client.request('session/new', {
+          cwd: workspace,
+          mcpServers: cursorMcpServers(mcpServer),
+        }, { timeoutMs: 60_000 });
+        turn.nativeSessionId = session?.sessionId;
+        if (!turn.nativeSessionId) throw new Error('Cursor did not return a session id.');
+
+        // Selecting a model in ACP also changes the user's default Cursor
+        // model, so the previous one is restored after the turn.
+        const requested = cursorBaseModelId(model);
+        if (requested) {
+          const available = session.models?.availableModels || [];
+          const variant = available.find((entry) => cursorBaseModelId(entry.modelId) === requested);
+          if (!variant) {
+            throw Object.assign(
+              new Error(`Cursor does not offer ${requested} on this account. Pick another Cursor model.`),
+              { code: 'CURSOR_MODEL_UNAVAILABLE', retryable: false },
+            );
+          }
+          const current = session.models?.currentModelId || null;
+          if (variant.modelId !== current) {
+            await client.request('session/set_model', {
+              sessionId: turn.nativeSessionId,
+              modelId: variant.modelId,
+            }, { timeoutMs: 30_000 });
+            restoreModelId = current;
+          }
+        }
+
+        onProgress?.({ kind: 'turn_started', provider: 'cursor', occurredAt: new Date().toISOString() });
+        const result = await client.request('session/prompt', {
+          sessionId: turn.nativeSessionId,
+          prompt: [
+            { type: 'text', text: withOutputContract(prompt, outputSchema) },
+            ...imageBlocks(imageFiles),
+          ],
+        }, { timeoutMs: 0 });
+        const text = segment.trim();
+        if (result?.stopReason === 'cancelled') {
+          throw Object.assign(new Error('The Cursor turn was cancelled.'), { code: 'RUN_CANCELLED' });
+        }
+        if (isCursorPlanRefusal(text)) {
+          throw planRequiredError(requested, text);
+        }
+        if (result?.stopReason && result.stopReason !== 'end_turn') {
+          throw Object.assign(
+            new Error(`Cursor stopped before finishing (${result.stopReason}).`),
+            { code: 'CURSOR_TURN_INCOMPLETE', retryable: result.stopReason === 'max_tokens' },
+          );
+        }
+        return {
+          text,
+          sessionId: turn.nativeSessionId,
+          usageAvailable: false,
+          usageSource: 'cursor',
+          usageAccuracy: 'unavailable',
+        };
+      };
+      return await Promise.race([run(), failure]);
+    } finally {
+      clearTimeout(inactivityTimer);
+      clearTimeout(deadlineTimer);
+      activeTurns.delete(turnKey);
+      if (restoreModelId && turn.nativeSessionId && !client.closed) {
+        await client.request('session/set_model', {
+          sessionId: turn.nativeSessionId,
+          modelId: restoreModelId,
+        }, { timeoutMs: 10_000 }).catch((error) => {
+          trace?.warn?.('cursor_model_restore_failed', { error: error?.message });
+        });
+      }
+      client.close();
+      if (temporaryWorkspace) {
+        fs.rmSync(temporaryWorkspace, { recursive: true, force: true });
+      }
+    }
+  }
+
+  async function runModelTurn(input = {}) {
+    return runTurn(input);
+  }
+
+  async function runOutcome(input = {}) {
+    return runTurn({
+      ...input,
+      mcpServer: input.harnessTools?.mcpServer || null,
+    });
+  }
+
+  async function cancel(sessionId) {
+    const turn = activeTurns.get(sessionId);
+    if (!turn || turn.client.closed || !turn.nativeSessionId) return;
+    turn.client.notify('session/cancel', { sessionId: turn.nativeSessionId });
+  }
+
+  function close() {
+    for (const turn of activeTurns.values()) turn.client.close();
+    activeTurns.clear();
+  }
+
+  return {
+    id: 'cursor',
+    driverKind: 'cursor-acp',
+    label: 'Cursor',
+    detect,
+    models: async () => models,
+    runModelTurn,
+    runOutcome,
+    cancel,
+    resetSession: async () => {},
+    close,
+  };
+}

package/src/providers/index.js

@@ -2,14 +2,15 @@ import { createCodexAppServerAdapter } from './codexAppServer.js';
 import { createDirectByokAdapter } from './directByok.js';
 import { createOpenCodeAdapter } from './openCode.js';
 import { createAcpAdapter } from './acp.js';
+import { createCursorAcpAdapter } from './cursorAcp.js';
+import { companionModelsForAgent } from '../config.js';
 
 /**
  * Local agent adapters.
  *
  * The server-owned agent loop and the `model_turn` relay protocol are unchanged;
- * an adapter only decides *how* one local model turn is executed. Today's shipping
- * Codex App Server is the only Codex path so model-only isolation is always
- * enforced.
+ * an adapter only decides *how* one local model turn is executed. Codex runs through
+ * its App Server and Cursor through `cursor-agent acp`.
  *
  * @typedef {Object} ProviderStatus
  * @property {boolean} ok
@@ -48,6 +49,13 @@ export const DRIVER_FACTORIES = {
     createOpenCodeAdapter({ ...options, profile }),
   acp: (profile, options) =>
     createAcpAdapter({ ...options, profile }),
+  'cursor-acp': (profile, options) =>
+    createCursorAcpAdapter({ ...options, models: companionModelsForAgent('cursor') }),
+};
+
+const BUILT_IN_AGENT_PROFILES = {
+  codex: { id: 'codex:default', driver: 'codex-app-server' },
+  cursor: { id: 'cursor:default', driver: 'cursor-acp' },
 };
 
 /**
@@ -56,9 +64,7 @@ export const DRIVER_FACTORIES = {
 export function createLocalAgentAdapter(profileOrAgent, options = {}) {
   const profile =
     typeof profileOrAgent === 'string'
-      ? profileOrAgent === 'codex'
-        ? { id: 'codex:default', driver: 'codex-app-server' }
-        : null
+      ? BUILT_IN_AGENT_PROFILES[profileOrAgent] || null
       : profileOrAgent;
   if (!profile?.driver) return null;
   const factory = DRIVER_FACTORIES[profile.driver];

package/src/runtimeProfiles.js

@@ -1,9 +1,11 @@
 import crypto from 'node:crypto';
 import { createLocalAgentAdapter } from './providers/index.js';
+import { cursorInstallCommand } from './providers/cursorAcp.js';
 
 const DRIVER_LABELS = {
   'codex-app-server': 'Codex',
   'claude-code-cli': 'Claude Code',
+  'cursor-acp': 'Cursor',
   'direct-byok': 'Local API key',
   opencode: 'OpenCode',
   acp: 'ACP agent',
@@ -171,9 +173,11 @@ export function diagnosticsFromAgentCheck(check, env = process.env) {
       'error',
       'cli_missing',
       check?.error || `${label} is not installed on this computer.`,
-      check?.agent === 'codex'
-        ? 'Install Codex (npm i -g @openai/codex), then restart the bridge.'
-        : 'Install Claude Code (npm i -g @anthropic-ai/claude-code), then restart the bridge.',
+      {
+        codex: 'Install Codex (npm i -g @openai/codex), then restart the bridge.',
+        cursor: `Install the Cursor CLI (${cursorInstallCommand()}), then restart the bridge.`,
+      }[check?.agent]
+        || 'Install Claude Code (npm i -g @anthropic-ai/claude-code), then restart the bridge.',
     );
   } else {
     add(
@@ -186,9 +190,11 @@ export function diagnosticsFromAgentCheck(check, env = process.env) {
         'error',
         'sign_in_required',
         check.error || `${label} is not signed in.`,
-        check.agent === 'codex'
-          ? 'Run `codex login` in a terminal, then restart the bridge.'
-          : 'Run `claude` in a terminal and sign in, then restart the bridge.',
+        {
+          codex: 'Run `codex login` in a terminal, then restart the bridge.',
+          cursor: 'Run `cursor-agent login` in a terminal, then restart the bridge.',
+        }[check.agent]
+          || 'Run `claude` in a terminal and sign in, then restart the bridge.',
       );
     } else {
       const method = text(check.authMethod || check.authMode, 80);
@@ -251,8 +257,37 @@ function normalizeDiagnostics(value) {
   };
 }
 
+// Cursor runs only Dexter's Framer tools: its own shell and file tools are
+// denied, so it cannot take App Builder workspace outcomes.
+function cursorProfileFromAgentCheck(check, env) {
+  return normalizeRuntimeProfile({
+    id: 'cursor:default',
+    instanceId: 'default',
+    label: DRIVER_LABELS['cursor-acp'],
+    driver: 'cursor-acp',
+    providerId: 'cursor',
+    authState: check.signedIn === false ? 'required' : 'ready',
+    capabilities: {
+      tools: true,
+      vision: true,
+      structuredOutput: true,
+      sessionResume: false,
+      progress: true,
+      cancellation: true,
+    },
+    models: check.modelDetails || [],
+    modelCatalog: {
+      source: check.modelCatalogSource || 'fallback',
+      refreshedAt: check.modelCatalogRefreshedAt,
+      modelCount: check.modelDetails?.length || 0,
+    },
+    diagnostics: diagnosticsFromAgentCheck(check, env),
+  });
+}
+
 function profileFromAgentCheck(check, env) {
   if (!check || check.installed === false) return null;
+  if (check.agent === 'cursor') return cursorProfileFromAgentCheck(check, env);
   const driver =
     check.agent === 'codex' ? 'codex-app-server' : check.agent === 'claude-code' ? 'claude-code-cli' : null;
   if (!driver) return null;