loreli 1.0.0 → 2.0.0

package/packages/agent/README.md

@@ -323,9 +323,9 @@ await prepare('~/.loreli/workspaces/loreli-optimus-0', {
 
 ### Model Aliases
 
-Loreli provides human-friendly model aliases that resolve to backend-specific and provider-specific identifiers. Resolution is config-driven — aliases map to concrete model IDs through the standard config resolution chain (overrides > loreli.yml > defaults).
+Loreli provides human-friendly model aliases (`fast`, `balanced`, `powerful`) that resolve to backend-specific and provider-specific model identifiers. Resolution combines config overrides, runtime discovery, and static fallbacks to always produce a valid model ID.
 
-The `resolve()` function takes an alias, backend name, provider, and optional `config` parameter. It looks up `config.get('backends.{backend}.models.{alias}.{provider}')` first, then falls through to built-in defaults from `defaults.js`. Exact model strings (not matching any alias) are returned unchanged.
+The `resolve()` function takes an alias, backend name, provider, optional config, and optional discovery cache. Exact model strings (not matching any alias) are returned unchanged.
 
 The following example demonstrates basic alias resolution using built-in defaults. Each backend has its own model mappings — the claude backend resolves to provider-specific model IDs, while the cursor backend resolves to cursor-agent short names:
 
@@ -338,7 +338,7 @@ models.resolve('fast', 'cursor', 'anthropic');    // 'sonnet-4.5'
 models.resolve('gpt-custom', 'codex', 'openai'); // 'gpt-custom' (passthrough)
 ```
 
-The following example demonstrates overriding model IDs via config. This is useful when your environment routes through a different proxy or you have access to newer model versions:
+The following example demonstrates overriding model IDs via config. This is useful when your environment routes through a LiteLLM proxy or you have access to newer model versions:
 
 ```js
 import { models } from 'loreli/agent';
@@ -359,7 +359,50 @@ models.resolve('fast', 'codex', 'openai', config);     // 'my-custom-gpt'
 models.resolve('balanced', 'codex', 'openai', config);  // 'gpt-5.1-codex' (falls to defaults)
 ```
 
-#### Default Model Mappings
+#### Resolution Chain
+
+Model resolution follows a four-layer priority chain:
+
+1. **Config override** — `backends.{name}.models.{alias}.{provider}` from `loreli.yml` or `config.merge()`. Always wins. This is the escape hatch for LiteLLM proxies, private deployments, and custom model names.
+2. **Runtime discovery** — models discovered at startup from backend CLIs and configured proxy endpoints. `cursor-agent` uses `--list-models`. `claude`/`codex` use OpenAI-compatible model listing (`/v1/models` with `/models` fallback) when `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` is configured. Discovered models are classified into tiers by name-pattern heuristics and cached on the `BackendRegistry`.
+3. **Static fallbacks** — built-in defaults from `defaults.js`. When discovery data is available, static fallbacks are validated against the discovered model list. Invalid models trigger a warning and fall back to the backend's default discovered model.
+4. **Pass-through** — exact model strings (those not matching any alias) bypass resolution entirely.
+
+#### Auto Model Discovery
+
+At startup, `BackendRegistry.discover()` probes available backends for their supported models:
+
+| Backend | Discovery Method | Behavior |
+|---------|-----------------|----------|
+| `cursor-agent` | `--list-models` CLI flag | Parses structured output, classifies into tiers per provider |
+| `claude` | Proxy model listing (`/v1/models` / `/models`) when `ANTHROPIC_BASE_URL` is configured | Auth uses `ANTHROPIC_API_KEY` first, then `OPENAI_API_KEY`; if discovery is unavailable, static defaults are used |
+| `codex` | Proxy model listing (`/v1/models` / `/models`) when `OPENAI_BASE_URL` is configured | Auth uses `OPENAI_API_KEY` first, then `ANTHROPIC_API_KEY`; if discovery is unavailable, static defaults are used |
+
+Proxy requests use `timeouts.proxyDiscovery` from config (default `5000` ms). This controls the per-request HTTP timeout for `/v1/models` / `/models` discovery calls.
+
+For all runtime-discovered models, tiers are inferred from name-pattern heuristics:
+
+| Tier | Patterns |
+|------|----------|
+| `powerful` | `-xhigh`, `-max`, `-high`, `opus-*`, `o3` |
+| `balanced` | No tier suffix, `-thinking` (non-opus), bare codex |
+| `fast` | `-low`, `-mini`, `haiku-*`, `o4-mini` |
+
+Discovery results override static defaults but are themselves overridden by explicit config. When discovery fails or is unavailable (including direct non-proxy setups), static fallbacks are used unchanged.
+
+#### Validation
+
+When discovery data is available for a backend, resolved model IDs are validated against the discovered model list. If a resolved model (from static defaults or config) is not found in the discovered list, a warning is logged and the backend's default model is used instead. This catches:
+
+- Stale static defaults (model IDs removed by providers)
+- Typos in `loreli.yml` backend model overrides
+- Models no longer available in the current subscription/plan
+
+When no discovery data is available (discovery failed, backend doesn't support it, or backend not installed), validation is skipped and models pass through as before.
+
+#### Static Default Mappings
+
+These are the built-in fallback model IDs used when neither config nor discovery provides a value:
 
 **Claude backend** (Anthropic model IDs):
 
@@ -385,33 +428,31 @@ models.resolve('balanced', 'codex', 'openai', config);  // 'gpt-5.1-codex' (fall
 | `balanced` | `sonnet-4.5-thinking` | `gpt-5.3-codex` |
 | `powerful` | `opus-4.6-thinking` | `gpt-5.1-codex-max` |
 
-#### Overriding via `loreli.yml`
+#### LiteLLM / Proxy Override
 
-Add a `backends` section to the target repo's `loreli.yml` to override the defaults. Unknown backends, tiers, and providers are passed through, so custom configurations work out of the box:
+When backends are behind a LiteLLM proxy or custom gateway, model discovery will query the configured base URL and validate resolved IDs against the returned model list. If your proxy uses custom aliases, override via `loreli.yml`:
 
 ```yaml
 backends:
   claude:
+    env:
+      ANTHROPIC_BASE_URL: https://your-litellm.example.com/v1
     models:
       fast:
-        anthropic: my-proxy-haiku
+        anthropic: litellm/haiku
       balanced:
-        anthropic: my-proxy-sonnet
+        anthropic: litellm/sonnet
+      powerful:
+        anthropic: litellm/opus
   codex:
+    env:
+      OPENAI_BASE_URL: https://your-litellm.example.com/v1
     models:
       fast:
-        openai: my-proxy-gpt-mini
+        openai: litellm/gpt-mini
 ```
 
-#### Resolution Chain
-
-Model resolution follows the same priority as all config values:
-
-1. **Start params** — `config.merge({ backends: { claude: { models: { ... } } } })`
-2. **`loreli.yml`** — `backends.{name}.models` section in the target repo
-3. **Built-in defaults** — hardcoded in `defaults.js`
-
-Exact model strings (those not matching any alias) bypass resolution entirely.
+Config overrides always take precedence — discovery and static defaults are bypassed entirely when `backends.{name}.models` is configured.
 
 ### Backend Environment Variables
 
@@ -501,6 +542,54 @@ Backend selection is handled entirely by `BackendRegistry.forProvider()`. The or
 | Mixed (e.g. claude + cursor-agent) | Exact match first, cursor fills the gap |
 | Nothing available | Error with installation guidance |
 
+## One-Shot LLM Calls (`oneshot`)
+
+Each backend provides a static `oneshot(prompt, opts)` method for non-interactive LLM calls. This uses the CLI's print/exec mode (`child_process.execFile`) — no tmux, no workspace, no agent lifecycle. It reuses the same model resolution and environment variable collection as interactive agents.
+
+The `BackendRegistry` also exposes a convenience `oneshot()` that discovers once, orders backends with discovery-backed entries first, and falls back across remaining oneshot-capable backends when one fails.
+
+### Usage
+
+```js
+import { BackendRegistry, ClaudeBackend } from 'loreli/agent';
+
+// Via specific backend
+const answer = await ClaudeBackend.oneshot('Summarize this text...', {
+  model: 'fast',
+  timeout: 30000
+});
+
+// Via registry (discovery-first ordering + fallback)
+const backends = new BackendRegistry();
+await backends.discover();
+const result = await backends.oneshot('Classify this output...', { model: 'fast' });
+```
+
+### Backend CLI Flags
+
+| Backend | Binary | Print Mode |
+|---------|--------|------------|
+| Claude | `claude` | `-p <prompt> --model <model> --output-format text` |
+| Codex | `codex` | `exec --ephemeral --skip-git-repo-check <prompt> -m <model>` |
+| Cursor | `cursor-agent` | `-p <prompt> --model <model> --output-format text` |
+
+### API
+
+#### `Backend.oneshot(prompt, opts)` (static)
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt` | `string` | — | Text prompt to send. |
+| `opts.model` | `string` | `'fast'` | Model alias or exact string. |
+| `opts.config` | `Config` | `undefined` | Config instance for model resolution. |
+| `opts.timeout` | `number` | `30000` | Max execution time in ms. |
+
+**Returns:** `Promise<string>` — LLM response text (trimmed).
+
+#### `BackendRegistry.oneshot(prompt, opts)`
+
+Same parameters as above. Runs discovery once (with optional `opts.config`), then tries backends in order until one succeeds.
+
 ## Session Persistence
 
 Agents are spawned detached — they survive orchestrator shutdown. State is persisted to `~/.loreli/sessions/<id>/`:

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

@@ -38,6 +38,40 @@ const READY_TIMEOUT = 60000;
  * @extends CliAgent
  */
 export class ClaudeBackend extends CliAgent {
+  /**
+   * Regex patterns that identify known Claude CLI blocking dialogs.
+   *
+   * @type {Array<{pattern: RegExp, category: string, reasoning: string, remedy?: string[]}>}
+   */
+  static patterns = [
+    {
+      pattern: /yes,\s*i\s+accept/i,
+      category: 'option_dialog',
+      reasoning: 'Claude CLI showing bypass-permissions dialog requiring selection',
+      remedy: ['Enter']
+    },
+    {
+      pattern: /do you want to proceed\?[\s\S]*yes,\s*and don't ask again(?:\s+for loreli\s*-\s*[a-z-]+\s*commands)?/i,
+      category: 'option_dialog',
+      reasoning: 'Claude CLI asking MCP tool approval for a Loreli command',
+      remedy: ['2', 'Enter']
+    }
+  ];
+
+  /**
+   * Detect known Claude 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 ClaudeBackend.patterns) {
+      if (pattern.test(output)) return { category, reasoning, ...(remedy && { remedy }) };
+    }
+    return null;
+  }
+
   /**
    * Return the scaffold descriptor for Claude Code workspaces.
    *
@@ -83,6 +117,28 @@ export class ClaudeBackend extends CliAgent {
       files: []
     };
   }
+  /**
+   * One-shot LLM call via `claude -p` (print mode).
+   *
+   * No tmux, no workspace, no identity — just a subprocess that
+   * prints the response and exits. Uses the same model resolution
+   * and env var collection as interactive agents.
+   *
+   * @param {string} prompt - Text prompt to send.
+   * @param {object} [opts] - Options.
+   * @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.
+   */
+  static async oneshot(prompt, { model, config, timeout, discovered } = {}) {
+    const resolved = resolve(model ?? 'fast', 'claude', 'anthropic', config, discovered);
+    const vars = env('claude', config) ?? {};
+    return CliAgent._exec('claude', [
+      '-p', '--model', resolved, '--output-format', 'text'
+    ], vars, timeout, prompt);
+  }
+
   /**
    * @param {object} opts
    * @param {object} opts.identity - Agent identity.
@@ -94,13 +150,15 @@ export class ClaudeBackend extends CliAgent {
    * @param {number} [opts.readyTimeout=60000] - Max ms to wait for CLI readiness.
    */
   constructor(opts) {
-    const model = resolve(opts.model ?? 'balanced', 'claude', 'anthropic', opts.config);
+    const model = resolve(opts.model ?? 'balanced', 'claude', 'anthropic', opts.config, opts.discovered);
 
     const denied = opts.config?.get?.('agents.disallowedTools') ?? [];
 
+    const mode = opts.role === 'planner' ? 'plan' : undefined;
+
     super({
       ...opts,
-      command: buildCommand(model, opts.cwd, denied)
+      command: buildCommand(model, opts.cwd, denied, mode)
     });
 
     /** @type {string} Resolved model identifier. */
@@ -113,6 +171,9 @@ export class ClaudeBackend extends CliAgent {
 
     /** @type {number} Max ms to wait for CLI readiness. */
     this.readyTimeout = opts.readyTimeout ?? READY_TIMEOUT;
+
+    /** @type {boolean} Whether MCP readiness (Phase 2) was confirmed. */
+    this._mcpReady = false;
   }
 
   /**
@@ -167,8 +228,7 @@ export class ClaudeBackend extends CliAgent {
       try {
         output = await this.tmux.capture(this.paneId);
       } catch {
-        log.warn(`${name} pane died during readiness check — proceeding`);
-        return;
+        throw new Error(`${name} pane died during readiness check`);
       }
 
       // Detect the bypass-permissions TUI confirmation dialog.
@@ -200,6 +260,7 @@ export class ClaudeBackend extends CliAgent {
         const ready = join(this.cwd, '.loreli', 'mcp-ready');
         if (existsSync(ready)) {
           log.info(`${name} MCP tools ready`);
+          this._mcpReady = true;
           try { await unlink(ready); } catch { /* already cleaned */ }
           return;
         }
@@ -211,6 +272,37 @@ export class ClaudeBackend extends CliAgent {
     log.warn(`${name} readiness timeout after ${this.readyTimeout}ms — proceeding anyway`);
   }
 
+  /**
+   * Wait for MCP readiness when `_navigate()` Phase 2 timed out.
+   *
+   * Polls for the `.loreli/mcp-ready` marker file that the MCP server
+   * writes after the handshake completes. Without this, prompts sent
+   * immediately after a readiness timeout are dropped because Claude
+   * Code is still in its MCP initialization state.
+   *
+   * @returns {Promise<void>}
+   */
+  async _awaitMcp() {
+    if (this._mcpReady) return;
+
+    const ready = join(this.cwd, '.loreli', 'mcp-ready');
+    const deadline = Date.now() + 30000;
+    const name = this.identity?.name ?? '?';
+
+    while (Date.now() < deadline) {
+      if (existsSync(ready)) {
+        log.info(`${name} MCP tools ready (late)`);
+        this._mcpReady = true;
+        try { await unlink(ready); } catch { /* already cleaned */ }
+        return;
+      }
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    log.warn(`${name} MCP readiness not confirmed — sending prompt anyway`);
+    this._mcpReady = true;
+  }
+
   /**
    * Send a prompt to Claude's interactive session.
    *
@@ -227,6 +319,8 @@ export class ClaudeBackend extends CliAgent {
     if (!this.paneId) throw new Error('Agent not spawned — call spawn() first');
     if (this.canTransition('working')) this.transition('working');
 
+    await this._awaitMcp();
+
     if (!message.includes('\n')) {
       await this.tmux.send(this.paneId, message);
       return;
@@ -248,7 +342,8 @@ export class ClaudeBackend extends CliAgent {
  * Build the claude CLI command string.
  *
  * Flags:
- * - `--dangerously-skip-permissions`: bypass all trust/permission dialogs
+ * - `--dangerously-skip-permissions`: bypass all trust/permission dialogs (action/reviewer)
+ * - `--permission-mode plan`: read-only plan mode (planner)
  * - `--mcp-config .mcp.json`: load scaffolded Loreli MCP config
  * - `--model`: resolved model identifier
  *
@@ -258,14 +353,19 @@ export class ClaudeBackend extends CliAgent {
  * @param {string} model - Resolved model identifier.
  * @param {string} [cwd] - Working directory (for --mcp-config path).
  * @param {string[]} [denied=[]] - Commands to block via --disallowedTools.
+ * @param {string} [mode] - Permission mode ('plan' for read-only).
  * @returns {string} CLI command string.
  */
-function buildCommand(model, cwd, denied = []) {
-  const parts = [
-    'claude',
-    '--dangerously-skip-permissions',
-    `--model ${model}`
-  ];
+function buildCommand(model, cwd, denied = [], mode) {
+  const parts = ['claude'];
+
+  if (mode === 'plan') {
+    parts.push('--permission-mode plan');
+  } else {
+    parts.push('--dangerously-skip-permissions');
+  }
+
+  parts.push(`--model ${model}`);
 
   // Defense-in-depth: --disallowedTools is a hard guardrail that cannot
   // be bypassed by the agent. The hooks file (.claude/settings.local.json)

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

@@ -38,6 +38,57 @@ const READY_TIMEOUT = 60000;
  * @extends CliAgent
  */
 export class CodexBackend extends CliAgent {
+  /**
+   * Regex patterns that identify known Codex CLI blocking dialogs.
+   * Matched against pane output by diagnose() for rapid-death
+   * remediation and stall monitor fallback.
+   *
+   * Each entry carries a `remedy` — an array of tmux key names that
+   * the orchestrator sends to dismiss the dialog. Patterns are
+   * checked in order; first match wins.
+   *
+   * @type {Array<{pattern: RegExp, category: string, reasoning: string, remedy?: string[]}>}
+   */
+  static patterns = [
+    {
+      pattern: /choose how you'd like.*to proceed/is,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI showing model upgrade selection — selecting "Use existing model"',
+      remedy: ['Down', 'Enter']
+    },
+    {
+      pattern: /invalid model name/i,
+      category: 'fatal',
+      reasoning: 'Codex CLI received invalid model name — API key may not support the requested model'
+    },
+    {
+      pattern: /update available!.*\n.*press enter to continue/is,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI showing update-available dialog requiring Enter to dismiss',
+      remedy: ['Enter']
+    },
+    {
+      pattern: /press enter to continue/i,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI waiting for Enter keypress to continue',
+      remedy: ['Enter']
+    }
+  ];
+
+  /**
+   * Detect known Codex 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 CodexBackend.patterns) {
+      if (pattern.test(output)) return { category, reasoning, ...(remedy && { remedy }) };
+    }
+    return null;
+  }
+
   /**
    * Return the scaffold descriptor for Codex workspaces.
    *
@@ -68,6 +119,24 @@ export class CodexBackend extends CliAgent {
       files: []
     };
   }
+  /**
+   * One-shot LLM call via `codex exec` (non-interactive mode).
+   *
+   * @param {string} prompt - Text prompt to send.
+   * @param {object} [opts] - Options.
+   * @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.
+   */
+  static async oneshot(prompt, { model, config, timeout, discovered } = {}) {
+    const resolved = resolve(model ?? 'fast', 'codex', 'openai', config, discovered);
+    const vars = env('codex', config) ?? {};
+    return CliAgent._exec('codex', [
+      'exec', '--ephemeral', '--skip-git-repo-check', prompt, '-m', resolved
+    ], vars, timeout);
+  }
+
   /**
    * @param {object} opts
    * @param {object} opts.identity - Agent identity.
@@ -79,13 +148,14 @@ export class CodexBackend extends CliAgent {
    * @param {number} [opts.readyTimeout=60000] - Max ms to wait for CLI readiness.
    */
   constructor(opts) {
-    const model = resolve(opts.model ?? 'balanced', 'codex', 'openai', opts.config);
+    const model = resolve(opts.model ?? 'balanced', 'codex', 'openai', opts.config, opts.discovered);
 
     const denied = opts.config?.get?.('agents.disallowedTools') ?? [];
+    const mode = opts.role === 'planner' ? 'plan' : undefined;
 
     super({
       ...opts,
-      command: buildCommand(model, opts.cwd, opts.context, denied)
+      command: buildCommand(model, opts.cwd, opts.context, denied, mode)
     });
 
     /** @type {string} Resolved model identifier. */
@@ -261,7 +331,8 @@ function rulesFlags(denied) {
  *   `--full-auto` maps to `-a on-request` which still allows the
  *   model to trigger interactive approval prompts, blocking the
  *   agent in tmux with no human to respond.
- * - `-s workspace-write`: sandbox to workspace write access only
+ * - `-s read-only`: read-only sandbox (planner)
+ * - `-s workspace-write`: sandbox to workspace write access (action/reviewer)
  * - `--no-alt-screen`: inline TUI mode for tmux capture compatibility
  * - `-C ${cwd}`: set the working directory for codex
  * - `-c mcp_servers.loreli.*`: inject loreli MCP server config
@@ -271,8 +342,10 @@ function rulesFlags(denied) {
  * @param {string} cwd - Working directory.
  * @param {object} [context] - Agent context for MCP env injection.
  * @param {string[]} [denied=[]] - Commands to block via prefix rules.
+ * @param {string} [mode] - Execution mode ('plan' for planner read-only mode).
  * @returns {string} CLI command string.
  */
-function buildCommand(model, cwd, context, denied = []) {
-  return `codex --model ${model} -a never -s workspace-write --no-alt-screen -C '${cwd}'${mcpFlags(context)}${rulesFlags(denied)}`;
+function buildCommand(model, cwd, context, denied = [], mode) {
+  const sandbox = mode === 'plan' ? 'read-only' : 'workspace-write';
+  return `codex --model ${model} -a never -s ${sandbox} --no-alt-screen -C '${cwd}'${mcpFlags(context)}${rulesFlags(denied)}`;
 }