loreli 0.0.0 → 1.0.0

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

@@ -0,0 +1,287 @@
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CliAgent } from '../cli.js';
+import { resolve, env } from '../models.js';
+import { mcpJson } from 'loreli/workspace';
+import { logger } from 'loreli/log';
+
+const log = logger('claude');
+
+/**
+ * Interval for polling pane content during readiness detection.
+ * @type {number}
+ */
+const READY_POLL = 1000;
+
+/**
+ * Maximum time to wait for the Claude CLI to become ready.
+ * @type {number}
+ */
+const READY_TIMEOUT = 60000;
+
+/**
+ * Claude Code CLI backend. Interactive: stays running in a tmux pane.
+ *
+ * Uses `--dangerously-skip-permissions` to bypass ALL startup dialogs
+ * (workspace trust, permission bypass, "continue anyway"). This flag
+ * eliminates the need for fragile interactive dialog navigation.
+ *
+ * Uses `--mcp-config` to load the scaffolded `.mcp.json` that points
+ * back to the Loreli MCP server. The agent discovers Loreli tools
+ * automatically on startup.
+ *
+ * After the CLI is ready (welcome banner visible), prompts are
+ * delivered via file-based send (multi-line) or tmux send-keys
+ * (single-line).
+ *
+ * @extends CliAgent
+ */
+export class ClaudeBackend extends CliAgent {
+  /**
+   * Return the scaffold descriptor for Claude Code workspaces.
+   *
+   * Claude uses `${GITHUB_TOKEN}` interpolation in `.mcp.json` —
+   * Claude Code resolves this from its parent process environment.
+   * Hooks use PreToolUse to delegate to deny.sh and protect.sh.
+   *
+   * @param {object} [context] - Agent context for env/token injection.
+   * @returns {object} Scaffold descriptor.
+   */
+  static scaffold(context) {
+    const denied = context?.denied ?? [];
+
+    return {
+      configs: [
+        {
+          path: '.mcp.json',
+          content: mcpJson(context, context ? { tokenRef: '${GITHUB_TOKEN}' } : {}),
+          marker: 'loreli',
+          format: 'json'
+        }
+      ],
+      hooks: [
+        {
+          path: '.claude/settings.local.json',
+          key: 'PreToolUse',
+          entry: {
+            matcher: 'Bash',
+            hooks: [{ type: 'command', command: 'bash "$CLAUDE_PROJECT_DIR/.loreli/deny.sh"' }]
+          },
+          marker: 'deny.sh'
+        },
+        {
+          path: '.claude/settings.local.json',
+          key: 'PreToolUse',
+          entry: {
+            matcher: 'Write|Edit|MultiEdit',
+            hooks: [{ type: 'command', command: 'bash "$CLAUDE_PROJECT_DIR/.loreli/protect.sh"' }]
+          },
+          marker: 'protect.sh'
+        }
+      ],
+      files: []
+    };
+  }
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity.
+   * @param {string} opts.role - Agent role.
+   * @param {string} opts.cwd - Working directory.
+   * @param {string} [opts.model='balanced'] - Model alias or exact string.
+   * @param {object} [opts.config] - Config instance for model resolution.
+   * @param {string} [opts.session='loreli'] - Tmux session name.
+   * @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 denied = opts.config?.get?.('agents.disallowedTools') ?? [];
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd, denied)
+    });
+
+    /** @type {string} Resolved model identifier. */
+    this.model = model;
+
+    /** @type {object|undefined} Backend-specific environment variables. */
+    this._env = env('claude', opts.config) ?? {};
+
+    if (opts.context?.token) this._env.GITHUB_TOKEN = opts.context.token;
+
+    /** @type {number} Max ms to wait for CLI readiness. */
+    this.readyTimeout = opts.readyTimeout ?? READY_TIMEOUT;
+  }
+
+  /**
+   * Spawn the Claude CLI and wait for readiness.
+   *
+   * Builds an inline shell command with env exports and passes it
+   * directly to tmux — no launcher scripts on disk. The user's
+   * `.zshrc` is bypassed because tmux runs the command via `/bin/sh`.
+   *
+   * All trust and permission dialogs are skipped by
+   * `--dangerously-skip-permissions` in the command — no interactive
+   * navigation is needed.
+   *
+   * @returns {Promise<void>}
+   */
+  async spawn() {
+    const cmd = this._shell(`exec ${this.command}`, this._env);
+    this.paneId = await this._launch(cmd);
+
+    log.info(`spawning ${this.identity?.name ?? '?'} in pane ${this.paneId}: ${this.command}`);
+    this.transition('spawned');
+
+    await this._navigate();
+  }
+
+  /**
+   * Wait for Claude CLI to finish initializing, including MCP tool discovery.
+   *
+   * Two-phase readiness check:
+   * 1. Navigate the bypass-permissions dialog and wait for the welcome banner
+   * 2. Wait for the MCP server to write a `.loreli-mcp-ready` marker file
+   *
+   * Phase 2 prevents a race condition where the prompt is sent before
+   * Claude Code finishes its MCP handshake, causing the agent to work
+   * without access to MCP tools.
+   *
+   * @returns {Promise<void>}
+   */
+  async _navigate() {
+    if (this.readyTimeout <= 0) return;
+
+    const deadline = Date.now() + this.readyTimeout;
+    const name = this.identity?.name ?? '?';
+    let accepted = false;
+    let banner = false;
+
+    while (Date.now() < deadline) {
+      // Guard against pane death — if Claude Code crashes during
+      // startup, the pane disappears and capture throws. Fall through
+      // to the timeout warning rather than crashing the spawn pipeline.
+      let output;
+      try {
+        output = await this.tmux.capture(this.paneId);
+      } catch {
+        log.warn(`${name} pane died during readiness check — proceeding`);
+        return;
+      }
+
+      // Detect the bypass-permissions TUI confirmation dialog.
+      // The cursor defaults to "No, exit" — we need Down then Enter
+      // to select "Yes, I accept".
+      if (!accepted && output.includes('Yes, I accept')) {
+        log.info(`${name} accepting bypass-permissions dialog`);
+        await this.tmux.keys(this.paneId, 'Down');
+        await new Promise(function pause(r) { setTimeout(r, 300); });
+        await this.tmux.keys(this.paneId, 'Enter');
+        accepted = true;
+        await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+        continue;
+      }
+
+      // Phase 1: Welcome banner signals Claude CLI is initialized
+      if (!banner && output.includes('Claude Code')) {
+        if (accepted || !output.includes('Bypass Permissions')) {
+          log.info(`${name} ready — Claude Code welcome banner detected`);
+          banner = true;
+          // Fall through to Phase 2 — don't return yet
+        }
+      }
+
+      // Phase 2: Wait for MCP tools to be discoverable. The loreli MCP
+      // server writes this file in its oninitialized callback, which fires
+      // after the client (Claude Code) completes the MCP handshake.
+      if (banner) {
+        const ready = join(this.cwd, '.loreli', 'mcp-ready');
+        if (existsSync(ready)) {
+          log.info(`${name} MCP tools ready`);
+          try { await unlink(ready); } catch { /* already cleaned */ }
+          return;
+        }
+      }
+
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    log.warn(`${name} readiness timeout after ${this.readyTimeout}ms — proceeding anyway`);
+  }
+
+  /**
+   * Send a prompt to Claude's interactive session.
+   *
+   * Multi-line prompts are written to a Markdown file and a single-line
+   * reference is sent via tmux send-keys. This avoids newline bytes
+   * being interpreted as Enter and fragmenting the prompt.
+   *
+   * Single-line messages are sent directly via send-keys.
+   *
+   * @param {string} message - The prompt text.
+   * @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');
+
+    if (!message.includes('\n')) {
+      await this.tmux.send(this.paneId, message);
+      return;
+    }
+
+    const dir = join(this.cwd, '.loreli');
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, `task-${Date.now()}.md`);
+    await writeFile(file, message, 'utf8');
+    log.info(`${this.identity?.name ?? '?'} prompt written to ${file}`);
+
+    await this.tmux.send(this.paneId,
+      `Read the complete task instructions from ${file} and execute them. Follow every instruction precisely.`
+    );
+  }
+}
+
+/**
+ * Build the claude CLI command string.
+ *
+ * Flags:
+ * - `--dangerously-skip-permissions`: bypass all trust/permission dialogs
+ * - `--mcp-config .mcp.json`: load scaffolded Loreli MCP config
+ * - `--model`: resolved model identifier
+ *
+ * No `--prompt` flag — prompts are delivered via `send()` after spawn
+ * to avoid shell injection risks from unescaped special characters.
+ *
+ * @param {string} model - Resolved model identifier.
+ * @param {string} [cwd] - Working directory (for --mcp-config path).
+ * @param {string[]} [denied=[]] - Commands to block via --disallowedTools.
+ * @returns {string} CLI command string.
+ */
+function buildCommand(model, cwd, denied = []) {
+  const parts = [
+    'claude',
+    '--dangerously-skip-permissions',
+    `--model ${model}`
+  ];
+
+  // Defense-in-depth: --disallowedTools is a hard guardrail that cannot
+  // be bypassed by the agent. The hooks file (.claude/settings.local.json)
+  // provides richer feedback, but this flag is the safety net.
+  if (denied.length) {
+    const globs = denied.map(function toGlob(cmd) {
+      return `"Bash(${cmd}:*)"`;
+    });
+    parts.push(`--disallowedTools ${globs.join(' ')}`);
+  }
+
+  // Only add --mcp-config when the scaffolded file exists. A missing
+  // file causes Claude CLI to hang indefinitely with zero output,
+  // blocking _navigate() for the full READY_TIMEOUT.
+  const mcpPath = cwd ? join(cwd, '.mcp.json') : null;
+  if (mcpPath && existsSync(mcpPath)) parts.push(`--mcp-config ${mcpPath}`);
+
+  return parts.join(' ');
+}

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

@@ -0,0 +1,278 @@
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CliAgent } from '../cli.js';
+import { resolve, env } from '../models.js';
+import { codexToml, mcpJson } from 'loreli/workspace';
+import { logger } from 'loreli/log';
+
+const log = logger('codex');
+
+/**
+ * Interval for polling pane content during readiness detection.
+ * @type {number}
+ */
+const READY_POLL = 1000;
+
+/**
+ * Maximum time to wait for the Codex CLI to become ready.
+ * @type {number}
+ */
+const READY_TIMEOUT = 60000;
+
+/**
+ * OpenAI Codex CLI backend. Interactive: stays running in a tmux pane.
+ *
+ * Uses `-a never -s workspace-write` for sandboxed unattended execution and
+ * `--no-alt-screen` so tmux can capture pane output (the TUI's
+ * alternate screen buffer is invisible to `capture-pane`).
+ *
+ * MCP servers are injected via `-c` flags at CLI level because
+ * Codex only reads `~/.codex/config.toml` (global), not the local
+ * `.codex/config.toml` in the working directory.
+ *
+ * After the CLI is ready (welcome banner visible), prompts are
+ * delivered via file-based send (multi-line) or tmux send-keys
+ * (single-line).
+ *
+ * @extends CliAgent
+ */
+export class CodexBackend extends CliAgent {
+  /**
+   * Return the scaffold descriptor for Codex workspaces.
+   *
+   * Codex uses TOML config with `env_vars` forwarding for
+   * GITHUB_TOKEN — whitelists the parent process env var for
+   * forwarding to MCP subprocesses.
+   *
+   * @param {object} [context] - Agent context for env/token injection.
+   * @returns {object} Scaffold descriptor.
+   */
+  static scaffold(context) {
+    return {
+      configs: [
+        {
+          path: '.mcp.json',
+          content: mcpJson(context, context ? { tokenRef: '${GITHUB_TOKEN}' } : {}),
+          marker: 'loreli',
+          format: 'json'
+        },
+        {
+          path: '.codex/config.toml',
+          content: codexToml(context),
+          marker: 'mcp_servers.loreli',
+          format: 'toml'
+        }
+      ],
+      hooks: [],
+      files: []
+    };
+  }
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity.
+   * @param {string} opts.role - Agent role.
+   * @param {string} opts.cwd - Working directory.
+   * @param {string} [opts.model='balanced'] - Model alias or exact string.
+   * @param {object} [opts.config] - Config instance for model resolution.
+   * @param {string} [opts.session='loreli'] - Tmux session name.
+   * @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 denied = opts.config?.get?.('agents.disallowedTools') ?? [];
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd, opts.context, denied)
+    });
+
+    /** @type {string} Resolved model identifier. */
+    this.model = model;
+
+    /** @type {object|undefined} Backend-specific environment variables. */
+    this._env = env('codex', opts.config) ?? {};
+
+    if (opts.context?.token) this._env.GITHUB_TOKEN = opts.context.token;
+
+    /** @type {number} Max ms to wait for CLI readiness. */
+    this.readyTimeout = opts.readyTimeout ?? READY_TIMEOUT;
+  }
+
+  /**
+   * Spawn the Codex CLI and wait for readiness.
+   *
+   * Builds an inline shell command with env exports and passes it
+   * directly to tmux — no launcher scripts on disk.
+   *
+   * @returns {Promise<void>}
+   */
+  async spawn() {
+    const cmd = this._shell(`exec ${this.command}`, this._env);
+    this.paneId = await this._launch(cmd);
+
+    log.info(`spawning ${this.identity?.name ?? '?'} in pane ${this.paneId}: ${this.command}`);
+    this.transition('spawned');
+
+    await this._navigate();
+  }
+
+  /**
+   * Wait for Codex CLI to finish initializing, including MCP tool discovery.
+   *
+   * Two-phase readiness check:
+   * 1. Wait for the welcome banner (`OpenAI Codex`) in pane output
+   * 2. Wait for the MCP server to write a `.loreli/mcp-ready` marker file
+   *
+   * Phase 2 prevents a race condition where the prompt is sent before
+   * Codex finishes its MCP handshake, causing the agent to work
+   * without access to MCP tools.
+   *
+   * @returns {Promise<void>}
+   */
+  async _navigate() {
+    if (this.readyTimeout <= 0) return;
+
+    const deadline = Date.now() + this.readyTimeout;
+    const name = this.identity?.name ?? '?';
+    let banner = false;
+
+    while (Date.now() < deadline) {
+      let output;
+      try {
+        output = await this.tmux.capture(this.paneId);
+      } catch {
+        log.warn(`${name} pane died during readiness check — proceeding`);
+        return;
+      }
+
+      if (!banner && output.includes('OpenAI Codex')) {
+        log.info(`${name} ready — OpenAI Codex welcome banner detected`);
+        banner = true;
+      }
+
+      if (banner) {
+        const ready = join(this.cwd, '.loreli', 'mcp-ready');
+        if (existsSync(ready)) {
+          log.info(`${name} MCP tools ready`);
+          try { await unlink(ready); } catch { /* already cleaned */ }
+          return;
+        }
+      }
+
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    log.warn(`${name} readiness timeout after ${this.readyTimeout}ms — proceeding anyway`);
+  }
+
+  /**
+   * Send a prompt to Codex's interactive session.
+   *
+   * Multi-line prompts are written to a Markdown file and a single-line
+   * reference is sent via tmux send-keys. This avoids newline bytes
+   * being interpreted as Enter and fragmenting the prompt.
+   *
+   * Single-line messages are sent directly via send-keys.
+   *
+   * @param {string} message - The prompt text.
+   * @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');
+
+    if (!message.includes('\n')) {
+      await this.tmux.send(this.paneId, message);
+      return;
+    }
+
+    const dir = join(this.cwd, '.loreli');
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, `task-${Date.now()}.md`);
+    await writeFile(file, message, 'utf8');
+    log.info(`${this.identity?.name ?? '?'} prompt written to ${file}`);
+
+    await this.tmux.send(this.paneId,
+      `Read the complete task instructions from ${file} and execute them. Follow every instruction precisely.`
+    );
+  }
+}
+
+/**
+ * Build `-c` flags for injecting loreli MCP server config into Codex CLI.
+ *
+ * Codex only reads `~/.codex/config.toml` (global), not the local
+ * `.codex/config.toml` in the working directory. The `-c` flag is
+ * the only reliable way to add MCP servers at runtime. When context
+ * is provided, LORELI_* env vars are also injected so the MCP server
+ * subprocess can hydrate session state on startup.
+ *
+ * @param {object} [context] - Agent context for env 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.token] - GitHub token (forwarded via env_vars).
+ * @returns {string} `-c` flag string (with leading space) or empty string.
+ */
+function mcpFlags(context) {
+  const flags = [
+    `-c 'mcp_servers.loreli.command="npx"'`,
+    `-c 'mcp_servers.loreli.args=["loreli", "mcp"]'`
+  ];
+
+  if (context?.session) {
+    flags.push(`-c 'mcp_servers.loreli.env.LORELI_SESSION="${context.session}"'`);
+    flags.push(`-c 'mcp_servers.loreli.env.LORELI_AGENT="${context.agent}"'`);
+    flags.push(`-c 'mcp_servers.loreli.env.LORELI_REPO="${context.repo}"'`);
+    if (context.home) flags.push(`-c 'mcp_servers.loreli.env.LORELI_HOME="${context.home}"'`);
+    // Forward token from parent process env without embedding the
+    // literal secret in CLI flags, logs, or launcher command strings.
+    if (context.token) flags.push(`-c 'mcp_servers.loreli.env_vars=["GITHUB_TOKEN"]'`);
+  }
+
+  return ' ' + flags.join(' ');
+}
+
+/**
+ * Build `-c` flags for injecting `rules.prefix_rules` into Codex CLI.
+ *
+ * Codex supports `rules.prefix_rules` in its `config.toml` to forbid
+ * commands by token pattern. Since Codex has no hooks system, this is
+ * the only way to block tool execution at the CLI level.
+ *
+ * @param {string[]} denied - Commands to block.
+ * @returns {string} `-c` flag string (with leading space) or empty string.
+ */
+function rulesFlags(denied) {
+  if (!denied?.length) return '';
+  const rules = denied.map(function toRule(cmd) {
+    return `{pattern=[{token="${cmd}"}], decision="forbidden", justification="Use Loreli MCP tools instead of ${cmd}"}`;
+  });
+  return ` -c 'rules.prefix_rules=[${rules.join(', ')}]'`;
+}
+
+/**
+ * Build the codex CLI command string.
+ *
+ * Flags:
+ * - `-a never`: disable approval prompts for unattended operation.
+ *   `--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
+ * - `--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
+ * - `-c rules.prefix_rules`: inject command deny rules
+ *
+ * @param {string} model - Resolved model identifier.
+ * @param {string} cwd - Working directory.
+ * @param {object} [context] - Agent context for MCP env injection.
+ * @param {string[]} [denied=[]] - Commands to block via prefix rules.
+ * @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)}`;
+}