@opsee/cli 0.11.9

package/src/foreman/claude-worker-adapter.ts

@@ -0,0 +1,412 @@
+import type { Account } from "./account.js";
+import { COMPLETION_REPORT_CONTRACT, completedEvent } from "./completion-report.js";
+import { VENDOR_CONFIG_DIR_ENV } from "./vendor.js";
+import type { InteractiveCommand, InteractiveSessionRequest, McpServerSpec, OutputContract, TurnFailureReason, TurnHandle, TurnRequest, TurnSandbox, WorkerAdapter } from "./worker-adapter.js";
+import {
+  buildWorkerEnv,
+  errorMessage,
+  failedHandle,
+  launchFailureReason,
+  ProcessTurn,
+  rateLimitedEvent,
+  spawnProcess,
+  type ProcessSpawner,
+  type ProcessTurnSpec,
+} from "./worker-process.js";
+
+/**
+ * The Worker Adapter for Claude Code (ADR-0001): the vendor's own `claude` binary, spawned in
+ * headless print mode with JSON streaming, under one Account and pinned to one directory.
+ *
+ * Flags, checked against the CLI reference and headless docs (https://code.claude.com/docs/en/cli-reference.md,
+ * .../headless.md, .../structured-outputs.md) and against `claude --help` plus one recorded run of
+ * 2.1.263 (the happy-turn fixture); `--max-turns` is in the reference and accepted by the binary
+ * but not listed in its `--help`:
+ *
+ * - `-p` prints and exits; `--output-format stream-json` emits one JSON object per line and needs
+ *   `--verbose` in print mode.
+ * - `--json-schema <schema>` requests structured output; the Worker delivers it through a
+ *   `StructuredOutput` tool call and the validated object arrives in the final `result` line as
+ *   `structured_output` (and as JSON text in `result`). A Worker that cannot satisfy the schema
+ *   ends with `subtype: "error_max_structured_output_retries"`.
+ * - `--max-turns <n>` caps agentic turns; the cap ends the run with `subtype: "error_max_turns"`.
+ * - `--resume <session-id>` continues a stored session; the `session_id` is on every line.
+ * - `--permission-mode acceptEdits` lets an unattended Worker write files without a prompt nobody
+ *   is there to answer. It covers file edits and a handful of file commands (`mkdir`, `touch`,
+ *   `rm`, `rmdir`, `mv`, `cp`, `sed`) and nothing else, so the git the Worker is *told* to run is
+ *   pre-approved by name instead (`CLAUDE_GIT_TOOLS`).
+ * - `--permission-prompts none` says who answers a prompt in print mode: nobody, so anything the
+ *   mode and the allow-list do not already settle is denied outright and reported in the stream.
+ *   Without it a turn that reaches for a tool it was not given waits on a question no terminal is
+ *   attached to answer, and the turn ends at the stall timeout with nothing said.
+ * - `--mcp-config <json>` adds MCP servers for the turn and `--strict-mcp-config` makes them the
+ *   only ones (the Verifier's Playwright MCP, core/verifier.ts); `--allowedTools mcp__<name>`
+ *   lets the unattended turn call that server's tools without a permission prompt. Both
+ *   `--mcp-config` and `--allowedTools` are variadic, so each is followed by another flag rather
+ *   than by the prompt, which would otherwise be read as one more of their values.
+ * - A `readonly-browser` turn (`TurnRequest.sandbox`, the Verifier's) also gets `--tools ""`,
+ *   which removes every built-in tool (`--allowedTools` only pre-approves, it never removes
+ *   Read, Glob, Grep, WebFetch, WebSearch, Write, Edit or Bash), and `--permission-mode dontAsk`,
+ *   which denies without a prompt whatever is not allowed, so the MCP server's tools are the only
+ *   ones the turn has. `--tools` is variadic too and is followed by a flag. The mode is `dontAsk`
+ *   and not `default` because 2.1.263 has no `default` choice (`acceptEdits`, `auto`,
+ *   `bypassPermissions`, `manual`, `dontAsk`, `plan`) and `manual` would wait on a prompt nobody
+ *   answers.
+ *
+ * The credential boundary (ADR-0013) is kept by construction: a subscription Account is only ever
+ * named to the process through `CLAUDE_CONFIG_DIR`, an API-key Account only through the value of
+ * the variable it names, copied into `ANTHROPIC_API_KEY` at spawn time (print mode prefers a key
+ * over a login, https://code.claude.com/docs/en/env-vars.md). Nothing here opens a path, and
+ * account-boundary.test.ts runs the adapter under the same fs audit as registration.
+ *
+ * The process seam, the environment building and the turn lifecycle are shared with the Codex
+ * adapter through worker-process.ts.
+ */
+
+export const CLAUDE_BINARY = "claude";
+export const CLAUDE_PERMISSION_MODE = "acceptEdits";
+/** The permission mode of a `readonly-browser` turn: anything not pre-allowed is denied outright. */
+export const CLAUDE_READONLY_PERMISSION_MODE = "dontAsk";
+
+/** Who answers a permission prompt in print mode: nobody. An unattended turn has no terminal, so
+ * the only two ends a prompt can have are "denied and said so" and "hangs until the stall timeout";
+ * this picks the first. `--permission-mode` still decides everything the prompt never reaches. */
+export const CLAUDE_PERMISSION_PROMPTS = "none";
+
+/**
+ * The Bash commands an implementer Worker may run without a prompt.
+ *
+ * The Worker prompt tells it to "Commit your work on this branch" (core/context.ts) and a turn
+ * that leaves no commit past `origin/<base>` is not a Hand-off at all (core/handoff.ts): the
+ * attempt settles incomplete, the Gates never run, the Verifier never runs and no pull request
+ * opens. `acceptEdits` auto-approves the file edits and a handful of file commands, but not
+ * `git add` or `git commit`, so without this list every unattended Claude turn asks a question
+ * nobody is there to answer.
+ *
+ * The list mirrors the Foreman's own git guard (core/workspace.ts `guardedGit`, ADR-0003): a fixed
+ * set of subcommands, nothing that reaches a remote, nothing that moves the branch.
+ *
+ * - No `push`, `fetch`, `remote` or `ls-remote`: the Foreman pushes the branch and opens the draft
+ *   pull request itself (core/handoff.ts), through the guarded runner that refuses the default
+ *   branch, and the prompt tells the Worker not to.
+ * - No `merge` or `pull`, for the same reason the guard refuses them.
+ * - No `checkout`, `switch`, `branch` or `worktree`: the prompt says never change branches, and a
+ *   branch renamed or left detached is one the Hand-off can no longer count commits on.
+ * - `diff` is here although the guard has no use for it: a Worker about to commit reads what it is
+ *   staging, and a denial there would only push it towards `cat`-ing files it already has open.
+ *
+ * Everything else is left to the denial `CLAUDE_PERMISSION_PROMPTS` makes automatic: a turn that
+ * reaches for something outside this list is told no in its own stream, and reports it, rather than
+ * stalling silently.
+ */
+export const CLAUDE_GIT_TOOLS: readonly string[] = [
+  "Bash(git add:*)",
+  "Bash(git commit:*)",
+  "Bash(git status:*)",
+  "Bash(git diff:*)",
+  "Bash(git log:*)",
+  "Bash(git show:*)",
+  "Bash(git rev-parse:*)",
+  "Bash(git rev-list:*)",
+];
+
+export interface ClaudeWorkerAdapterOptions {
+  spawn?: ProcessSpawner;
+  /** Base environment the Worker inherits before the Account's variables are applied. */
+  baseEnv?: Readonly<Record<string, string | undefined>>;
+  /** Sees every raw stdout line before it is parsed; the debug command uses it to re-record fixtures. */
+  onLine?: (line: string) => void;
+}
+
+/** The variable print mode reads an API key from (https://code.claude.com/docs/en/env-vars.md). */
+export const CLAUDE_API_KEY_ENV = "ANTHROPIC_API_KEY";
+
+/** The Worker's environment for one Account (see `buildWorkerEnv`). */
+export function buildClaudeEnv(
+  account: Account,
+  baseEnv: Readonly<Record<string, string | undefined>>,
+  overrides: Readonly<Record<string, string>> = {},
+  sandbox: TurnSandbox = "worker",
+): Record<string, string> {
+  return buildWorkerEnv(account, { configDir: VENDOR_CONFIG_DIR_ENV.claude, apiKey: CLAUDE_API_KEY_ENV }, baseEnv, overrides, sandbox);
+}
+
+/** The attended turn (story 53): `claude --resume <session-id>`, the interactive form of the same
+ * resume the unattended turn uses (https://code.claude.com/docs/en/cli-reference.md), with no `-p`
+ * so the terminal is the vendor's own. */
+export function buildClaudeInteractiveArgs(sessionId: string): string[] {
+  return ["--resume", sessionId];
+}
+
+/** The `--mcp-config` document for the request's MCP servers (https://code.claude.com/docs/en/mcp.md). */
+export function claudeMcpConfig(servers: Readonly<Record<string, McpServerSpec>>): Record<string, unknown> {
+  return { mcpServers: Object.fromEntries(Object.entries(servers).map(([name, s]) => [name, { type: "stdio", command: s.command, args: s.args, ...(s.env ? { env: s.env } : {}) }])) };
+}
+
+/** The attended planning session (story 10): `claude <prompt>`, the interactive form with the
+ * prompt as its first message (`claude [options] [command] [prompt]`, "starts an interactive
+ * session by default"; https://code.claude.com/docs/en/cli-reference.md). No `-p`, no schema, no
+ * permission mode: the human is there to answer. */
+export function buildClaudeInteractiveSessionArgs(prompt: string): string[] {
+  return [prompt];
+}
+
+export function buildClaudeArgs(request: TurnRequest, resumeSessionId?: string): string[] {
+  const contract = request.contract ?? COMPLETION_REPORT_CONTRACT;
+  const args = ["-p", "--output-format", "stream-json", "--verbose"];
+  const servers = request.mcpServers ?? {};
+  const readonly = request.sandbox === "readonly-browser";
+  // `mcp__<server>` allows every tool of that server. A read-only turn has no built-in tool to
+  // allow (`--tools ""` below removes them), so the git list is the implementer's alone.
+  const allowed = [...Object.keys(servers).map((name) => `mcp__${name}`), ...(readonly ? [] : CLAUDE_GIT_TOOLS)];
+  // A variadic flag ends at the next flag, so every list here is followed by one, never by the prompt.
+  if (allowed.length > 0) args.push("--allowedTools", ...allowed);
+  if (Object.keys(servers).length > 0) {
+    args.push("--mcp-config", JSON.stringify(claudeMcpConfig(servers)), "--strict-mcp-config");
+  }
+  // No built-in tool at all for a read-only turn; `--tools` is variadic and is followed by a flag.
+  if (readonly) args.push("--tools", "");
+  args.push(
+    "--json-schema",
+    JSON.stringify(contract.jsonSchema),
+    "--permission-mode",
+    readonly ? CLAUDE_READONLY_PERMISSION_MODE : CLAUDE_PERMISSION_MODE,
+    "--permission-prompts",
+    CLAUDE_PERMISSION_PROMPTS,
+  );
+  if (request.maxTurns !== undefined) args.push("--max-turns", String(request.maxTurns));
+  if (resumeSessionId !== undefined) args.push("--resume", resumeSessionId);
+  args.push(request.prompt);
+  return args;
+}
+
+/**
+ * The strings by which a rate limit reaches print mode as the text of an error result rather than
+ * as a `rate_limit_event` (https://code.claude.com/docs/en/errors.md lists the first three). Matched
+ * only against error results, since a Worker's own report may well mention a rate limit it met.
+ */
+export const RATE_LIMIT_TEXT_PATTERNS: readonly RegExp[] = [
+  /hit your (session|weekly|usage) limit/i,
+  /usage limit reached/i,
+  /request rejected \(429\)/i,
+  /rate limit/i,
+];
+
+/**
+ * The strings by which a dead credential reaches print mode (OPS-288). Every one is a documented
+ * message from https://code.claude.com/docs/en/errors.md and every one means the login itself is
+ * finished: Claude Code is telling the operator to authenticate again, or the API refused the
+ * credentials outright. Matched only against error results, like `RATE_LIMIT_TEXT_PATTERNS`, and
+ * only after them — a message that reads as both is a rate limit, because a Pause lifts by itself
+ * where a quarantine waits for a human.
+ *
+ * Narrow on purpose. Documented messages deliberately left out, because none of them says the
+ * credential is dead and each would cost a working Account a Lane for the night:
+ * `Credit balance is too low` and the spend-cap family are a funded identity that is out of money
+ * (quota, which is OPS-289's ground); `This organization has been disabled` and the org-policy
+ * messages are a policy state a re-login cannot change; the AWS/Bedrock messages name a credential
+ * chain the Foreman never hands a Worker.
+ */
+export const CREDENTIAL_TEXT_PATTERNS: readonly RegExp[] = [
+  // "Not logged in · Please run /login", "Login expired · Please run /login",
+  // "OAuth token refresh failed — run /login to re-authenticate", "JWT refresh failed: no OAuth token — run /login".
+  /run \/login/i,
+  // "Login expired", "Claude.ai login expired", "Anthropic profile login expired".
+  /login expired/i,
+  /oauth token (has expired|revoked)/i,
+  /oauth session expired and could not be refreshed/i,
+  /invalid api key/i,
+  // "API Error: 401 Invalid authentication credentials".
+  /api error: 401/i,
+];
+
+/** The `Claude AI usage limit reached|<unix seconds>` form carries its reset; the "resets 5am"
+ * form names a wall-clock time without a date and is left to the scheduler's default. */
+export function resetAtFromLimitText(text: string): string | undefined {
+  const epoch = /\|(\d{9,10})\b/.exec(text);
+  return epoch ? new Date(Number(epoch[1]) * 1000).toISOString() : undefined;
+}
+
+/** The Claude Code tool through which `--json-schema` output is delivered; its input is the report. */
+export const STRUCTURED_OUTPUT_TOOL = "StructuredOutput";
+
+interface StreamLine {
+  type?: string;
+  subtype?: string;
+  session_id?: string;
+  message?: { content?: unknown };
+  rate_limit_info?: { status?: string; resetsAt?: number; rateLimitType?: string };
+  is_error?: boolean;
+  result?: unknown;
+  structured_output?: unknown;
+  total_cost_usd?: number;
+  num_turns?: number;
+  errors?: unknown;
+}
+
+/** Translates one Claude Code print-mode stream into the adapter's event stream; one per turn. */
+class ClaudeTurn extends ProcessTurn {
+  private rateLimit: { message: string; resetAt?: string } | undefined;
+
+  constructor(spec: ProcessTurnSpec, private readonly contract: OutputContract) {
+    super(spec);
+    this.begin();
+  }
+
+  protected handleMessage(parsed: unknown): void {
+    const line = parsed as StreamLine;
+    if (typeof line.session_id === "string" && line.session_id !== "" && this.sessionId === undefined) {
+      this.sessionId = line.session_id;
+    }
+    switch (line.type) {
+      case "system":
+        if (line.subtype === "init" && typeof line.session_id === "string") {
+          this.sessionId = line.session_id;
+          this.emit({ type: "started", sessionId: line.session_id });
+        }
+        return;
+      case "assistant":
+        this.handleAssistant(line.message?.content);
+        return;
+      case "rate_limit_event":
+        this.handleRateLimit(line.rate_limit_info);
+        return;
+      case "result":
+        this.handleResult(line);
+        return;
+      default:
+        return;
+    }
+  }
+
+  private handleAssistant(content: unknown): void {
+    if (!Array.isArray(content)) return;
+    for (const block of content as { type?: string; text?: string; name?: string }[]) {
+      if (block.type === "text" && typeof block.text === "string" && block.text !== "") {
+        this.emit({ type: "output", text: block.text });
+      } else if (block.type === "tool_use" && typeof block.name === "string" && block.name !== STRUCTURED_OUTPUT_TOOL) {
+        this.emit({ type: "tool", name: block.name });
+      }
+    }
+  }
+
+  private handleRateLimit(info: StreamLine["rate_limit_info"]): void {
+    // `allowed` and `allowed_warning` are advisory (a warning fires at 90% of a window and the run
+    // goes on); only a refusal is reported, and it fails the turn only if the result confirms it.
+    if (!info || info.status === "allowed" || info.status === "allowed_warning") return;
+    const resetAt = typeof info.resetsAt === "number" ? new Date(info.resetsAt * 1000).toISOString() : undefined;
+    const message = `Rate limit ${info.status ?? "reported"}${info.rateLimitType ? ` (${info.rateLimitType})` : ""}`;
+    this.rateLimit = { message, resetAt };
+    this.emit(rateLimitedEvent(message, resetAt));
+  }
+
+  private handleResult(line: StreamLine): void {
+    const sessionId = this.sessionId;
+    const resultText = typeof line.result === "string" ? line.result : "";
+    const failure = (reason: TurnFailureReason, message: string, details?: string[]) =>
+      this.end({ type: "failed", reason, message, sessionId, details });
+    const isError = line.is_error === true || (line.subtype !== undefined && line.subtype !== "success");
+
+    if (!isError) {
+      const parsed = this.contract.parse(line.structured_output ?? resultText);
+      if (!parsed.ok) {
+        failure("invalid_report", `The Worker's final message is not a ${this.contract.name}`, parsed.errors);
+      } else if (sessionId === undefined) {
+        failure("vendor_error", "The Worker reported without ever naming its session");
+      } else {
+        this.end({
+          type: "completed",
+          sessionId,
+          ...completedEvent(this.contract, parsed.value, sessionId),
+          // Read off the vendor's final line and carried on the event; nothing consumes it yet.
+          // It is deliberately not written to the Run Record as a `spend` event: that event counts
+          // Opsee credits and per-model tokens, not a vendor's dollars for the operator's own
+          // subscription (see "Spend is not tracked yet" in the README).
+          costUsd: typeof line.total_cost_usd === "number" ? line.total_cost_usd : undefined,
+          numTurns: typeof line.num_turns === "number" ? line.num_turns : undefined,
+        });
+      }
+      return;
+    }
+
+    if (this.rateLimit) {
+      failure("rate_limited", this.rateLimit.message, resultText ? [resultText] : undefined);
+      return;
+    }
+    const errorTexts = Array.isArray(line.errors) ? (line.errors as unknown[]).map(String) : [];
+    const limitText = [resultText, ...errorTexts].find((t) => RATE_LIMIT_TEXT_PATTERNS.some((p) => p.test(t)));
+    if (limitText !== undefined) {
+      this.emit(rateLimitedEvent(limitText, resetAtFromLimitText(limitText)));
+      failure("rate_limited", limitText);
+      return;
+    }
+    // After the rate limit and before the catch-all: a refused credential is otherwise a
+    // `vendor_error`, indistinguishable from a bad working directory, and the Account keeps being
+    // handed Tasks all night (OPS-288).
+    const credentialText = [resultText, ...errorTexts].find((t) => CREDENTIAL_TEXT_PATTERNS.some((p) => p.test(t)));
+    if (credentialText !== undefined) {
+      failure("credential_failed", credentialText);
+      return;
+    }
+    switch (line.subtype) {
+      case "error_max_turns":
+        failure("max_turns", "The Worker reached its turn cap before it reported", resultText ? [resultText] : undefined);
+        return;
+      case "error_max_structured_output_retries":
+        failure("invalid_report", `The Worker could not produce a schema-valid ${this.contract.name}`, [resultText || "no final message"]);
+        return;
+      default:
+        failure("vendor_error", resultText || errorTexts.join("; ") || `result ${line.subtype ?? "error"}`);
+    }
+  }
+}
+
+export class ClaudeWorkerAdapter implements WorkerAdapter {
+  private readonly spawn: ProcessSpawner;
+  private readonly baseEnv: Readonly<Record<string, string | undefined>>;
+  private readonly onLine: ((line: string) => void) | undefined;
+
+  constructor(options: ClaudeWorkerAdapterOptions = {}) {
+    this.spawn = options.spawn ?? spawnProcess;
+    this.baseEnv = options.baseEnv ?? process.env;
+    this.onLine = options.onLine;
+  }
+
+  launch(request: TurnRequest): TurnHandle {
+    return this.start(request, undefined);
+  }
+
+  resume(sessionId: string, request: TurnRequest): TurnHandle {
+    return this.start(request, sessionId);
+  }
+  interactiveCommand(sessionId: string, request: Pick<TurnRequest, "account" | "cwd">): InteractiveCommand {
+    return { command: CLAUDE_BINARY, args: buildClaudeInteractiveArgs(sessionId), cwd: request.cwd, env: buildClaudeEnv(request.account, this.baseEnv) };
+  }
+
+  interactiveSession(request: InteractiveSessionRequest): InteractiveCommand {
+    return { command: CLAUDE_BINARY, args: buildClaudeInteractiveSessionArgs(request.prompt), cwd: request.cwd, env: buildClaudeEnv(request.account, this.baseEnv) };
+  }
+
+
+  private start(request: TurnRequest, resumeSessionId: string | undefined): TurnHandle {
+    let env: Record<string, string>;
+    try {
+      env = buildClaudeEnv(request.account, this.baseEnv, request.env, request.sandbox);
+    } catch (error) {
+      return failedHandle(errorMessage(error), launchFailureReason(error));
+    }
+    return new ClaudeTurn(
+      {
+        spawn: this.spawn,
+        command: CLAUDE_BINARY,
+        args: buildClaudeArgs(request, resumeSessionId),
+        options: { cwd: request.cwd, env },
+        stallTimeoutMs: request.stallTimeoutMs,
+        sessionId: resumeSessionId,
+        onLine: this.onLine,
+      },
+      request.contract ?? COMPLETION_REPORT_CONTRACT,
+    );
+  }
+}
+