loreli 1.0.0 → 2.0.0

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

@@ -29,6 +29,13 @@ const READY_TIMEOUT = 60000;
  */
 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.
  *
@@ -51,12 +58,48 @@ const INPUT_READY_TIMEOUT = 15000;
  * @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.
    *
-   * cursor-agent CLI does not support `${env:NAME}` interpolation,
-   * so token propagation uses `envFile` pointing to `.git/loreli.env`
-   * (inherently unstageable). Hooks use beforeShellExecution.
+   * 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.
@@ -81,7 +124,9 @@ export class CursorBackend extends CliAgent {
         },
         {
           path: '.cursor/mcp.json',
-          content: mcpJson(context, context ? { envFile: '.git/loreli.env' } : {}),
+          content: mcpJson(context, context ? {
+            envFile: '.git/loreli.env'
+          } : {}),
           marker: 'loreli',
           format: 'json'
         }
@@ -113,6 +158,26 @@ export class CursorBackend extends CliAgent {
 
     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.
@@ -125,11 +190,12 @@ export class CursorBackend extends CliAgent {
    */
   constructor(opts) {
     const v = vendor(opts.identity?.provider ?? 'anthropic');
-    const model = resolve(opts.model ?? 'balanced', 'cursor', v, opts.config);
+    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)
+      command: buildCommand(model, opts.cwd, mode)
     });
 
     /** @type {string} Resolved model identifier. */
@@ -165,7 +231,7 @@ export class CursorBackend extends CliAgent {
   /**
    * Wait for cursor-agent to finish initializing.
    *
-   * Readiness is detected reactively through two phases:
+   * 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:
@@ -173,13 +239,20 @@ export class CursorBackend extends CliAgent {
    *  - 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. 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.
+   * active.
    *
    * @returns {Promise<void>}
    */
@@ -207,18 +280,18 @@ export class CursorBackend extends CliAgent {
       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).
-    // 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;
@@ -270,23 +343,27 @@ export class CursorBackend extends CliAgent {
  *
  * Flags:
  * - `--model`: resolved cursor-agent model name
- * - `--force`: auto-approve all tool usage
- * - `--sandbox disabled`: disable sandbox isolation prompts
+ * - `--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) {
-  const parts = [
-    'cursor-agent',
-    `--model ${model}`,
-    '--force',
-    '--sandbox disabled',
-    '--approve-mcps'
-  ];
+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}'`);
 

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

@@ -1,4 +1,8 @@
 import { execFileSync } from 'node:child_process';
+import { discover as discoverModels } from '../discover.js';
+import { logger } from 'loreli/log';
+
+const log = logger('backends');
 
 /**
  * Map of built-in backends with their module paths and metadata.
@@ -26,6 +30,15 @@ export class BackendRegistry {
     /** @type {Map<string, {name: string, provider: string, binary: string}>} */
     this.discovered = new Map();
 
+    /**
+     * Runtime-discovered models per backend. Populated by
+     * {@link discover} after binary detection. Keyed by backend
+     * name; each value contains a flat model list and a tier map.
+     *
+     * @type {Map<string, {models: object[], tiers: object}>}
+     */
+    this.models = new Map();
+
     /**
      * Failure counts per backend. Used to detect degraded backends
      * that repeatedly fail (e.g. budget exhaustion, rate limits).
@@ -33,6 +46,31 @@ export class BackendRegistry {
      * @type {Map<string, {count: number, first: number, last: number}>}
      */
     this._failures = new Map();
+
+    /**
+     * Warning counts per backend. Tracks transient issues (dialogs,
+     * prompts) that were successfully remediated. Only promotes to a
+     * failure after reaching the warning threshold.
+     *
+     * @type {Map<string, {count: number, first: number, last: number}>}
+     */
+    this._warnings = new Map();
+
+    /**
+     * Tracks whether model/backends discovery has already been completed
+     * for oneshot calls in this registry instance.
+     *
+     * @type {boolean}
+     */
+    this._discoveredOnce = false;
+
+    /**
+     * In-flight discovery promise used to prevent concurrent oneshot
+     * calls from racing discovery and clearing shared state.
+     *
+     * @type {Promise<void>|null}
+     */
+    this._discovering = null;
   }
 
   /**
@@ -49,13 +87,16 @@ export class BackendRegistry {
   }
 
   /**
-   * 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.
+   * Discover available backends by checking for CLI binaries on PATH,
+   * then discover available models from backends that support it.
    *
+   * Model discovery runs in parallel with backend class loading.
+   * Results are stored in {@link models} for use during resolution.
+   *
+   * @param {object} [config] - Optional config for discovery-time env overrides.
    * @returns {Promise<void>}
    */
-  async discover() {
+  async discover(config) {
     this.discovered.clear();
 
     for (const [name, meta] of Object.entries(BUILTIN_BACKENDS)) {
@@ -67,6 +108,9 @@ export class BackendRegistry {
         this.backends.set(name, { cls, provider: meta.provider, binary: meta.binary });
       }
     }
+
+    this.models = await discoverModels(this, { config });
+    this._discoveredOnce = true;
   }
 
   /**
@@ -150,6 +194,27 @@ export class BackendRegistry {
     return entry.count >= 2 && (Date.now() - entry.last) < window;
   }
 
+  /**
+   * Record a transient warning for a backend. Warnings track
+   * recoverable issues (dialogs dismissed, prompts answered) that
+   * don't indicate a systemic failure. After 3 warnings within the
+   * degradation window, promotes to a full failure.
+   *
+   * @param {string} name - Backend name (e.g. 'codex', 'claude').
+   */
+  recordWarning(name) {
+    const entry = this._warnings.get(name) ?? { count: 0, first: 0, last: 0 };
+    entry.count++;
+    if (!entry.first) entry.first = Date.now();
+    entry.last = Date.now();
+    this._warnings.set(name, entry);
+
+    if (entry.count >= 3) {
+      this.recordFailure(name);
+      this.recordFailure(name);
+    }
+  }
+
   /**
    * Clear failure history for a backend. Called when a backend
    * successfully completes work, proving it has recovered.
@@ -158,6 +223,26 @@ export class BackendRegistry {
    */
   clearFailures(name) {
     this._failures.delete(name);
+    this._warnings.delete(name);
+  }
+
+  /**
+   * Detect known blocking patterns in agent pane output using the
+   * backend's static diagnose() method.
+   *
+   * Each backend knows its own CLI's quirks — update dialogs, trust
+   * prompts, selection menus. This method delegates to the correct
+   * backend based on name, providing a regex-based fallback when LLM
+   * classification is unavailable.
+   *
+   * @param {string} name - Backend name (e.g. 'codex', 'claude').
+   * @param {string} output - Captured pane content.
+   * @returns {{category: string, reasoning: string}|null} Diagnosis, or null.
+   */
+  diagnose(name, output) {
+    const info = this.backends.get(name);
+    if (!info?.cls?.diagnose) return null;
+    return info.cls.diagnose(output);
   }
 
   /**
@@ -295,6 +380,78 @@ export class BackendRegistry {
     return paths;
   }
 
+  /**
+   * One-shot LLM call using the best available backend.
+   *
+   * Prefers backends with discovery data and falls back across all
+   * discovered oneshot-capable backends on failure.
+   *
+   * @param {string} prompt - Text prompt to send.
+   * @param {object} [opts] - Options forwarded to the backend's oneshot().
+   * @param {string} [opts.model='fast'] - Model alias or exact string.
+   * @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.
+   */
+  async oneshot(prompt, opts = {}) {
+    if (!this._discoveredOnce) {
+      if (!this._discovering) {
+        const self = this;
+        this._discovering = this.discover(opts.config).finally(function done() {
+          self._discovering = null;
+        });
+      }
+      await this._discovering;
+    }
+
+    const order = this._oneshotOrder();
+    if (!order.length) throw new Error('No backends available for oneshot');
+
+    let last;
+    for (const name of order) {
+      try {
+        const info = this.backends.get(name);
+        return await info.cls.oneshot(prompt, { ...opts, discovered: this.models });
+      } catch (err) {
+        last = err;
+        log.warn(`oneshot ${name} failed: ${err.message}`);
+      }
+    }
+
+    throw last;
+  }
+
+  /**
+   * Build backend order for oneshot calls.
+   *
+   * Backends with model discovery are tried first, followed by the
+   * remaining discovered backends that support static `oneshot()`.
+   *
+   * @returns {string[]} Ordered backend names.
+   */
+  _oneshotOrder() {
+    const order = [];
+    const seen = new Set();
+
+    for (const [name] of this.models) {
+      if (!this.backends.has(name)) continue;
+      const info = this.backends.get(name);
+      if (typeof info?.cls?.oneshot !== 'function') continue;
+      order.push(name);
+      seen.add(name);
+    }
+
+    for (const [name] of this.discovered) {
+      if (seen.has(name) || !this.backends.has(name)) continue;
+      const info = this.backends.get(name);
+      if (typeof info?.cls?.oneshot !== 'function') continue;
+      order.push(name);
+      seen.add(name);
+    }
+
+    return order;
+  }
+
   /**
    * Create a backend instance.
    *
@@ -307,7 +464,7 @@ export class BackendRegistry {
     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);
+    const agent = new info.cls({ ...opts, discovered: this.models });
     agent.backend = name;
     return agent;
   }

package/packages/agent/src/cli.js

@@ -1,3 +1,4 @@
+import { execFile as execFileCb } from 'node:child_process';
 import { Tmux } from 'loreli/tmux';
 import { Agent } from './base.js';
 import { inline } from './models.js';
@@ -47,6 +48,74 @@ export class CliAgent extends Agent {
   static scaffold() {
     return null;
   }
+  /**
+   * Run a CLI binary and return its stdout.
+   *
+   * Shared subprocess execution for all backend `oneshot()` methods.
+   * Each backend calls this with its own binary, args, and env vars.
+   *
+   * When `input` is provided it is written to the child's stdin and
+   * the stream is closed. CLI tools like `claude -p` and
+   * `cursor-agent -p` expect their prompt on stdin — passing it as
+   * a positional argument causes the process to block indefinitely
+   * waiting for piped input that never arrives.
+   *
+   * @param {string} binary - CLI binary name (e.g. 'claude', 'codex').
+   * @param {string[]} args - Command-line arguments.
+   * @param {object} [vars] - Additional environment variables.
+   * @param {number} [timeout=60000] - Max execution time in ms.
+   * @param {string} [input] - Text to write to stdin before closing.
+   * @returns {Promise<string>} Trimmed stdout.
+   */
+  static _exec(binary, args, vars, timeout, input) {
+    return new Promise(function run(resolve, reject) {
+      const child = execFileCb(binary, args, {
+        env: { ...process.env, ...vars },
+        timeout: timeout ?? 60000,
+        maxBuffer: 1024 * 1024
+      }, function done(err, stdout, stderrOutput) {
+        if (err) {
+          const code = err.code ?? 'none';
+          const signal = err.signal ?? 'none';
+          const killed = Boolean(err.killed);
+          const stderr = String(err.stderr ?? stderrOutput ?? '').slice(0, 200);
+          const wrapped = Object.assign(
+            new Error(`${binary} failed (code=${code}, signal=${signal}, killed=${killed}): ${stderr}`),
+            {
+              cause: err,
+              code: err.code,
+              signal: err.signal,
+              killed: err.killed,
+              stderr: err.stderr
+            }
+          );
+          return reject(wrapped);
+        }
+        resolve(stdout.trim());
+      });
+
+      if (input != null) {
+        child.stdin.write(input);
+        child.stdin.end();
+      }
+    });
+  }
+
+  /**
+   * One-shot LLM call via the CLI's non-interactive mode.
+   *
+   * Backends override this with their own binary, flags, model
+   * resolution, and env var collection. The base implementation
+   * throws to signal that the backend has not implemented it.
+   *
+   * @param {string} _prompt - Text prompt to send.
+   * @param {object} [_opts] - Options (model, config, timeout).
+   * @returns {Promise<string>} LLM response text.
+   */
+  static async oneshot(_prompt, _opts) {
+    throw new Error('Backend does not support oneshot — override static oneshot()');
+  }
+
   /**
    * @param {object} opts
    * @param {object} opts.identity - Agent identity.
@@ -92,7 +161,6 @@ export class CliAgent extends Agent {
   async spawn() {
     const cmd = this._shell(`exec ${this.command}`);
     this.paneId = await this._launch(cmd);
-    await this.tmux.set(this.paneId, 'remain-on-exit', 'on');
 
     log.info(`spawning ${this.identity?.name ?? '?'} in pane ${this.paneId}: ${this.command}`);
     this.transition('spawned');
@@ -123,14 +191,23 @@ export class CliAgent extends Agent {
    *
    * When the session already exists, a new window is added.
    *
+   * Sets `remain-on-exit` on every pane so dead process output is
+   * preserved for diagnosis. Backend subclasses override spawn() but
+   * all call _launch(), so this is the single point of enforcement.
+   *
    * @param {string} command - Shell command string.
    * @returns {Promise<string>} The assigned pane ID.
    */
   async _launch(command) {
+    let paneId;
     if (!await this.tmux.has(this.session)) {
-      return this.tmux.create(this.session, { cwd: this.cwd, command });
+      paneId = await this.tmux.create(this.session, { cwd: this.cwd, command });
+    } else {
+      paneId = await this.tmux.window(this.session, { cwd: this.cwd, command });
     }
-    return this.tmux.window(this.session, { cwd: this.cwd, command });
+
+    await this.tmux.set(paneId, 'remain-on-exit', 'on');
+    return paneId;
   }
 
   /**