loreli 0.0.0 → 2.0.0

package/packages/agent/src/cli.js

@@ -0,0 +1,275 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { Tmux } from 'loreli/tmux';
+import { Agent } from './base.js';
+import { inline } from './models.js';
+import { logger } from 'loreli/log';
+
+const log = logger('agent');
+
+/**
+ * CLI-backed agent that runs inside a tmux pane.
+ *
+ * Each agent gets its own window in the loreli tmux session.
+ * Commands are passed directly to tmux as shell strings —
+ * no launcher scripts on disk. Tmux handles working directory
+ * via its `-c` flag, and env vars are inlined as `export K='V' && ...`.
+ *
+ * Backends override `buildCommand()` (via constructor) for their
+ * specific CLI flags, and optionally override `spawn()` and
+ * `_navigate()` for custom readiness detection.
+ *
+ * Backends that need workspace scaffolding (config files, hooks,
+ * token propagation) override the static `scaffold()` method to
+ * return a declarative descriptor consumed by `workspace.prepare()`.
+ *
+ * @extends Agent
+ */
+export class CliAgent extends Agent {
+  /**
+   * Return a scaffold descriptor for this backend's workspace needs.
+   *
+   * Each CLI backend overrides this to declare the config files,
+   * hooks, and additional files it needs written into the agent's
+   * working directory. Workspace code writes them generically —
+   * no backend-specific knowledge required.
+   *
+   * @param {object} [context] - Agent context for env/token injection.
+   * @param {string} [context.session] - Session ID.
+   * @param {string} [context.agent] - Agent identity name.
+   * @param {string} [context.repo] - Target repository (owner/name).
+   * @param {string} [context.home] - Loreli home directory.
+   * @param {string} [context.token] - GitHub token.
+   * @param {string[]} [context.denied] - Commands to block.
+   * @returns {object|null} Scaffold descriptor or null if no scaffolding needed.
+   * @property {Array<{path: string, content: string, marker: string, format: string}>} configs - Config files.
+   * @property {Array<{path: string, key: string, entry: object, marker: string, defaults?: object}>} hooks - Hook entries to merge.
+   * @property {Array<{path: string, content: string, mode?: number}>} files - Additional files (e.g. .git/loreli.env).
+   */
+  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.
+   * @param {string} opts.role - Agent role.
+   * @param {string} opts.cwd - Working directory.
+   * @param {string} opts.command - CLI command to execute in the pane.
+   * @param {string} [opts.session='loreli'] - Tmux session name.
+   */
+  constructor(opts) {
+    super(opts);
+
+    /** @type {string} CLI command to execute. */
+    this.command = opts.command;
+
+    /** @type {string} Tmux session name. */
+    this.session = opts.session ?? 'loreli';
+
+    /** @type {Tmux} Tmux instance. */
+    this.tmux = new Tmux();
+
+    /** @type {string|null} Assigned tmux pane ID. */
+    this.paneId = null;
+  }
+
+  /**
+   * Spawn the agent in a tmux window.
+   *
+   * Builds an inline shell command with env exports and passes it
+   * directly to tmux — no launcher scripts written to disk.
+   *
+   *  1. If the session doesn't exist, create it with the command as the
+   *     initial window (no garbage default window — tmux auto-destroys
+   *     the session when all windows die)
+   *  2. If the session already exists, add a new window
+   *  3. Transition to `spawned` state
+   *
+   * Backends that need custom behavior (e.g. Claude dialog navigation,
+   * Codex readiness detection) override this method but follow the
+   * same pattern via {@link CliAgent#_launch}.
+   *
+   * @returns {Promise<void>}
+   */
+  async spawn() {
+    const cmd = this._shell(`exec ${this.command}`);
+    this.paneId = await this._launch(cmd);
+
+    log.info(`spawning ${this.identity?.name ?? '?'} in pane ${this.paneId}: ${this.command}`);
+    this.transition('spawned');
+  }
+
+  /**
+   * Build an inline shell command string with optional env exports.
+   *
+   * Joins `export K='V'` statements with ` && ` and appends the body.
+   * No files written to disk — the string is passed directly to tmux
+   * which runs it via `/bin/sh -c`.
+   *
+   * @param {string} body - Shell command to execute.
+   * @param {object} [vars] - Environment variables to export.
+   * @returns {string} Complete shell command string.
+   */
+  _shell(body, vars) {
+    const exports = inline(vars);
+    return exports ? `${exports} && ${body}` : body;
+  }
+
+  /**
+   * Launch a command in the tmux session.
+   *
+   * When the session does not exist, the command becomes the initial
+   * window — no empty default window is created. This lets tmux
+   * auto-destroy the session when all windows die, preventing orphans.
+   *
+   * 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)) {
+      paneId = await this.tmux.create(this.session, { cwd: this.cwd, command });
+    } else {
+      paneId = await this.tmux.window(this.session, { cwd: this.cwd, command });
+    }
+
+    await this.tmux.set(paneId, 'remain-on-exit', 'on');
+    return paneId;
+  }
+
+  /**
+   * Send a message to the agent's tmux pane.
+   *
+   * @param {string} message - Text to send via tmux send-keys.
+   * @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');
+    await this.tmux.send(this.paneId, message);
+  }
+
+  /**
+   * Capture the current output of the agent's tmux pane.
+   *
+   * @param {number} [lines] - Number of history lines to capture.
+   * @returns {Promise<string>} Captured terminal output.
+   */
+  async capture(lines) {
+    if (!this.paneId) throw new Error('Agent not spawned — call spawn() first');
+    return this.tmux.capture(this.paneId, lines);
+  }
+
+  /**
+   * Check if the agent's tmux pane is still alive.
+   *
+   * @returns {Promise<boolean>}
+   */
+  async alive() {
+    if (!this.paneId) return false;
+    return this.tmux.alive(this.paneId);
+  }
+
+  /**
+   * Kill the agent's tmux pane and reap the session if it is now empty.
+   *
+   * After removing the pane, checks whether the session still has any
+   * remaining panes. If not, the session is killed — this prevents
+   * orphaned sessions from accumulating when all agents have stopped.
+   *
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    log.info(`stopping ${this.identity?.name ?? '?'} pane=${this.paneId}`);
+    if (this.paneId) {
+      try {
+        await this.tmux.killPane(this.paneId);
+      } catch { /* pane may already be dead */ }
+      this.paneId = null;
+
+      // Reap the session when this was the last pane — prevents orphans
+      try {
+        const remaining = await this.tmux.panes(this.session);
+        if (remaining.length === 0) {
+          log.info(`session "${this.session}" is empty — reaping`);
+          await this.tmux.kill(this.session);
+        }
+      } catch { /* session may already be gone (tmux auto-destroyed it) */ }
+    }
+
+    if (this.state !== 'dormant') this.transition('dormant');
+  }
+}

package/packages/agent/src/discover.js

@@ -0,0 +1,396 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logger } from 'loreli/log';
+import { defaults } from 'loreli/config';
+
+const execFile = promisify(execFileCb);
+const log = logger('discover');
+
+const PROXY_BACKENDS = [
+  {
+    backend: 'claude',
+    baseKey: 'ANTHROPIC_BASE_URL',
+    keyOrder: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY']
+  },
+  {
+    backend: 'codex',
+    baseKey: 'OPENAI_BASE_URL',
+    keyOrder: ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']
+  }
+];
+
+/**
+ * Known tiers in priority order (lowest capability first).
+ * @type {string[]}
+ */
+const TIERS = ['fast', 'balanced', 'powerful'];
+
+/**
+ * Detect AI provider from a cursor-agent model ID.
+ *
+ * @param {string} id - Model identifier.
+ * @returns {'openai'|'anthropic'|null} Provider, or null for unsupported models.
+ */
+function provider(id) {
+  if (/^(gpt-|o[134]|codex-)/.test(id)) return 'openai';
+  if (/^(opus-|sonnet-|haiku-|claude-)/.test(id)) return 'anthropic';
+  return null;
+}
+
+/**
+ * Read an env value with config override precedence.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @param {string} backend - Backend name.
+ * @param {string} key - Env key name.
+ * @returns {string|undefined} Resolved env value.
+ */
+function envValue(config, backend, key) {
+  const fromConfig = config?.get?.(`backends.${backend}.env.${key}`);
+  if (typeof fromConfig === 'string' && fromConfig.length) return fromConfig;
+  const fromProcess = process.env[key];
+  if (typeof fromProcess === 'string' && fromProcess.length) return fromProcess;
+  return undefined;
+}
+
+/**
+ * Resolve timeout for proxy model discovery.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @returns {number} Timeout in milliseconds.
+ */
+function proxyTimeout(config) {
+  const configured = config?.get?.('timeouts.proxyDiscovery');
+  if (typeof configured === 'number' && configured > 0) return configured;
+  const fallback = defaults?.timeouts?.proxyDiscovery;
+  if (typeof fallback === 'number' && fallback > 0) return fallback;
+  return 5000;
+}
+
+/**
+ * Build endpoint candidates for proxy model discovery.
+ *
+ * Handles base URLs with and without `/v1` to avoid producing
+ * invalid `/v1/v1/models` paths.
+ *
+ * @param {string} baseUrl - Proxy base URL.
+ * @returns {string[]} Candidate absolute URLs in priority order.
+ */
+function endpointCandidates(baseUrl) {
+  const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+  const parsed = new URL(base);
+  const path = parsed.pathname.replace(/\/+$/, '');
+  const hasV1 = path.endsWith('/v1');
+  const candidates = [];
+
+  if (hasV1) {
+    candidates.push(new URL('models', base).toString());
+    candidates.push(new URL('../models', base).toString());
+  } else {
+    candidates.push(new URL('v1/models', base).toString());
+    candidates.push(new URL('models', base).toString());
+  }
+
+  return [...new Set(candidates)];
+}
+
+/**
+ * Normalize a base URL for cache keying.
+ *
+ * @param {string} baseUrl - Base URL.
+ * @returns {string} Normalized URL string.
+ */
+function normalizeBase(baseUrl) {
+  const parsed = new URL(baseUrl);
+  parsed.search = '';
+  parsed.hash = '';
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+  return parsed.toString();
+}
+
+/**
+ * Query one proxy endpoint candidate for model listing.
+ *
+ * @param {string} endpoint - Candidate endpoint URL.
+ * @param {string|undefined} apiKey - Optional bearer token.
+ * @param {number} timeout - Request timeout in milliseconds.
+ * @returns {Promise<null|object[]>} Raw model objects.
+ */
+async function requestModels(endpoint, apiKey, timeout) {
+  const headers = {};
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+
+  const response = await fetch(endpoint, {
+    headers,
+    signal: AbortSignal.timeout(timeout)
+  });
+
+  if (!response.ok) return null;
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
+
+  return Array.isArray(body?.data) ? body.data : null;
+}
+
+/**
+ * Convert proxy `/models` payload into internal discovery shape.
+ *
+ * Keeps all model IDs for `validate()`; provider-aware tier mapping
+ * is derived from recognizable IDs only.
+ *
+ * @param {object[]} entries - Raw model entries.
+ * @returns {{models: object[], tiers: object}|null} Discovery result.
+ */
+function toDiscovery(entries) {
+  const models = [];
+
+  for (const entry of entries) {
+    if (!entry?.id) continue;
+    const id = String(entry.id);
+    models.push({
+      id,
+      name: id,
+      provider: provider(id),
+      tier: tier(id),
+      marker: null
+    });
+  }
+
+  if (!models.length) return null;
+  return { models, tiers: tiers(models) };
+}
+
+/**
+ * Discover proxy models using endpoint candidates and optional auth.
+ *
+ * @param {string} baseUrl - Proxy base URL.
+ * @param {string|undefined} apiKey - Optional bearer token.
+ * @param {number} timeout - Request timeout in milliseconds.
+ * @returns {Promise<{models: object[], tiers: object}|null>} Discovery result.
+ */
+async function discoverProxy(baseUrl, apiKey, timeout) {
+  for (const endpoint of endpointCandidates(baseUrl)) {
+    const data = await requestModels(endpoint, apiKey, timeout);
+    if (!data) continue;
+    const discovery = toDiscovery(data);
+    if (discovery) return discovery;
+  }
+  return null;
+}
+
+/**
+ * Return unique auth key candidates in order.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @param {string} backend - Backend name.
+ * @param {string[]} order - Env key names in priority order.
+ * @returns {(string|undefined)[]} Ordered key candidates.
+ */
+function authKeys(config, backend, order) {
+  const keys = [];
+  for (const keyName of order) {
+    const value = envValue(config, backend, keyName);
+    if (value && !keys.includes(value)) keys.push(value);
+  }
+  if (!keys.length) keys.push(undefined);
+  return keys;
+}
+
+/**
+ * Patterns that force a model into a specific tier.
+ * Checked in order — first match wins.
+ * @type {Array<{pattern: RegExp, tier: string}>}
+ */
+const TIER_RULES = [
+  { pattern: /-(low|mini)\b/, tier: 'fast' },
+  { pattern: /(^|-)haiku-/, tier: 'fast' },
+  { pattern: /\bflash\b/, tier: 'fast' },
+  { pattern: /-(xhigh|max)\b/, tier: 'powerful' },
+  { pattern: /(^|-)opus-/, tier: 'powerful' },
+  { pattern: /^o3\b/, tier: 'powerful' },
+  { pattern: /-high\b/, tier: 'powerful' }
+];
+
+/**
+ * Classify a model ID into a capability tier.
+ *
+ * @param {string} id - Model identifier.
+ * @returns {string} Tier name ('fast', 'balanced', or 'powerful').
+ */
+function tier(id) {
+  for (const rule of TIER_RULES) {
+    if (rule.pattern.test(id)) return rule.tier;
+  }
+  return 'balanced';
+}
+
+/**
+ * Parse the structured output of `cursor-agent --list-models`.
+ *
+ * Each line is `id - Human Name` with optional `(default)` or `(current)` markers.
+ * Only models from supported providers (openai, anthropic) are returned.
+ *
+ * @param {string} output - Raw stdout from `cursor-agent --list-models`.
+ * @returns {Array<{id: string, name: string, provider: string, tier: string, marker: string|null}>}
+ */
+export function parseCursor(output) {
+  const models = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(/^(\S+)\s+-\s+(.+?)(?:\s+\((default|current)\))?\s*$/);
+    if (!match) continue;
+
+    const [, id, name, marker] = match;
+    const p = provider(id);
+    if (!p) continue;
+
+    models.push({
+      id,
+      name: name.trim(),
+      provider: p,
+      tier: tier(id),
+      marker: marker ?? null
+    });
+  }
+  return models;
+}
+
+/**
+ * Build a tier map from a flat list of discovered models.
+ *
+ * Groups models by provider, then for each tier picks the best candidate:
+ * models marked as `default` or `current` are preferred, then the
+ * lexicographically last ID (usually the latest generation).
+ *
+ * @param {Array<{id: string, provider: string, tier: string, marker: string|null}>} models
+ * @returns {Record<string, Record<string, string>>} `{ fast: { openai: 'gpt-...', anthropic: '...' }, ... }`
+ */
+export function tiers(models) {
+  const grouped = {};
+  for (const m of models) {
+    const key = `${m.provider}:${m.tier}`;
+    if (!grouped[key]) grouped[key] = [];
+    grouped[key].push(m);
+  }
+
+  const result = {};
+  for (const t of TIERS) {
+    for (const prov of ['openai', 'anthropic']) {
+      const candidates = grouped[`${prov}:${t}`];
+      if (!candidates?.length) continue;
+
+      const best = candidates.find(function marked(m) { return m.marker; })
+        ?? candidates.sort(function latest(a, b) { return b.id.localeCompare(a.id); })[0];
+
+      if (!result[t]) result[t] = {};
+      result[t][prov] = best.id;
+    }
+  }
+  return result;
+}
+
+/**
+ * Discover available models from cursor-agent CLI.
+ *
+ * @returns {Promise<{models: object[], tiers: object}|null>} Discovery result, or null on failure.
+ */
+export async function discoverCursor() {
+  try {
+    const { stdout } = await execFile('cursor-agent', ['--list-models'], {
+      timeout: 10000,
+      maxBuffer: 64 * 1024
+    });
+
+    const models = parseCursor(stdout);
+    if (!models.length) {
+      log.warn('cursor-agent --list-models returned no supported models');
+      return null;
+    }
+
+    log.info(`cursor: discovered ${models.length} models`);
+    return { models, tiers: tiers(models) };
+  } catch (err) {
+    log.warn(`cursor model discovery failed: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Run model discovery for all available backends.
+ *
+ * Discovery sources:
+ * - `cursor`: `cursor-agent --list-models`
+ * - `claude` / `codex`: proxy model listing when corresponding
+ *   base URLs are configured (ANTHROPIC_BASE_URL / OPENAI_BASE_URL)
+ *
+ * Results are cached on the registry for use during model resolution.
+ *
+ * @param {import('./backends/index.js').BackendRegistry} registry - Backend registry with discovered binaries.
+ * @param {object} [opts] - Discovery options.
+ * @param {object} [opts.config] - Config instance with `get()`.
+ * @returns {Promise<Map<string, {models: object[], tiers: object}>>} Per-backend discovery results.
+ */
+export async function discover(registry, opts = {}) {
+  const { config } = opts;
+  const cache = new Map();
+  const successfulProxy = new Map();
+  const timeout = proxyTimeout(config);
+
+  if (registry.discovered.has('cursor')) {
+    const result = await discoverCursor();
+    if (result) cache.set('cursor', result);
+  }
+
+  for (const def of PROXY_BACKENDS) {
+    const { backend, baseKey, keyOrder } = def;
+    if (!registry.discovered.has(backend)) continue;
+
+    const baseUrl = envValue(config, backend, baseKey);
+    if (!baseUrl) continue;
+
+    const normalized = normalizeBase(baseUrl);
+    const cached = successfulProxy.get(normalized);
+    if (cached) {
+      cache.set(backend, cached);
+      continue;
+    }
+
+    const keys = authKeys(config, backend, keyOrder);
+    let found = null;
+
+    for (const key of keys) {
+      try {
+        found = await discoverProxy(baseUrl, key, timeout);
+      } catch (err) {
+        log.warn(`${backend} proxy discovery failed: ${err.message}`);
+      }
+      if (found) break;
+    }
+
+    if (found) {
+      cache.set(backend, found);
+      successfulProxy.set(normalized, found);
+      log.info(`${backend}: discovered ${found.models.length} models via ${baseKey}`);
+    }
+  }
+
+  return cache;
+}
+
+/**
+ * Check if a resolved model ID exists in the discovered model list.
+ *
+ * @param {string} model - Resolved model identifier.
+ * @param {string} backend - Backend name.
+ * @param {Map<string, {models: object[]}>} discovered - Discovery cache.
+ * @returns {boolean} True if the model is known or discovery is unavailable.
+ */
+export function validate(model, backend, discovered) {
+  const entry = discovered?.get(backend);
+  if (!entry?.models?.length) return true;
+  return entry.models.some(function known(m) { return m.id === model; });
+}