loreli 0.0.0 → 2.0.0

package/packages/agent/src/backends/cursor.js

@@ -0,0 +1,371 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliAgent } from '../cli.js';
+import { resolve, env } from '../models.js';
+import { mcpJson, cursorMatcher } from 'loreli/workspace';
+import { vendor } from 'loreli/identity';
+import { logger } from 'loreli/log';
+
+const log = logger('cursor');
+
+/**
+ * Interval for polling pane content during startup.
+ * @type {number}
+ */
+const READY_POLL = 1000;
+
+/**
+ * Maximum time to wait for cursor-agent to become ready.
+ * @type {number}
+ */
+const READY_TIMEOUT = 60000;
+
+/**
+ * Maximum time (ms) to wait for the TUI input prompt after the banner
+ * appears. This is NOT a fixed sleep — the readiness loop polls for
+ * a concrete signal (workspace path line rendered in the pane).
+ *
+ * @type {number}
+ */
+const INPUT_READY_TIMEOUT = 15000;
+
+/**
+ * Settle delay (ms) after Phase 1 before sending the trust-approval
+ * keystroke. Gives cursor-agent time to render the trust dialog.
+ * @type {number}
+ */
+const TRUST_SETTLE = 2000;
+
+/**
+ * Cursor Agent CLI backend. Interactive: stays running in a tmux pane.
+ *
+ * Cursor Agent is the multi-provider workhorse — it can run models from
+ * Anthropic, OpenAI, Google, and others through a single CLI. This makes
+ * it the natural fallback when provider-specific CLIs (claude, codex) are
+ * unavailable or their API endpoints are unreachable.
+ *
+ * The yin/yang adversarial pairing is preserved because each agent's
+ * identity carries its provider. The model resolver maps `balanced` to
+ * `claude-sonnet-4-20250514` for anthropic and `gpt-4o` for openai.
+ * The CURSOR_MODELS table then translates those API identifiers into
+ * cursor-agent short names.
+ *
+ * Flags:
+ * - `--force`: auto-approve tool usage (file writes, bash commands)
+ * - `--sandbox disabled`: no sandbox isolation prompts
+ * - `--approve-mcps`: auto-approve scaffolded Loreli MCP server
+ *
+ * @extends CliAgent
+ */
+export class CursorBackend extends CliAgent {
+  /**
+   * Regex patterns that identify known Cursor Agent blocking dialogs.
+   *
+   * @type {Array<{pattern: RegExp, category: string, reasoning: string, remedy?: string[]}>}
+   */
+  static patterns = [
+    {
+      pattern: /ready to build\?[\s\S]*no,\s*propose changes\s*\(p\s*or\s*esc\)/i,
+      category: 'option_dialog',
+      reasoning: 'Cursor plan-mode summary dialog blocks planner execution until a choice is made',
+      remedy: ['p']
+    },
+    {
+      pattern: /read the complete task instructions from[\s\S]*follow every instruction precisely\./i,
+      category: 'option_dialog',
+      reasoning: 'Cursor can remain on the initial injected prompt until an explicit continuation Enter key',
+      remedy: ['Enter']
+    }
+  ];
+
+  /**
+   * Detect known Cursor Agent CLI blocking patterns in pane output.
+   *
+   * @param {string} output - Captured pane content.
+   * @returns {{category: string, reasoning: string, remedy?: string[]}|null} Diagnosis, or null if unrecognized.
+   */
+  static diagnose(output) {
+    if (!output) return null;
+    for (const { pattern, category, reasoning, remedy } of CursorBackend.patterns) {
+      if (pattern.test(output)) return { category, reasoning, ...(remedy && { remedy }) };
+    }
+    return null;
+  }
+
+  /**
+   * Return the scaffold descriptor for Cursor Agent workspaces.
+   *
+   * Token propagation relies on process env inheritance and the
+   * envFile fallback. cursor-agent CLI does not expand
+   * `${env:NAME}` interpolation — it passes the literal string
+   * to MCP subprocesses, poisoning `_hydrateHub()`.
+   * Hooks use beforeShellExecution.
+   *
+   * @param {object} [context] - Agent context for env/token injection.
+   * @returns {object} Scaffold descriptor.
+   */
+  static scaffold(context) {
+    const denied = context?.denied ?? [];
+
+    const dangerousCommands = [
+      ...denied,
+      'git', 'rm', 'mv', 'chmod', 'sed', 'perl', 'tee', 'truncate',
+      'node', 'python', 'python3', 'ruby'
+    ];
+    const unique = [...new Set(dangerousCommands)];
+
+    const descriptor = {
+      configs: [
+        {
+          path: '.mcp.json',
+          content: mcpJson(context, context ? { tokenRef: '${GITHUB_TOKEN}' } : {}),
+          marker: 'loreli',
+          format: 'json'
+        },
+        {
+          path: '.cursor/mcp.json',
+          content: mcpJson(context, context ? {
+            envFile: '.git/loreli.env'
+          } : {}),
+          marker: 'loreli',
+          format: 'json'
+        }
+      ],
+      hooks: [
+        {
+          path: '.cursor/hooks.json',
+          key: 'beforeShellExecution',
+          entry: {
+            command: '.loreli/deny.sh',
+            matcher: cursorMatcher(unique)
+          },
+          marker: 'deny.sh',
+          defaults: { version: 1 }
+        }
+      ],
+      files: []
+    };
+
+    // Declare .git/loreli.env for token propagation. Written by
+    // workspace.create() after clone when .git/ exists.
+    if (context?.token) {
+      descriptor.files.push({
+        path: '.git/loreli.env',
+        content: `GITHUB_TOKEN=${context.token}\n`,
+        mode: 0o600
+      });
+    }
+
+    return descriptor;
+  }
+  /**
+   * One-shot LLM call via `cursor-agent -p` (print mode).
+   *
+   * @param {string} prompt - Text prompt to send.
+   * @param {object} [opts] - Options.
+   * @param {string} [opts.model='fast'] - Model alias or exact string.
+   * @param {string} [opts.provider='anthropic'] - Provider for model resolution.
+   * @param {object} [opts.config] - Config instance for model resolution.
+   * @param {number} [opts.timeout=60000] - Max execution time in ms.
+   * @returns {Promise<string>} LLM response text.
+   */
+  static async oneshot(prompt, { model, provider, config, timeout, discovered } = {}) {
+    const v = vendor(provider ?? 'anthropic');
+    const resolved = resolve(model ?? 'fast', 'cursor', v, config, discovered);
+    const vars = env('cursor', config) ?? {};
+    return CliAgent._exec('cursor-agent', [
+      '-p', '--trust', '--model', resolved, '--output-format', 'text'
+    ], vars, timeout, prompt);
+  }
+
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity.
+   * @param {string} opts.role - Agent role.
+   * @param {string} opts.cwd - Working directory.
+   * @param {string} [opts.model='balanced'] - Model alias or exact string.
+   * @param {object} [opts.config] - Config instance for model resolution.
+   * @param {string} [opts.session='loreli'] - Tmux session name.
+   * @param {number} [opts.readyTimeout=60000] - Max ms to wait for CLI readiness.
+   */
+  constructor(opts) {
+    const v = vendor(opts.identity?.provider ?? 'anthropic');
+    const model = resolve(opts.model ?? 'balanced', 'cursor', v, opts.config, opts.discovered);
+    const mode = opts.role === 'planner' ? 'plan' : undefined;
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd, mode)
+    });
+
+    /** @type {string} Resolved model identifier. */
+    this.model = model;
+
+    /** @type {object|undefined} Backend-specific environment variables. */
+    this._env = env('cursor', opts.config) ?? {};
+
+    if (opts.context?.token) this._env.GITHUB_TOKEN = opts.context.token;
+
+    /** @type {number} Max ms to wait for CLI readiness. */
+    this.readyTimeout = opts.readyTimeout ?? READY_TIMEOUT;
+  }
+
+  /**
+   * Spawn cursor-agent and wait for readiness.
+   *
+   * Builds an inline shell command with env exports and passes it
+   * directly to tmux — no launcher scripts on disk.
+   *
+   * @returns {Promise<void>}
+   */
+  async spawn() {
+    const cmd = this._shell(`exec ${this.command}`, this._env);
+    this.paneId = await this._launch(cmd);
+
+    log.info(`spawning ${this.identity?.name ?? '?'} in pane ${this.paneId}: ${this.command}`);
+    this.transition('spawned');
+
+    await this._navigate();
+  }
+
+  /**
+   * Wait for cursor-agent to finish initializing.
+   *
+   * Readiness is detected reactively through three phases:
+   *
+   * **Phase 1 — Process detection** (up to `readyTimeout`):
+   * Polls until the cursor-agent Node process is running. Two signals:
+   *  - Banner: `Cursor Agent v<version>` appears in pane output.
+   *  - Process: tmux reports `node` or a version string as the
+   *    foreground command.
+   *
+   * **Phase 1.5 — Trust approval**:
+   * cursor-agent shows a "Workspace Trust" dialog for directories
+   * not previously trusted. The dialog blocks all TUI rendering.
+   * `--force` only auto-approves command execution, not workspace
+   * trust, and `--trust` only works in `--print` mode. Sending
+   * Enter dismisses the dialog (default action = approve). When
+   * no dialog is showing, the keystroke enters the empty input
+   * field harmlessly.
+   *
+   * **Phase 2 — Input readiness** (up to `INPUT_READY_TIMEOUT`):
+   * After the process starts, continues polling pane output for the
+   * TUI's workspace line (e.g. `~/path · branch`). This line renders
+   * only after MCP connections are established and the input field is
+   * active.
+   *
+   * @returns {Promise<void>}
+   */
+  async _navigate() {
+    if (this.readyTimeout <= 0) return;
+
+    const deadline = Date.now() + this.readyTimeout;
+    const name = this.identity?.name ?? '?';
+
+    // Phase 1: detect cursor-agent process startup
+    while (Date.now() < deadline) {
+      const output = await this.tmux.capture(this.paneId);
+
+      if (output.includes('Cursor Agent v')) {
+        log.info(`${name} phase 1 — cursor-agent banner detected`);
+        break;
+      }
+
+      const cmd = await this.tmux.command(this.paneId);
+      if (cmd === 'node' || /^\d+\.\d+\.\d+/.test(cmd)) {
+        log.info(`${name} phase 1 — cursor-agent process detected (${cmd})`);
+        break;
+      }
+
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    // Phase 1.5: dismiss "Workspace Trust" dialog if present.
+    // cursor-agent blocks on an interactive trust prompt for
+    // programmatically-created workspaces. Enter approves it.
+    await new Promise(function settle(r) { setTimeout(r, TRUST_SETTLE); });
+    await this.tmux.keys(this.paneId, 'Enter');
+    log.info(`${name} phase 1.5 — sent trust approval (Enter)`);
+
+    // Phase 2: wait for TUI input readiness (reactive, not fixed delay).
+    const inputDeadline = Date.now() + INPUT_READY_TIMEOUT;
+    while (Date.now() < inputDeadline) {
+      const output = await this.tmux.capture(this.paneId);
+
+      if (output.includes('\u00b7')) {
+        log.info(`${name} phase 2 — TUI input ready (workspace line detected)`);
+        return;
+      }
+
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    log.warn(`${name} input readiness timeout after ${INPUT_READY_TIMEOUT}ms — proceeding anyway`);
+  }
+
+  /**
+   * Send a prompt to cursor-agent's interactive session.
+   *
+   * Multi-line prompts are written to a Markdown file and a single-line
+   * reference is sent, matching the ClaudeBackend pattern. This avoids
+   * tmux send-keys fragmenting the message at newlines.
+   *
+   * @param {string} message - The prompt text.
+   * @returns {Promise<void>}
+   */
+  async send(message) {
+    if (!this.paneId) throw new Error('Agent not spawned — call spawn() first');
+    if (this.canTransition('working')) this.transition('working');
+
+    if (!message.includes('\n')) {
+      await this.tmux.send(this.paneId, message);
+      return;
+    }
+
+    const dir = join(this.cwd, '.loreli');
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, `task-${Date.now()}.md`);
+    await writeFile(file, message, 'utf8');
+    log.info(`${this.identity?.name ?? '?'} prompt written to ${file}`);
+
+    await this.tmux.send(this.paneId,
+      `Read the complete task instructions from ${file} and execute them. Follow every instruction precisely.`
+    );
+  }
+}
+
+/**
+ * Build the cursor-agent CLI command string.
+ *
+ * Model names are resolved directly from config — no translation table.
+ * The `backends.cursor.models` config maps tiers to cursor-agent native
+ * names per provider (e.g. `sonnet-4.5-thinking`, `gpt-5.3-codex`).
+ *
+ * Flags:
+ * - `--model`: resolved cursor-agent model name
+ * - `--plan`: read-only plan mode (planner)
+ * - `--force`: auto-approve tool prompts (all roles; required for unattended planner MCP calls)
+ * - `--sandbox disabled`: disable sandbox isolation prompts (action/reviewer)
+ * - `--approve-mcps`: auto-approve the scaffolded Loreli MCP server
+ * - `--workspace`: set the working directory
+ *
+ * @param {string} model - Resolved cursor-agent model name from config.
+ * @param {string} [cwd] - Working directory for --workspace.
+ * @param {string} [mode] - Execution mode ('plan' for planner read-only mode).
+ * @returns {string} CLI command string.
+ */
+function buildCommand(model, cwd, mode) {
+  const parts = ['cursor-agent', `--model ${model}`];
+
+  if (mode === 'plan') {
+    parts.push('--plan', '--force');
+  } else {
+    parts.push('--force', '--sandbox disabled');
+  }
+
+  parts.push('--approve-mcps');
+
+  if (cwd) parts.push(`--workspace '${cwd}'`);
+
+  return parts.join(' ');
+}