loreli 0.0.0 → 2.0.0

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

@@ -0,0 +1,486 @@
+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.
+ *
+ * @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();
+
+    /**
+     * 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).
+     *
+     * @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;
+  }
+
+  /**
+   * 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,
+   * 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(config) {
+    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 });
+      }
+    }
+
+    this.models = await discoverModels(this, { config });
+    this._discoveredOnce = true;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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.
+   *
+   * @param {string} name - Backend name.
+   */
+  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);
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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.
+   *
+   * @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, discovered: this.models });
+    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;
+  }
+}

package/packages/agent/src/base.js

@@ -0,0 +1,138 @@
+import { EventEmitter } from 'node:events';
+import { logger } from 'loreli/log';
+
+const log = logger('agent');
+
+/**
+ * Valid agent states and their allowed transitions.
+ *
+ * Agent states parallel Session states but include `idle` as the
+ * pre-spawn state. The graph prevents impossible transitions like
+ * `dormant -> working`.
+ *
+ * @type {Record<string, Set<string>>}
+ */
+const AGENT_TRANSITIONS = {
+  idle: new Set(['spawned', 'dormant']),
+  spawned: new Set(['working', 'standby', 'dormant']),
+  working: new Set(['standby', 'reviewing', 'awaiting_hitl', 'dormant']),
+  standby: new Set(['working', 'reviewing', 'awaiting_hitl', 'dormant']),
+  reviewing: new Set(['working', 'standby', 'awaiting_hitl', 'dormant']),
+  awaiting_hitl: new Set(['working', 'standby', 'dormant']),
+  dormant: new Set(['spawned'])
+};
+
+/**
+ * Abstract base class for all agent backends.
+ *
+ * Transport-agnostic: a tmux-backed agent maintains a persistent pane,
+ * a future SDK-backed agent holds an open API session. Both satisfy
+ * the same interface.
+ *
+ * @extends EventEmitter
+ */
+export class Agent extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity (from loreli/identity).
+   * @param {string} opts.role - Agent role ('planner' | 'action' | 'reviewer').
+   * @param {string} opts.cwd - Working directory for the agent.
+   */
+  constructor({ identity, role, cwd }) {
+    super();
+
+    /** @type {object} Agent identity. */
+    this.identity = identity;
+
+    /** @type {string} Agent role. */
+    this.role = role;
+
+    /** @type {string} Working directory. */
+    this.cwd = cwd;
+
+    /** @type {string} Current agent state. */
+    this._state = 'idle';
+  }
+
+  /**
+   * Current agent state.
+   *
+   * @type {string} idle | spawned | working | standby | reviewing | dormant
+   */
+  get state() {
+    return this._state;
+  }
+
+  /**
+   * Start the agent process.
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} Must be overridden by subclass.
+   */
+  async spawn() {
+    throw new Error('spawn: not implemented — subclass must override');
+  }
+
+  /**
+   * Deliver work/instructions to the running agent.
+   *
+   * @param {string} _message - The message to send.
+   * @returns {Promise<void>}
+   * @throws {Error} Must be overridden by subclass.
+   */
+  async send(_message) {
+    throw new Error('send: not implemented — subclass must override');
+  }
+
+  /**
+   * Graceful shutdown of the agent.
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} Must be overridden by subclass.
+   */
+  async stop() {
+    throw new Error('stop: not implemented — subclass must override');
+  }
+
+  /**
+   * Read latest output from the agent.
+   *
+   * @returns {Promise<string>}
+   * @throws {Error} Must be overridden by subclass.
+   */
+  async capture() {
+    throw new Error('capture: not implemented — subclass must override');
+  }
+
+  /**
+   * Check whether a transition to the given state is valid.
+   *
+   * @param {string} next - Target state to check.
+   * @returns {boolean} True if the transition is allowed.
+   */
+  canTransition(next) {
+    return AGENT_TRANSITIONS[this._state]?.has(next) ?? false;
+  }
+
+  /**
+   * Transition to a new state, emitting a 'state' event.
+   * Validates the transition against AGENT_TRANSITIONS to prevent
+   * impossible state changes.
+   *
+   * @param {string} next - The new state.
+   * @throws {Error} If the transition is invalid.
+   */
+  transition(next) {
+    const prev = this._state;
+
+    const allowed = AGENT_TRANSITIONS[prev];
+    if (!allowed?.has(next)) {
+      const valid = allowed ? [...allowed].join(', ') || 'none (terminal)' : 'unknown';
+      throw new Error(`Invalid agent transition: "${prev}" -> "${next}". Allowed: ${valid}`);
+    }
+
+    this._state = next;
+    log.debug(`${this.identity?.name ?? '?'}: ${prev} -> ${next}`);
+    this.emit('state', { prev, next, identity: this.identity });
+  }
+}