loreli 0.0.0 → 1.0.0

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 });
+  }
+}

package/packages/agent/src/cli.js

@@ -0,0 +1,198 @@
+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;
+  }
+  /**
+   * @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);
+    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');
+  }
+
+  /**
+   * 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.
+   *
+   * @param {string} command - Shell command string.
+   * @returns {Promise<string>} The assigned pane ID.
+   */
+  async _launch(command) {
+    if (!await this.tmux.has(this.session)) {
+      return this.tmux.create(this.session, { cwd: this.cwd, command });
+    }
+    return this.tmux.window(this.session, { cwd: this.cwd, command });
+  }
+
+  /**
+   * 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/factory.js

@@ -0,0 +1,119 @@
+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);
+
+    const identity = this.identities.acquire(theme, provider, resolved, opts.taken);
+
+    // 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);
+  }
+}

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,141 @@
+import { defaults } from 'loreli/config';
+
+/**
+ * Resolve a model alias to a concrete model identifier.
+ *
+ * Resolution order:
+ *  1. Config layer: `config.get('backends.{backend}.models.{alias}.{provider}')`
+ *  2. Built-in defaults: `defaults.backends[backend].models[alias][provider]`
+ *  3. Pass-through: return the alias string unchanged (exact model IDs)
+ *
+ * @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.
+ * @returns {string} Resolved model identifier.
+ */
+export function resolve(alias, backend, provider, config) {
+  // Config layer: highest priority
+  const fromConfig = config?.get?.(`backends.${backend}.models.${alias}.${provider}`);
+  if (fromConfig) return fromConfig;
+
+  // Built-in defaults layer
+  const fallback = defaults.backends?.[backend]?.models?.[alias]?.[provider];
+  if (fallback) 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);
+}