loreli 0.0.0 → 2.0.0

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

@@ -0,0 +1,387 @@
+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 {
+  /**
+   * Regex patterns that identify known Claude CLI blocking dialogs.
+   *
+   * @type {Array<{pattern: RegExp, category: string, reasoning: string, remedy?: string[]}>}
+   */
+  static patterns = [
+    {
+      pattern: /yes,\s*i\s+accept/i,
+      category: 'option_dialog',
+      reasoning: 'Claude CLI showing bypass-permissions dialog requiring selection',
+      remedy: ['Enter']
+    },
+    {
+      pattern: /do you want to proceed\?[\s\S]*yes,\s*and don't ask again(?:\s+for loreli\s*-\s*[a-z-]+\s*commands)?/i,
+      category: 'option_dialog',
+      reasoning: 'Claude CLI asking MCP tool approval for a Loreli command',
+      remedy: ['2', 'Enter']
+    }
+  ];
+
+  /**
+   * Detect known Claude 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 ClaudeBackend.patterns) {
+      if (pattern.test(output)) return { category, reasoning, ...(remedy && { remedy }) };
+    }
+    return null;
+  }
+
+  /**
+   * 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: []
+    };
+  }
+  /**
+   * One-shot LLM call via `claude -p` (print mode).
+   *
+   * No tmux, no workspace, no identity — just a subprocess that
+   * prints the response and exits. Uses the same model resolution
+   * and env var collection as interactive agents.
+   *
+   * @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', 'claude', 'anthropic', config, discovered);
+    const vars = env('claude', config) ?? {};
+    return CliAgent._exec('claude', [
+      '-p', '--model', resolved, '--output-format', 'text'
+    ], vars, timeout, prompt);
+  }
+
+  /**
+   * @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, opts.discovered);
+
+    const denied = opts.config?.get?.('agents.disallowedTools') ?? [];
+
+    const mode = opts.role === 'planner' ? 'plan' : undefined;
+
+    super({
+      ...opts,
+      command: buildCommand(model, opts.cwd, denied, mode)
+    });
+
+    /** @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;
+
+    /** @type {boolean} Whether MCP readiness (Phase 2) was confirmed. */
+    this._mcpReady = false;
+  }
+
+  /**
+   * 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 {
+        throw new Error(`${name} pane died during readiness check`);
+      }
+
+      // 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`);
+          this._mcpReady = true;
+          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`);
+  }
+
+  /**
+   * Wait for MCP readiness when `_navigate()` Phase 2 timed out.
+   *
+   * Polls for the `.loreli/mcp-ready` marker file that the MCP server
+   * writes after the handshake completes. Without this, prompts sent
+   * immediately after a readiness timeout are dropped because Claude
+   * Code is still in its MCP initialization state.
+   *
+   * @returns {Promise<void>}
+   */
+  async _awaitMcp() {
+    if (this._mcpReady) return;
+
+    const ready = join(this.cwd, '.loreli', 'mcp-ready');
+    const deadline = Date.now() + 30000;
+    const name = this.identity?.name ?? '?';
+
+    while (Date.now() < deadline) {
+      if (existsSync(ready)) {
+        log.info(`${name} MCP tools ready (late)`);
+        this._mcpReady = true;
+        try { await unlink(ready); } catch { /* already cleaned */ }
+        return;
+      }
+      await new Promise(function wait(r) { setTimeout(r, READY_POLL); });
+    }
+
+    log.warn(`${name} MCP readiness not confirmed — sending prompt anyway`);
+    this._mcpReady = true;
+  }
+
+  /**
+   * 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');
+
+    await this._awaitMcp();
+
+    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 (action/reviewer)
+ * - `--permission-mode plan`: read-only plan mode (planner)
+ * - `--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.
+ * @param {string} [mode] - Permission mode ('plan' for read-only).
+ * @returns {string} CLI command string.
+ */
+function buildCommand(model, cwd, denied = [], mode) {
+  const parts = ['claude'];
+
+  if (mode === 'plan') {
+    parts.push('--permission-mode plan');
+  } else {
+    parts.push('--dangerously-skip-permissions');
+  }
+
+  parts.push(`--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(' ');
+}