loreli 0.0.0 → 2.0.0

package/packages/agent/src/factory.js

@@ -0,0 +1,124 @@
+import { prepare, pathFor, mirror, create as createWorktree } from 'loreli/workspace';
+import { vendor, pick } from 'loreli/identity';
+import { resolve as resolveModel } from './models.js';
+import { logger } from 'loreli/log';
+
+const log = logger('factory');
+
+/**
+ * Agent factory that centralizes the creation pipeline:
+ * discover → acquire identity → create cwd → select backend → instantiate.
+ *
+ * Both the orchestrator's `enlist()` and `rework()` paths were duplicating
+ * this sequence with subtle inconsistencies (e.g. rework used `defaultBackend()`
+ * instead of `forProvider()`). This class is the single source of truth.
+ *
+ * The factory **creates** agents but does not **spawn** them. Spawning
+ * and registration is the caller's responsibility (e.g. the orchestrator's
+ * `spawn()` method handles process start, map registration, and rollback).
+ *
+ * The factory composes the backend registry and identity registry — it does
+ * not own them. The orchestrator (or any other caller) injects them.
+ */
+export class Factory {
+  /**
+   * @param {object} opts
+   * @param {import('./backends/index.js').BackendRegistry} opts.backends - Backend registry.
+   * @param {import('loreli/identity').Registry} opts.identities - Identity registry.
+   * @param {object} [opts.config] - Config instance for model resolution.
+   */
+  constructor({ backends, identities, config }) {
+    /** @type {import('./backends/index.js').BackendRegistry} */
+    this.backends = backends;
+
+    /** @type {import('loreli/identity').Registry} */
+    this.identities = identities;
+
+    /** @type {object|undefined} */
+    this.config = config;
+  }
+
+  /**
+   * Create an agent for the given provider and role.
+   *
+   * Pipeline:
+   *  1. Discover available backends (idempotent)
+   *  2. Acquire a themed identity from the identity registry
+   *  3. Create the agent's working directory
+   *  4. Select the best backend via `forProvider()`
+   *  5. Instantiate the backend class
+   *
+   * The returned agent is in `idle` state — call `agent.spawn()` (or
+   * the orchestrator's `spawn()` for registration+rollback) to start it.
+   *
+   * @param {string} provider - AI provider ('anthropic', 'openai').
+   * @param {string} role - Agent role ('action', 'reviewer', 'planner').
+   * @param {object} [opts] - Additional options.
+   * @param {string} [opts.theme='transformers'] - Theme for identity.
+   * @param {string} [opts.model='balanced'] - Model alias or exact string.
+   * @param {object} [opts.config] - Config instance override (falls back to factory-level config).
+   * @param {string} [opts.cwd] - Override working directory (default: ~/.loreli/workspaces/loreli-{name}).
+   * @returns {Promise<object>} The unspawned agent instance (state: idle).
+   */
+  async create(provider, role, opts = {}) {
+    const theme = opts.theme ?? pick('transformers');
+    const model = opts.model ?? 'balanced';
+
+    await this.backends.discover();
+
+    const backendName = this.backends.forProvider(provider);
+
+    // Resolve the model alias to a concrete identifier so the identity
+    // carries the real model name for signatures and labels. Without
+    // this, identities created via Factory.create() (the enlist() path)
+    // would have an empty model while add_agent identities had the
+    // resolved name — causing "unknown" in reviewer stamps.
+    const config = opts.config ?? this.config;
+    const resolved = resolveModel(model, backendName, vendor(provider), config, this.backends.models);
+
+    const identity = this.identities.acquire(theme, provider, resolved, opts.taken);
+
+    try {
+      // Update context.agent before prepare() and backend construction
+      // so the Codex -c flags and .mcp.json env vars have the real name
+      // instead of null. Context is mutated in-place intentionally —
+      // callers (e.g. enlist) pass the same reference and read it back.
+      if (opts.context) {
+        opts.context.agent = identity.name;
+
+        if (!opts.context.denied) {
+          opts.context.denied = config?.get?.('agents.disallowedTools') ?? [];
+        }
+      }
+
+      let cwd = opts.cwd ?? pathFor(identity.name);
+
+      // Collect scaffold descriptors from all registered backends so
+      // workspace.prepare() and workspace.create() write configs, hooks,
+      // and files generically — no backend-specific knowledge needed.
+      const descriptors = this.backends.scaffoldAll(opts.context);
+
+      // When we have full orchestration context (repo + home), create a
+      // git worktree instead of an empty directory. This gives the agent
+      // a fully checked-out repo with zero network overhead per agent —
+      // all from a shared bare mirror.
+      if (opts.context?.repo && opts.context?.home && !opts.cwd) {
+        const url = `https://github.com/${opts.context.repo}.git`;
+        const bare = await mirror(url, { home: opts.context.home, token: opts.context.token });
+        cwd = await createWorktree(bare, 'HEAD', identity.name, undefined, opts.context, descriptors);
+        log.info(`worktree ready at ${cwd} from mirror of ${opts.context.repo}`);
+      } else {
+        await prepare(cwd, opts.context, descriptors);
+      }
+
+      const agentOpts = { identity, role, cwd, model, config };
+      if (opts.context) agentOpts.context = opts.context;
+
+      log.info(`created ${identity.name} (${role}) via ${backendName}`);
+      return this.backends.create(backendName, agentOpts);
+    } catch (err) {
+      this.identities.release(identity);
+      throw err;
+    }
+  }
+}

package/packages/agent/src/index.js

@@ -0,0 +1,12 @@
+export { Agent } from './base.js';
+export { CliAgent } from './cli.js';
+export { Session, STATES, TRANSITIONS } from './session.js';
+export { BackendRegistry } from './backends/index.js';
+export { Factory } from './factory.js';
+export { ClaudeBackend } from './backends/claude.js';
+export { CodexBackend } from './backends/codex.js';
+export { CursorBackend } from './backends/cursor.js';
+export * as models from './models.js';
+export * as output from './output.js';
+export * as trace from './trace.js';
+export { prepare } from 'loreli/workspace';

package/packages/agent/src/models.js

@@ -0,0 +1,159 @@
+import { defaults } from 'loreli/config';
+import { validate as validateModel } from './discover.js';
+import { logger } from 'loreli/log';
+
+const log = logger('models');
+
+/**
+ * Resolve a model alias to a concrete model identifier.
+ *
+ * Resolution order:
+ *  1. Config layer: `config.get('backends.{backend}.models.{alias}.{provider}')`
+ *  2. Discovery layer: runtime-discovered models classified into tiers
+ *  3. Built-in defaults: `defaults.backends[backend].models[alias][provider]`
+ *  4. Pass-through: return the alias string unchanged (exact model IDs)
+ *
+ * When discovery data is available, the resolved model is validated
+ * against the known model list. Invalid models trigger a warning and
+ * fall back to the backend's default discovered model.
+ *
+ * @param {string} alias - Alias ('fast', 'balanced', 'powerful') or exact model string.
+ * @param {string} backend - Backend name ('claude', 'codex', 'cursor').
+ * @param {string} provider - AI provider ('openai' | 'anthropic').
+ * @param {object} [config] - Config instance with a `get()` method.
+ * @param {Map} [discovered] - Discovery cache from BackendRegistry.
+ * @returns {string} Resolved model identifier.
+ */
+export function resolve(alias, backend, provider, config, discovered) {
+  const fromConfig = config?.get?.(`backends.${backend}.models.${alias}.${provider}`);
+  if (fromConfig) return fromConfig;
+
+  const fromDiscovery = discovered?.get(backend)?.tiers?.[alias]?.[provider];
+  if (fromDiscovery) return fromDiscovery;
+
+  const fallback = defaults.backends?.[backend]?.models?.[alias]?.[provider];
+  if (fallback) {
+    if (discovered && !validateModel(fallback, backend, discovered)) {
+      log.warn(`model "${fallback}" (${alias}/${backend}/${provider}) not found in discovered models — using backend default`);
+      const def = discovered.get(backend)?.models?.find(function isDefault(m) { return m.marker === 'default'; });
+      if (def) return def.id;
+    }
+    return fallback;
+  }
+
+  // Pass-through for exact model strings
+  return alias;
+}
+
+/**
+ * Env var prefixes relevant to each backend. Used to inherit
+ * process.env vars so launcher scripts in tmux get the right
+ * proxy URLs, auth tokens, and feature flags.
+ *
+ * @type {Record<string, string[]>}
+ */
+const PREFIXES = {
+  claude: ['ANTHROPIC_', 'CLAUDE_'],
+  codex: ['OPENAI_', 'CODEX_'],
+  cursor: ['ANTHROPIC_', 'OPENAI_', 'CLAUDE_', 'CURSOR_']
+};
+
+/**
+ * Collect process.env vars matching a backend's known prefixes.
+ *
+ * @param {string} backend - Backend name.
+ * @returns {object} Matching env vars from process.env.
+ */
+function inherit(backend) {
+  const prefixes = PREFIXES[backend] ?? [];
+  if (!prefixes.length) return {};
+
+  const result = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value && prefixes.some(function match(p) { return key.startsWith(p); })) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Retrieve backend-specific environment variables.
+ *
+ * Merges two layers:
+ *  1. Inherited: process.env vars matching the backend's known prefixes
+ *     (e.g. ANTHROPIC_BASE_URL, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS)
+ *  2. Config overrides: `backends.{backend}.env` from loreli.yml
+ *
+ * Config values take precedence over process.env when keys collide.
+ * Returns undefined when no vars are collected from either layer.
+ *
+ * @param {string} backend - Backend name ('claude', 'codex', 'cursor').
+ * @param {object} [config] - Config instance with a `get()` method.
+ * @returns {object|undefined} Merged environment variables, or undefined if empty.
+ */
+export function env(backend, config) {
+  const inherited = inherit(backend);
+
+  const configured = config?.get?.(`backends.${backend}.env`);
+  const overrides = (configured && typeof configured === 'object') ? configured : {};
+
+  // Config overrides process.env
+  const merged = { ...inherited, ...overrides };
+  if (!Object.keys(merged).length) return undefined;
+  return merged;
+}
+
+/**
+ * Format an env object into shell export lines for launcher scripts.
+ *
+ * Returns an empty string when no env is configured, keeping the
+ * launcher script clean. Values are single-quoted to prevent expansion.
+ *
+ * @param {object|undefined} vars - Key/value environment map.
+ * @returns {string} Shell export statements (with trailing newline), or empty string.
+ */
+export function format(vars) {
+  if (!vars || !Object.keys(vars).length) return '';
+  return Object.entries(vars)
+    .map(function line([k, v]) { return `export ${k}='${v}'`; })
+    .join('\n') + '\n';
+}
+
+/**
+ * Format an env object as a single-line shell export string.
+ *
+ * Designed for inline use with tmux commands — no newlines, exports
+ * joined with ` && `. Values are single-quoted to prevent expansion.
+ *
+ * @param {object|undefined} vars - Key/value environment map.
+ * @returns {string} Inline export string, or empty string when no vars.
+ */
+export function inline(vars) {
+  if (!vars || !Object.keys(vars).length) return '';
+  return Object.entries(vars)
+    .map(function line([k, v]) { return `export ${k}='${v}'`; })
+    .join(' && ');
+}
+
+/**
+ * List all known aliases for a given backend.
+ *
+ * When a config instance is provided, reads alias keys from config's
+ * backend models. Otherwise falls back to built-in defaults.
+ *
+ * @param {string} backend - Backend name ('claude', 'codex', 'cursor').
+ * @param {object} [config] - Config instance with a `get()` method.
+ * @returns {string[]} Array of alias names.
+ */
+export function list(backend, config) {
+  if (!backend) throw new Error('models.list() requires a backend name');
+
+  const models = config?.get?.(`backends.${backend}.models`);
+  if (models && typeof models === 'object') return Object.keys(models);
+
+  const fallback = defaults.backends?.[backend]?.models;
+  if (fallback) return Object.keys(fallback);
+
+  return [];
+}

package/packages/agent/src/output.js

@@ -0,0 +1,62 @@
+/**
+ * Agent output processing utilities.
+ *
+ * Handles cleaning, truncating, and formatting captured terminal output
+ * from CLI-backed agents. Used by the orchestrator's relay and any other
+ * consumer that reads agent pane output.
+ */
+
+/**
+ * Regex to strip ANSI escape codes from terminal output.
+ * Matches both CSI sequences (e.g. `\x1b[31m`) and OSC sequences
+ * (e.g. `\x1b]0;title\x07`).
+ *
+ * @type {RegExp}
+ */
+export const ANSI_RE = /\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07/g;
+
+/**
+ * Default maximum characters for truncated output.
+ *
+ * @type {number}
+ */
+export const MAX_CHARS = 12000;
+
+/**
+ * Strip ANSI escape codes from a string.
+ *
+ * @param {string} text - Raw terminal output.
+ * @returns {string} Clean text without ANSI codes.
+ */
+export function strip(text) {
+  return text.replace(ANSI_RE, '');
+}
+
+/**
+ * Truncate text to a maximum length, keeping the tail.
+ *
+ * When the input exceeds `max` characters, the beginning is removed
+ * and a `...(truncated)` prefix is prepended. This preserves the most
+ * recent output which is typically the most relevant.
+ *
+ * @param {string} text - Text to truncate.
+ * @param {number} [max=MAX_CHARS] - Maximum character count.
+ * @returns {string} Truncated text, or original if under the limit.
+ */
+export function truncate(text, max = MAX_CHARS) {
+  if (text.length <= max) return text;
+  return `...(truncated)\n${text.slice(-max)}`;
+}
+
+/**
+ * Clean agent output: strip ANSI codes, then truncate.
+ *
+ * Convenience function combining both operations in the standard order.
+ *
+ * @param {string} text - Raw terminal output.
+ * @param {number} [max=MAX_CHARS] - Maximum character count.
+ * @returns {string} Cleaned and truncated text.
+ */
+export function clean(text, max = MAX_CHARS) {
+  return truncate(strip(text), max);
+}

package/packages/agent/src/session.js

@@ -0,0 +1,162 @@
+/**
+ * Valid session states.
+ *
+ * @type {Set<string>}
+ */
+export const STATES = new Set([
+  'spawned', 'working', 'standby', 'reviewing', 'awaiting_hitl', 'dormant'
+]);
+
+/**
+ * Explicit state transition map.
+ *
+ * Each key is a current state, and the value is a Set of states
+ * it can transition to. Transitions not in this map are rejected.
+ *
+ * Uses an explicit graph instead of linear ordering because agent
+ * states have branching paths (e.g. working -> awaiting_hitl vs
+ * working -> dormant).
+ *
+ * @type {Record<string, Set<string>>}
+ */
+export const TRANSITIONS = {
+  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([])
+};
+
+/**
+ * Tracks an active agent's runtime state.
+ *
+ * Sessions are persisted to disk so agents survive orchestrator shutdown.
+ * State transitions are validated against the TRANSITIONS map to catch
+ * bugs where agents are reactivated without proper re-initialization.
+ */
+export class Session {
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity object.
+   * @param {string} opts.role - Agent role ('planner' | 'action' | 'reviewer').
+   * @param {string} opts.backend - Backend name ('claude', 'codex', etc.).
+   * @param {string} [opts.paneId] - Tmux pane ID.
+   * @param {number} [opts.pid] - Process ID.
+   * @param {string} [opts.repo] - Target repository (owner/name).
+   */
+  constructor({ identity, role, backend, paneId, pid, repo }) {
+    /** @type {object} Agent identity. */
+    this.identity = identity;
+
+    /** @type {string} Agent role. */
+    this.role = role;
+
+    /** @type {string} Backend name. */
+    this.backend = backend;
+
+    /** @type {string|null} Tmux pane ID. */
+    this.paneId = paneId ?? null;
+
+    /** @type {number|null} Process ID. */
+    this.pid = pid ?? null;
+
+    /** @type {string|null} Target repository. */
+    this.repo = repo ?? null;
+
+    /** @type {string} Current state. */
+    this.state = 'spawned';
+
+    /** @type {string} When the session started. */
+    this.startedAt = new Date().toISOString();
+
+    /** @type {string} Last activity timestamp. */
+    this.lastActivity = this.startedAt;
+
+    /** @type {number|null} Claimed issue number. */
+    this.claimedIssue = null;
+
+    /** @type {object|null} Dynamic task context from latest dispatch. */
+    this.task = null;
+
+    /** @type {string[]} Human reviewers assigned during HITL. */
+    this.reviewers = [];
+
+    /** @type {Array<{name: string, provider: string, timestamp: string}>} Agent approval records. */
+    this.agentApprovals = [];
+
+    /** @type {string|null} ISO timestamp when HITL was activated. */
+    this.hitlAt = null;
+
+    /**
+     * Token usage accumulator for the current task.
+     * Reset when a new task is assigned via dispatch.
+     *
+     * @type {{ input: number, output: number, model: string|null }}
+     */
+    this.usage = { input: 0, output: 0, model: null };
+  }
+
+  /**
+   * Transition to a new state with validation.
+   *
+   * Validates the transition against the TRANSITIONS map. Invalid
+   * transitions throw an error to catch bugs where agents are moved
+   * to impossible states (e.g. dormant -> working without re-spawn).
+   *
+   * @param {string} next - New state (spawned | working | standby | reviewing | awaiting_hitl | dormant).
+   * @throws {Error} If the transition is invalid.
+   */
+  transition(next) {
+    if (!STATES.has(next)) {
+      throw new Error(`Invalid state: "${next}". Valid: ${[...STATES].join(', ')}`);
+    }
+
+    const allowed = TRANSITIONS[this.state];
+    if (!allowed?.has(next)) {
+      throw new Error(
+        `Invalid transition: "${this.state}" -> "${next}". ` +
+        `Allowed from "${this.state}": ${allowed ? [...allowed].join(', ') || 'none (terminal)' : 'unknown'}`
+      );
+    }
+
+    this.state = next;
+    this.lastActivity = new Date().toISOString();
+  }
+
+  /**
+   * 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 TRANSITIONS[this.state]?.has(next) ?? false;
+  }
+
+  /**
+   * Serialize the session to a plain object for JSON storage.
+   *
+   * @returns {object} Plain object representation.
+   */
+  toJSON() {
+    return {
+      identity: this.identity,
+      role: this.role,
+      backend: this.backend,
+      paneId: this.paneId,
+      pid: this.pid,
+      repo: this.repo,
+      state: this.state,
+      startedAt: this.startedAt,
+      lastActivity: this.lastActivity,
+      claimedIssue: this.claimedIssue,
+      task: this.task,
+      reviewers: this.reviewers,
+      agentApprovals: this.agentApprovals,
+      hitlAt: this.hitlAt,
+      usage: this.usage
+    };
+  }
+
+}