@bevel-software/ael 0.0.0-stage → 0.1.0

package/src/harness/claude-code.ts

@@ -0,0 +1,397 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { MCP_SERVER_NAME, type Harness, type RunEvent, type SessionResult, type SessionStartParams, type SessionState } from '../run/contract.js';
+import { VERDICT_NUDGE, parseOutputs, parseVerdict, tail } from '../run/verdict.js';
+
+/**
+ * Claude Code inside a run container: the `claude-code` harness of a
+ * container step. One `claude -p` process per turn, its stream-JSON output
+ * translated into the run's events; the knowledge base's tools through the
+ * local Hexis MCP server as the actor, local tools such as `git` included
+ * (the only MCP server it may load); signed in to the person's own
+ * subscription with the long-lived token `claude setup-token` prints, which
+ * reaches the container as `CLAUDE_CODE_OAUTH_TOKEN` from the vault.
+ *
+ * The CLI ships in the harness bundle (the `@anthropic-ai/claude-code`
+ * package and the native binary of the executor's platform) and is started
+ * through the package's own launcher on the bundle's node, which picks the
+ * binary for the container it runs in — so a run image needs nothing
+ * installed. The session's transcript file is the stored state, so a step
+ * resumes on any executor, not only the one that wrote it.
+ */
+
+export interface ClaudeCodeOptions {
+  /** How the CLI is started: node and the package's launcher, unless a test hands its own. */
+  command?: { file: string; args: string[] };
+  /** Spawns the CLI; Node's own unless a test hands a fake. */
+  spawn?: typeof nodeSpawn;
+  /** Default step budget when the caller gives none. */
+  defaultTimeoutMs?: number;
+  /** The nudge is one short turn; it never gets a step's full budget. */
+  verdictNudgeTimeoutMs?: number;
+  /** The clock, for the reset time a subscription limit names. */
+  now?: () => number;
+  /** Whether the container is on musl (then the image's own `claude` runs); read from `/lib` unless a test says. */
+  isMusl?: () => boolean;
+}
+
+const STATE_VERSION = 1;
+/** Credentials that outrank the subscription token in Claude Code's own precedence: never handed to the CLI. */
+const OUTRANKING_CREDENTIALS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'];
+const SESSION_LIMIT = /you'?ve hit your (session|usage|weekly) limit|usage limit reached|limit will reset/i;
+const RESETS_AT = /resets?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*(?:\(UTC\))?/i;
+const TOKEN_REFUSED = /invalid bearer token|invalid api key|not logged in|please run \/login|oauth token (has )?(expired|been revoked)|authentication_error|\b401\b/i;
+const UNKNOWN_SESSION = /no conversation found with session id/i;
+/** A session id as Claude Code mints them (a UUID); anything else is not used to name a file. */
+const SESSION_ID = /^[A-Za-z0-9_-]+$/;
+
+/** The state a step resumes from: the session's id and its transcript file. */
+interface ClaudeState {
+  sessionId: string;
+  /** The session's JSONL transcript, as Claude Code wrote it. */
+  transcript: string;
+}
+
+const now = () => new Date().toISOString();
+
+/** Where Claude Code keeps a session's transcript: its project folder is the working directory with every other character a dash. */
+export function claudeProjectDir(configDir: string, cwd: string): string {
+  return path.join(configDir, 'projects', cwd.replace(/[^a-zA-Z0-9]/g, '-'));
+}
+
+/**
+ * The CLI as the bundle ships it: the package's launcher, run on the node
+ * running this. The bundle carries the native binary of the executor's own
+ * platform (glibc); on a musl image (Alpine) it cannot start, and the image's
+ * own `claude` runs instead.
+ */
+function defaultCommand(isMusl: () => boolean = muslLoaderPresent): { file: string; args: string[] } {
+  if (isMusl()) return { file: 'claude', args: [] };
+  const require = createRequire(import.meta.url);
+  return { file: process.execPath, args: [require.resolve('@anthropic-ai/claude-code/cli-wrapper.cjs')] };
+}
+
+/** A musl system: its dynamic loader is in `/lib` (what the harness's node launcher checks too). */
+function muslLoaderPresent(): boolean {
+  try {
+    return readdirSync('/lib').some((name) => name.startsWith('ld-musl-'));
+  } catch {
+    return false;
+  }
+}
+
+/** The next instant at the wall-clock time a limit message names (read in UTC), at or after now. */
+function nextReset(hour12: number, minute: number, meridiem: string, nowMs: number): number {
+  const hour = meridiem.toLowerCase() === 'pm' ? (hour12 % 12) + 12 : hour12 % 12;
+  const d = new Date(nowMs);
+  const at = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), hour, minute, 0, 0);
+  return at >= nowMs ? at : at + 24 * 60 * 60_000;
+}
+
+interface TurnOutput {
+  events: RunEvent[];
+  sessionId?: string;
+  finalText: string;
+  /** The terminal `result` event's own text: the CLI's word, never the model's prose. */
+  resultText: string;
+  /** The CLI ended its turn with a terminal `result` event. */
+  hasResult: boolean;
+  isError: boolean;
+  usage?: { input?: number; output?: number };
+  /** Everything it printed on stderr, for the classification of a refusal. */
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+}
+
+export class ClaudeCodeHarness implements Harness {
+  readonly name = 'claude-code';
+
+  constructor(private readonly options: ClaudeCodeOptions = {}) {}
+
+  async run(p: SessionStartParams): Promise<SessionResult> {
+    const cwd = p.cwd ?? process.cwd();
+    const env = this.sessionEnv(p);
+    const configDir = env.CLAUDE_CONFIG_DIR ?? path.join(env.HOME ?? cwd, '.claude');
+    await this.prepareConfig(env, configDir);
+    const events: RunEvent[] = [];
+    const emit = (event: RunEvent) => {
+      events.push(event);
+      p.onEvent?.(event);
+    };
+
+    // Resume from the stored transcript wherever this step runs now.
+    let resumeId = await this.restore(p.state, configDir, cwd);
+    emit({ type: 'user', at: now(), text: p.input.text });
+    let turn = await this.turn(p, env, cwd, p.input.text, resumeId, p.timeoutMs ?? this.options.defaultTimeoutMs ?? 30 * 60_000, emit, !!resumeId);
+    if (resumeId && !turn.timedOut && !turn.hasResult && UNKNOWN_SESSION.test(`${turn.stderr}\n${turn.resultText}`)) {
+      // The stored session cannot be resumed (another CLI version, a lost file): the step starts afresh rather than failing.
+      resumeId = undefined;
+      turn = await this.turn(p, env, cwd, p.input.text, undefined, p.timeoutMs ?? this.options.defaultTimeoutMs ?? 30 * 60_000, emit, false);
+    }
+
+    // A turn that ends early — past its budget, or refused — keeps its session, so the retry resumes the work done.
+    const early = await this.endedEarly(turn, p, configDir, emit);
+    if (early) return { ...early, events };
+    if (!turn.hasResult && !events.some((e) => e.type === 'assistant' || e.type === 'tool_call')) {
+      return { ok: false, finalText: tail(turn.stderr || turn.finalText), sessionNotStarted: true, events };
+    }
+
+    let finalText = turn.finalText;
+    let verdict = parseVerdict(finalText);
+    // A session that ended cleanly without the verdict this step needs is asked for it once.
+    if (p.expectVerdict && !verdict && turn.hasResult && !turn.isError && turn.sessionId && !p.signal?.aborted) {
+      emit({ type: 'user', at: now(), text: VERDICT_NUDGE });
+      const nudge = await this.turn(p, env, cwd, VERDICT_NUDGE, turn.sessionId, this.options.verdictNudgeTimeoutMs ?? 2 * 60_000, emit, true);
+      // A limit, a refused token or a timeout on the nudge is that outcome, not a session that merely gave no verdict.
+      const nudgeEarly = await this.endedEarly({ ...nudge, sessionId: nudge.sessionId ?? turn.sessionId }, p, configDir, emit);
+      if (nudgeEarly) return { ...nudgeEarly, events };
+      if (nudge.hasResult && !nudge.isError) {
+        finalText = `${finalText}\n${nudge.finalText}`;
+        verdict = parseVerdict(nudge.finalText);
+        turn = { ...nudge, finalText };
+      }
+    }
+    const ok = turn.hasResult && !turn.isError && turn.exitCode === 0;
+    if (!ok && !events.some((e) => e.type === 'error')) emit({ type: 'error', at: now(), message: tail(turn.stderr || finalText) });
+    emit({ type: 'session_ended', at: now(), ok, finalText, ...(turn.usage ? { usage: turn.usage } : {}) });
+    const state = await this.keep(turn.sessionId, p, configDir);
+    const outputs = parseOutputs(finalText);
+    return { ok, finalText, ...(verdict ? { verdict } : {}), ...(outputs ? { outputs } : {}), ...(state ? { state } : {}), events };
+  }
+
+  /** A timeout or a refusal, with the session's state stored for the retry; null for a turn that ran its course. */
+  private async endedEarly(turn: TurnOutput, p: SessionStartParams, configDir: string, emit: (e: RunEvent) => void): Promise<Omit<SessionResult, 'events'> | null> {
+    // Past its budget is a timeout whatever it printed.
+    const outcome = turn.timedOut ? { ok: false, timedOut: true, finalText: tail(turn.finalText || turn.stderr) } : this.refusal(turn);
+    if (!outcome) return null;
+    // A refused token is a step error whose reason is what to do: the error event is what the step's outcome reads.
+    if (!outcome.timedOut && !outcome.accountLimit) emit({ type: 'error', at: now(), message: outcome.finalText });
+    const state = await this.keep(turn.sessionId, p, configDir);
+    return { ...outcome, ...(state ? { state } : {}) };
+  }
+
+  /** The session's transcript as state, handed to the caller as it is captured. */
+  private async keep(sessionId: string | undefined, p: SessionStartParams, configDir: string): Promise<SessionState | undefined> {
+    const state = await this.capture(sessionId, configDir);
+    if (state) p.onState?.(state);
+    return state;
+  }
+
+  /**
+   * The CLI's environment: the container's, the configuration's `env:` (the
+   * token among them), and nothing that outranks the token in Claude Code's
+   * own precedence — an API key left in the image would otherwise win over
+   * the person's subscription.
+   */
+  private sessionEnv(p: SessionStartParams): Record<string, string> {
+    const env: Record<string, string> = {};
+    for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
+    Object.assign(env, p.env ?? {});
+    if (env.CLAUDE_CODE_OAUTH_TOKEN) for (const name of OUTRANKING_CREDENTIALS) delete env[name];
+    return env;
+  }
+
+  /**
+   * First-run state, so the token is used on the very first run: without it
+   * the CLI can stop at its onboarding instead of reading the token. Written
+   * only when absent; a configuration of the person's own is left alone.
+   */
+  private async prepareConfig(env: Record<string, string>, configDir: string): Promise<void> {
+    await fs.mkdir(configDir, { recursive: true });
+    const settingsFile = env.CLAUDE_CONFIG_DIR ? path.join(configDir, '.claude.json') : path.join(env.HOME ?? path.dirname(configDir), '.claude.json');
+    try {
+      await fs.access(settingsFile);
+    } catch {
+      await fs.writeFile(settingsFile, JSON.stringify({ hasCompletedOnboarding: true }), { mode: 0o600 });
+    }
+  }
+
+  /** Put the stored transcript back where Claude Code looks for it; the session id to resume, or none. */
+  private async restore(state: SessionState | undefined, configDir: string, cwd: string): Promise<string | undefined> {
+    if (!state || state.harness !== this.name || state.version !== STATE_VERSION) return undefined;
+    const data = state.data as Partial<ClaudeState> | null;
+    if (!data || typeof data.sessionId !== 'string' || typeof data.transcript !== 'string') return undefined;
+    // The id names a file: a stored `../x` must not write outside the projects folder.
+    if (!SESSION_ID.test(data.sessionId)) return undefined;
+    const dir = claudeProjectDir(configDir, cwd);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, `${data.sessionId}.jsonl`), data.transcript, { mode: 0o600 });
+    return data.sessionId;
+  }
+
+  /** The session's transcript as state, read from wherever the CLI wrote it under its projects folder. */
+  private async capture(sessionId: string | undefined, configDir: string): Promise<SessionState | undefined> {
+    if (!sessionId || !SESSION_ID.test(sessionId)) return undefined;
+    const projects = path.join(configDir, 'projects');
+    let dirs: string[];
+    try {
+      dirs = await fs.readdir(projects);
+    } catch {
+      return undefined;
+    }
+    for (const dir of dirs) {
+      try {
+        const transcript = await fs.readFile(path.join(projects, dir, `${sessionId}.jsonl`), 'utf8');
+        return { harness: this.name, version: STATE_VERSION, data: { sessionId, transcript } satisfies ClaudeState };
+      } catch {
+        // not in this folder
+      }
+    }
+    return undefined;
+  }
+
+  /** A refusal of the ACCOUNT or the token, read from everything the turn printed; none for an ordinary outcome. */
+  private refusal(turn: TurnOutput): Omit<SessionResult, 'events'> | null {
+    // A clean session that merely QUOTES a refusal (a ticket about rate limits) is not one.
+    if (turn.hasResult && !turn.isError) return null;
+    // Read from the CLI's own diagnostics only — stderr and its terminal result — never from what the model said.
+    const everything = `${turn.stderr}\n${turn.resultText}`;
+    if (SESSION_LIMIT.test(everything)) {
+      const m = everything.match(RESETS_AT);
+      const resetAt = m ? nextReset(Number(m[1]), Number(m[2] ?? 0), m[3]!, (this.options.now ?? Date.now)()) : undefined;
+      return { ok: false, finalText: tail(everything), accountLimit: { kind: 'session-limit', ...(resetAt ? { resetAt } : {}), text: (m ? m[0] : 'subscription usage limit').trim() } };
+    }
+    if (TOKEN_REFUSED.test(everything)) {
+      // The person's token, not the executor's account: a step error that says what to do, never a pause of a shared executor.
+      return {
+        ok: false,
+        finalText: 'Claude Code refused the subscription token (missing, expired or revoked). Run `claude setup-token` on your own machine and enter the new token as CLAUDE_CODE_OAUTH_TOKEN on this configuration\'s page in the Agents app.',
+      };
+    }
+    return null;
+  }
+
+  /** One `claude -p` turn: the prompt on stdin, the stream read line by line into events. */
+  private turn(p: SessionStartParams, env: Record<string, string>, cwd: string, prompt: string, resumeId: string | undefined, timeoutMs: number, emit: (e: RunEvent) => void, resumed: boolean): Promise<TurnOutput> {
+    const command = this.options.command ?? defaultCommand(this.options.isMusl);
+    // The local Hexis MCP server in a run container (local tools run there, git among them); the platform's endpoint otherwise.
+    const server = p.platform.localMcp
+      ? { type: 'stdio', command: p.platform.localMcp.command, args: p.platform.localMcp.args, env: p.platform.localMcp.env }
+      : { type: 'http', url: p.platform.mcpUrl, headers: { Authorization: `Bearer ${p.actorKey.token}` } };
+    const mcpConfig = JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: server } });
+    const args = [
+      ...command.args,
+      '-p',
+      '--output-format',
+      'stream-json',
+      '--verbose',
+      // The container is the boundary: the session may use its own tools there without asking.
+      '--dangerously-skip-permissions',
+      // The knowledge base's server only: a repository's own `.mcp.json` in the workspace may not hand the session more.
+      '--mcp-config',
+      mcpConfig,
+      '--strict-mcp-config',
+    ];
+    if (p.systemPrompt) args.push('--append-system-prompt', p.systemPrompt);
+    if (p.agent.model) args.push('--model', p.agent.model);
+    // `--tools` restricts which built-in tools exist at all (`--allowedTools` only pre-approves, and with
+    // permissions skipped would narrow nothing); names in Claude Code's spelling (`Bash`, `Read`, `Edit`).
+    // The platform's MCP tools are not built-ins and stay, as the person's own tools.
+    // An `mcp__…` entry (the execution layer's `mcp__hexis`) names the knowledge base's server, which is never a built-in.
+    const builtins = p.agent.harnessTools.filter((t) => !t.startsWith('mcp__'));
+    if (builtins.length > 0) args.push('--tools', builtins.join(','));
+    if (resumeId) args.push('--resume', resumeId);
+
+    const out: TurnOutput = { events: [], finalText: '', resultText: '', hasResult: false, isError: false, stderr: '', exitCode: null, timedOut: false };
+    let assistantText = '';
+    const toolNames = new Map<string, string>();
+    const onLine = (line: string) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      let ev: Record<string, unknown>;
+      try {
+        const parsed = JSON.parse(trimmed) as unknown;
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return;
+        ev = parsed as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      if (typeof ev.session_id === 'string') out.sessionId = ev.session_id;
+      if (ev.type === 'system' && ev.subtype === 'init') {
+        const tools = Array.isArray(ev.tools) ? (ev.tools as unknown[]).filter((t): t is string => typeof t === 'string') : undefined;
+        emit({ type: 'session_started', at: now(), harness: this.name, ...(typeof ev.model === 'string' ? { model: ev.model } : {}), ...(out.sessionId ? { sessionId: out.sessionId } : {}), resumed, ...(tools ? { tools } : {}) });
+        return;
+      }
+      const content = (ev.message as { content?: unknown } | undefined)?.content;
+      if (ev.type === 'assistant' && Array.isArray(content)) {
+        for (const block of content as Array<Record<string, unknown>>) {
+          if (block.type === 'text' && typeof block.text === 'string') {
+            assistantText += `${block.text}\n`;
+            emit({ type: 'assistant', at: now(), text: block.text });
+          } else if (block.type === 'tool_use' && typeof block.id === 'string') {
+            const name = typeof block.name === 'string' ? block.name : 'tool';
+            toolNames.set(block.id, name);
+            emit({ type: 'tool_call', at: now(), id: block.id, name, input: block.input });
+          }
+        }
+        return;
+      }
+      if (ev.type === 'user' && Array.isArray(content)) {
+        for (const block of content as Array<Record<string, unknown>>) {
+          if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+            emit({ type: 'tool_result', at: now(), id: block.tool_use_id, name: toolNames.get(block.tool_use_id) ?? 'tool', output: block.content, isError: block.is_error === true });
+          }
+        }
+        return;
+      }
+      if (ev.type === 'result') {
+        out.hasResult = true;
+        out.isError = ev.is_error === true;
+        if (typeof ev.result === 'string') {
+          out.finalText = ev.result;
+          out.resultText = ev.result;
+        }
+        const usage = ev.usage as { input_tokens?: number; output_tokens?: number } | undefined;
+        if (usage) out.usage = { input: usage.input_tokens, output: usage.output_tokens };
+      }
+    };
+
+    return new Promise<TurnOutput>((resolve) => {
+      const spawn = this.options.spawn ?? nodeSpawn;
+      const child = spawn(command.file, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+      let buffer = '';
+      child.stdout?.setEncoding('utf8');
+      child.stdout?.on('data', (chunk: string) => {
+        buffer += chunk;
+        let nl: number;
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+          onLine(buffer.slice(0, nl));
+          buffer = buffer.slice(nl + 1);
+        }
+      });
+      child.stderr?.setEncoding('utf8');
+      child.stderr?.on('data', (chunk: string) => {
+        // Bounded: a chatty CLI must not hold the whole of it.
+        out.stderr = (out.stderr + chunk).slice(-20_000);
+      });
+      const stop = () => child.kill('SIGTERM');
+      const timer = setTimeout(() => {
+        out.timedOut = true;
+        stop();
+      }, timeoutMs);
+      if (p.signal?.aborted) stop();
+      else p.signal?.addEventListener('abort', stop, { once: true });
+      const done = (code: number | null) => {
+        clearTimeout(timer);
+        p.signal?.removeEventListener('abort', stop);
+        if (buffer) onLine(buffer);
+        out.exitCode = code;
+        if (!out.finalText) out.finalText = assistantText.trim();
+        resolve(out);
+      };
+      child.on('error', (err) => {
+        out.stderr += `\n${err instanceof Error ? err.message : String(err)}`;
+        done(null);
+      });
+      child.on('close', (code) => done(code));
+      // A CLI that dies before reading its prompt breaks the pipe: noted, never thrown — its exit says the rest.
+      child.stdin?.on('error', (err) => {
+        out.stderr += `\n${err instanceof Error ? err.message : String(err)}`;
+      });
+      child.stdin?.end(prompt);
+    });
+  }
+}