loreli 0.0.0 → 1.0.0

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

@@ -0,0 +1,294 @@
+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;
+
+/**
+ * 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 {
+  /**
+   * Return the scaffold descriptor for Cursor Agent workspaces.
+   *
+   * cursor-agent CLI does not support `${env:NAME}` interpolation,
+   * so token propagation uses `envFile` pointing to `.git/loreli.env`
+   * (inherently unstageable). 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;
+  }
+  /**
+   * @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);
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd)
+    });
+
+    /** @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 two 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 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. This replaces the previous fixed-delay STABILIZE_MS timer
+   * with an event-driven check — the method returns as soon as the
+   * signal appears, not after a fixed sleep.
+   *
+   * @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 2: wait for TUI input readiness (reactive, not fixed delay).
+    // cursor-agent renders a workspace line containing a middle dot (·)
+    // and/or the prompt indicator once MCP servers are connected and the
+    // input field is ready. Polling pane output for this is faster than
+    // a fixed timer and adapts to varying startup speeds.
+    const inputDeadline = Date.now() + INPUT_READY_TIMEOUT;
+    while (Date.now() < inputDeadline) {
+      const output = await this.tmux.capture(this.paneId);
+
+      // The workspace line (`~/path · branch`) appears after MCP init.
+      // The middle dot (·) is a reliable delimiter cursor-agent uses
+      // between the path and branch name in its TUI header.
+      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
+ * - `--force`: auto-approve all tool usage
+ * - `--sandbox disabled`: disable sandbox isolation prompts
+ * - `--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.
+ * @returns {string} CLI command string.
+ */
+function buildCommand(model, cwd) {
+  const parts = [
+    'cursor-agent',
+    `--model ${model}`,
+    '--force',
+    '--sandbox disabled',
+    '--approve-mcps'
+  ];
+
+  if (cwd) parts.push(`--workspace '${cwd}'`);
+
+  return parts.join(' ');
+}

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

@@ -0,0 +1,329 @@
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Map of built-in backends with their module paths and metadata.
+ *
+ * @type {Record<string, {path: string, cls: string, binary: string, provider: string}>}
+ */
+const BUILTIN_BACKENDS = {
+  claude: { path: './claude.js', cls: 'ClaudeBackend', binary: 'claude', provider: 'anthropic' },
+  codex: { path: './codex.js', cls: 'CodexBackend', binary: 'codex', provider: 'openai' },
+  cursor: { path: './cursor.js', cls: 'CursorBackend', binary: 'cursor-agent', provider: 'multi' }
+};
+
+/**
+ * Discovers and manages available agent backends.
+ *
+ * Checks for CLI binaries on PATH and lazy-loads backend classes at
+ * discovery time. All backends are interactive CLI agents running in
+ * tmux panes.
+ */
+export class BackendRegistry {
+  constructor() {
+    /** @type {Map<string, {cls: Function|null, provider: string, binary?: string}>} */
+    this.backends = new Map();
+
+    /** @type {Map<string, {name: string, provider: string, binary: string}>} */
+    this.discovered = new Map();
+
+    /**
+     * Failure counts per backend. Used to detect degraded backends
+     * that repeatedly fail (e.g. budget exhaustion, rate limits).
+     *
+     * @type {Map<string, {count: number, first: number, last: number}>}
+     */
+    this._failures = new Map();
+  }
+
+  /**
+   * Register a backend class.
+   *
+   * @param {string} name - Backend name (e.g. 'claude', 'codex').
+   * @param {Function} cls - Backend class constructor.
+   * @param {object} meta - Backend metadata.
+   * @param {string} meta.provider - AI provider ('anthropic', 'openai').
+   * @param {string} [meta.binary] - CLI binary name to check on PATH.
+   */
+  register(name, cls, meta) {
+    this.backends.set(name, { cls, ...meta });
+  }
+
+  /**
+   * Discover available backends by checking for CLI binaries on PATH.
+   * Lazy-loads the actual backend class for each discovered binary so
+   * that create() can instantiate real agent instances.
+   *
+   * @returns {Promise<void>}
+   */
+  async discover() {
+    this.discovered.clear();
+
+    for (const [name, meta] of Object.entries(BUILTIN_BACKENDS)) {
+      if (which(meta.binary)) {
+        const mod = await import(meta.path);
+        const cls = mod[meta.cls];
+
+        this.discovered.set(name, { name, provider: meta.provider, binary: meta.binary });
+        this.backends.set(name, { cls, provider: meta.provider, binary: meta.binary });
+      }
+    }
+  }
+
+  /**
+   * List all discovered (available) backends.
+   *
+   * @returns {Array<{name: string, provider: string, binary: string}>}
+   */
+  available() {
+    return [...this.discovered.values()];
+  }
+
+  /**
+   * List unique providers from discovered backends.
+   *
+   * When cursor-agent is discovered (provider `multi`), it is expanded
+   * into `cursor-openai` and `cursor-anthropic` virtual providers.
+   * This makes every provider in the returned list directly usable for
+   * identity acquisition and yin/yang pairing.
+   *
+   * @returns {string[]} Array of provider names.
+   */
+  providers() {
+    const providerSet = new Set();
+    for (const info of this.discovered.values()) {
+      if (info.provider === 'multi') {
+        providerSet.add('cursor-openai');
+        providerSet.add('cursor-anthropic');
+      } else if (info.provider !== 'unknown') {
+        providerSet.add(info.provider);
+      }
+    }
+    return [...providerSet];
+  }
+
+  /**
+   * Check if a specific backend is available.
+   *
+   * @param {string} name - Backend name.
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.backends.has(name);
+  }
+
+  /**
+   * Get a backend entry by name.
+   *
+   * @param {string} name - Backend name.
+   * @returns {{cls: Function|null, provider: string, binary?: string}|undefined}
+   */
+  get(name) {
+    return this.backends.get(name);
+  }
+
+  /**
+   * Record a backend failure. Repeated failures within a time window
+   * mark the backend as degraded, triggering fallback to cursor-agent.
+   *
+   * @param {string} name - Backend name (e.g. 'codex', 'claude').
+   */
+  recordFailure(name) {
+    const entry = this._failures.get(name) ?? { count: 0, first: 0, last: 0 };
+    entry.count++;
+    if (!entry.first) entry.first = Date.now();
+    entry.last = Date.now();
+    this._failures.set(name, entry);
+  }
+
+  /**
+   * Check if a backend is degraded. A backend is degraded when it has
+   * 2+ failures within the last 30 minutes — indicating a systemic
+   * issue like budget exhaustion or API outage.
+   *
+   * @param {string} name - Backend name.
+   * @returns {boolean} True if the backend is degraded.
+   */
+  degraded(name) {
+    const entry = this._failures.get(name);
+    if (!entry) return false;
+    const window = 30 * 60 * 1000;
+    return entry.count >= 2 && (Date.now() - entry.last) < window;
+  }
+
+  /**
+   * Clear failure history for a backend. Called when a backend
+   * successfully completes work, proving it has recovered.
+   *
+   * @param {string} name - Backend name.
+   */
+  clearFailures(name) {
+    this._failures.delete(name);
+  }
+
+  /**
+   * Select the best backend for a given AI provider.
+   *
+   * Resolution order:
+   *  1. Virtual cursor providers (`cursor-openai`, `cursor-anthropic`)
+   *     route directly to the cursor backend
+   *  2. Exact provider match (claude for anthropic, codex for openai)
+   *     — skipped when the matched backend is degraded and a multi-
+   *     provider fallback exists
+   *  3. Multi-provider backend (cursor-agent — runs any provider)
+   *  4. Generic default fallback via {@link defaultBackend}
+   *
+   * @param {string} provider - AI provider ('anthropic', 'openai', 'cursor-openai', 'cursor-anthropic').
+   * @returns {string} Backend name.
+   * @throws {Error} When no suitable backend is available.
+   */
+  forProvider(provider) {
+    if (provider?.startsWith('cursor-')) {
+      for (const info of this.discovered.values()) {
+        if (info.provider === 'multi') return info.name;
+      }
+    }
+
+    for (const info of this.discovered.values()) {
+      if (info.provider === provider) {
+        if (this.degraded(info.name)) {
+          const cursor = this._cursorFallback();
+          if (cursor) return cursor;
+        }
+        return info.name;
+      }
+    }
+
+    for (const info of this.discovered.values()) {
+      if (info.provider === 'multi') return info.name;
+    }
+
+    return this.defaultBackend();
+  }
+
+  /**
+   * Find the cursor (multi-provider) backend among discovered backends.
+   *
+   * @returns {string|null} Backend name, or null if not available.
+   */
+  _cursorFallback() {
+    for (const info of this.discovered.values()) {
+      if (info.provider === 'multi') return info.name;
+    }
+    return null;
+  }
+
+  /**
+   * Return the default backend name using priority:
+   *  1. claude (Anthropic)
+   *  2. cursor (multi-provider)
+   *  3. first discovered backend
+   *
+   * @returns {string} Backend name.
+   * @throws {Error} When no backends are available.
+   */
+  defaultBackend() {
+    if (this.discovered.has('claude')) return 'claude';
+    if (this.discovered.has('cursor')) return 'cursor';
+
+    const first = this.discovered.keys().next();
+    if (!first.done) return first.value;
+
+    throw new Error('No backends available — install claude, cursor-agent, or codex CLI');
+  }
+
+  /**
+   * Resolve the best backend for a provider with optional explicit override.
+   *
+   * Resolution order:
+   *  1. Explicit override: if provided and registered, use it directly
+   *  2. Provider-native match via {@link forProvider}
+   *
+   * @param {string} provider - AI provider ('anthropic', 'openai', 'cursor-openai', 'cursor-anthropic').
+   * @param {string} [explicit] - Explicitly requested backend name.
+   * @returns {string} Backend name.
+   * @throws {Error} When no suitable backend is available.
+   */
+  resolve(provider, explicit) {
+    if (explicit && this.has(explicit)) return explicit;
+    return this.forProvider(provider);
+  }
+
+  /**
+   * Collect scaffold descriptors from all registered backends.
+   *
+   * Calls the static `scaffold(context)` method on every backend
+   * class that defines one. Returns a flat array of descriptors
+   * that `workspace.prepare()` can write generically.
+   *
+   * @param {object} [context] - Agent context for env/token injection.
+   * @returns {object[]} Array of scaffold descriptors.
+   */
+  scaffoldAll(context) {
+    const descriptors = [];
+    for (const [, info] of this.backends) {
+      if (typeof info.cls?.scaffold === 'function') {
+        const descriptor = info.cls.scaffold(context);
+        if (descriptor) descriptors.push(descriptor);
+      }
+    }
+    return descriptors;
+  }
+
+  /**
+   * Collect config path metadata from all registered backends.
+   *
+   * Returns the union of `configs` entries from all backend scaffold
+   * descriptors — used by the start tool to know which files to
+   * ensure in the remote repository.
+   *
+   * @returns {Array<{path: string, marker: string, format: string}>}
+   */
+  configPaths() {
+    const seen = new Set();
+    const paths = [];
+    for (const [, info] of this.backends) {
+      if (typeof info.cls?.scaffold !== 'function') continue;
+      const descriptor = info.cls.scaffold();
+      if (!descriptor?.configs) continue;
+      for (const cfg of descriptor.configs) {
+        if (!seen.has(cfg.path)) {
+          seen.add(cfg.path);
+          paths.push({ path: cfg.path, marker: cfg.marker, format: cfg.format });
+        }
+      }
+    }
+    return paths;
+  }
+
+  /**
+   * Create a backend instance.
+   *
+   * @param {string} name - Backend name.
+   * @param {object} opts - Options passed to the backend constructor.
+   * @returns {object} Backend instance.
+   * @throws {Error} When the backend is not registered or has no class.
+   */
+  create(name, opts) {
+    const info = this.backends.get(name);
+    if (!info) throw new Error(`Unknown backend: "${name}"`);
+    if (!info.cls) throw new Error(`Backend "${name}" has no implementation class registered`);
+    const agent = new info.cls(opts);
+    agent.backend = name;
+    return agent;
+  }
+}
+
+/**
+ * Check if a binary exists on PATH.
+ *
+ * @param {string} binary - Binary name to check.
+ * @returns {boolean} True if the binary is on PATH.
+ */
+function which(binary) {
+  try {
+    execFileSync('which', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}