loreli 0.0.0 → 2.0.0

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

@@ -0,0 +1,351 @@
+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 {
+  /**
+   * Regex patterns that identify known Codex CLI blocking dialogs.
+   * Matched against pane output by diagnose() for rapid-death
+   * remediation and stall monitor fallback.
+   *
+   * Each entry carries a `remedy` — an array of tmux key names that
+   * the orchestrator sends to dismiss the dialog. Patterns are
+   * checked in order; first match wins.
+   *
+   * @type {Array<{pattern: RegExp, category: string, reasoning: string, remedy?: string[]}>}
+   */
+  static patterns = [
+    {
+      pattern: /choose how you'd like.*to proceed/is,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI showing model upgrade selection — selecting "Use existing model"',
+      remedy: ['Down', 'Enter']
+    },
+    {
+      pattern: /invalid model name/i,
+      category: 'fatal',
+      reasoning: 'Codex CLI received invalid model name — API key may not support the requested model'
+    },
+    {
+      pattern: /update available!.*\n.*press enter to continue/is,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI showing update-available dialog requiring Enter to dismiss',
+      remedy: ['Enter']
+    },
+    {
+      pattern: /press enter to continue/i,
+      category: 'option_dialog',
+      reasoning: 'Codex CLI waiting for Enter keypress to continue',
+      remedy: ['Enter']
+    }
+  ];
+
+  /**
+   * Detect known Codex CLI blocking patterns in pane output.
+   *
+   * @param {string} output - Captured pane content.
+   * @returns {{category: string, reasoning: string, remedy?: string[]}|null} Diagnosis, or null if unrecognized.
+   */
+  static diagnose(output) {
+    if (!output) return null;
+    for (const { pattern, category, reasoning, remedy } of CodexBackend.patterns) {
+      if (pattern.test(output)) return { category, reasoning, ...(remedy && { remedy }) };
+    }
+    return null;
+  }
+
+  /**
+   * 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: []
+    };
+  }
+  /**
+   * One-shot LLM call via `codex exec` (non-interactive mode).
+   *
+   * @param {string} prompt - Text prompt to send.
+   * @param {object} [opts] - Options.
+   * @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.
+   */
+  static async oneshot(prompt, { model, config, timeout, discovered } = {}) {
+    const resolved = resolve(model ?? 'fast', 'codex', 'openai', config, discovered);
+    const vars = env('codex', config) ?? {};
+    return CliAgent._exec('codex', [
+      'exec', '--ephemeral', '--skip-git-repo-check', prompt, '-m', resolved
+    ], vars, timeout);
+  }
+
+  /**
+   * @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, opts.discovered);
+
+    const denied = opts.config?.get?.('agents.disallowedTools') ?? [];
+    const mode = opts.role === 'planner' ? 'plan' : undefined;
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd, opts.context, denied, mode)
+    });
+
+    /** @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 read-only`: read-only sandbox (planner)
+ * - `-s workspace-write`: sandbox to workspace write access (action/reviewer)
+ * - `--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.
+ * @param {string} [mode] - Execution mode ('plan' for planner read-only mode).
+ * @returns {string} CLI command string.
+ */
+function buildCommand(model, cwd, context, denied = [], mode) {
+  const sandbox = mode === 'plan' ? 'read-only' : 'workspace-write';
+  return `codex --model ${model} -a never -s ${sandbox} --no-alt-screen -C '${cwd}'${mcpFlags(context)}${rulesFlags(denied)}`;
+}