@gethmy/harness 1.0.0

package/src/sdk-agent-runner.ts

@@ -0,0 +1,575 @@
+/**
+ * SdkAgentRunner — productionized from the #417 Phase 2 spike (GO, comment
+ * `ae0c55f9`). An {@link AgentRunner} built on `@anthropic-ai/claude-agent-sdk`'s
+ * `query()` that maps SDK messages → {@link AgentRunEventDraft} (the same union the
+ * CliAgentRunner produces). It is a *runtime swap*, not a provider change — the model
+ * is still Claude, the host `claude` login still authenticates, the worktree, prompt,
+ * verification and PR pipeline are unchanged (#430 covers cross-provider runners).
+ *
+ * Selected by `AgentConfig.runner === "sdk"`; the CLI runner stays the default and the
+ * indefinite fallback. The worker drives the run by iterating {@link start}/{@link resume}
+ * and feeding the drafts into the same progress tracker + run-event stream the CLI path
+ * uses, so the surrounding lifecycle (watchdog, cancel, verify, completion) is identical.
+ *
+ * The two non-obvious requirements from the spike, both load-bearing:
+ *
+ *  1. **Cancellation parity (the single most important task).** The SDK's default spawn
+ *     only kills the leader — *worse* than the CLI, which orphans the model's
+ *     grandchildren (a disowned `sleep 600 &`). So we inject {@link spawnInGroup} via
+ *     `Options.spawnClaudeCodeProcess`, making the child a process-group leader, and
+ *     {@link stop} escalates a cooperative `abort()` → `terminateGroup` on the **negative
+ *     pgid** (SIGINT→TERM→KILL), reaping the whole subtree at CLI parity. The worker also
+ *     receives the child via `onSpawn` so its existing pause/resume/cancel paths keep
+ *     working on `this.process`.
+ *
+ *  2. **MCP visibility.** The Agent SDK loads all filesystem setting sources (incl. the
+ *     host `claude` MCP config, where the harmony server is registered) when
+ *     `settingSources` is omitted — the proven spike behaviour and CLI parity, so that is
+ *     the default. An operator can instead declare the harmony MCP explicitly via
+ *     `mcpServers` (+ `strictMcpConfig` / `settingSources: []`) once validated in prod —
+ *     the "explicit declaration" improvement, gated as a config opt-in rather than a
+ *     big-bang.
+ */
+
+import type { ChildProcess } from "node:child_process";
+import {
+  type McpServerConfig,
+  type Options,
+  query,
+  type SDKMessage,
+  type SettingSource,
+  type SpawnedProcess,
+  type SpawnOptions,
+} from "@anthropic-ai/claude-agent-sdk";
+import type {
+  AgentRunEventDraft,
+  AgentRunInput,
+  AgentRunner,
+  ResumeInput,
+  StopReason,
+  UserAgentMessage,
+} from "@harmony/shared";
+import { type ApiErrorKind, classifyRunError } from "./error-classifier.js";
+import { reapGroup, spawnInGroup, terminateGroup } from "./process-group.js";
+
+/**
+ * Default allowed-tool surface — mirrors the CLI's `IMPLEMENT_ALLOWED_TOOLS`. The CLI
+ * passes a comma string to `--allowedTools`; the SDK takes `string[]`. The worker
+ * overrides this per-spawn (e.g. the read-only planning pass).
+ */
+export const SDK_ALLOWED_TOOLS = [
+  "Bash",
+  "Read",
+  "Write",
+  "Edit",
+  "Glob",
+  "Grep",
+  "Agent",
+  "mcp__harmony__*",
+];
+
+const MAX_TEXT_LEN = 8_000;
+const MAX_OUTPUT_LEN = 4_000;
+/** Grace windows for the belt-and-suspenders pgid escalation in {@link stop}. */
+const STOP_SIGINT_MS = 2_000;
+const STOP_SIGTERM_MS = 2_000;
+
+export interface SdkRunnerConfig {
+  /** Model id for the run (per-attempt tier selection lives in the worker). */
+  model?: string;
+  /** Max conversation turns before the SDK stops the query. */
+  maxTurns?: number;
+  /** Allowed tools (SDK array form). Defaults to {@link SDK_ALLOWED_TOOLS}. */
+  allowedTools?: string[];
+  /**
+   * Denied tools (SDK array form). A disallow wins over `allowedTools`, so this
+   * strips specific tools from a wildcard allow set — used for playbook stage runs
+   * to remove the daemon-owned session/move tools from `mcp__harmony__*` (#576).
+   */
+  disallowedTools?: string[];
+  /**
+   * Native SDK per-query budget cap (USD) — a per-card cost ceiling the daemon
+   * otherwise lacks. Exceeding it ends the query with an `error_max_budget_usd`
+   * result, surfaced as a failure event.
+   */
+  maxBudgetUsd?: number;
+  /**
+   * Filesystem setting sources the SDK loads. Omit (default) → load all, which
+   * includes the host `claude` MCP config (harmony server) — CLI parity. Pass `[]`
+   * for SDK isolation, in which case declare {@link mcpServers} explicitly.
+   */
+  settingSources?: SettingSource[];
+  /**
+   * Explicit MCP server declarations (the #417 "declare harmony MCP explicitly"
+   * improvement). Opt-in: when set, typically paired with {@link strictMcpConfig}.
+   */
+  mcpServers?: Record<string, McpServerConfig>;
+  /** Maps to `--strict-mcp-config`: ignore all MCP config except {@link mcpServers}. */
+  strictMcpConfig?: boolean;
+  /**
+   * Environment variables to DELETE from the spawned child's environment
+   * (Task 15). The Agent SDK builds the child's env from the daemon's own
+   * `process.env` and hands it to {@link spawn} below, so a credential the
+   * parent holds reaches the subagent unless something removes it by name.
+   *
+   * The list is DERIVED from the role's launch — `envKeysDroppedByLaunch`
+   * (runner.ts) reports the keys the launch omitted — so `buildRoleLaunch`
+   * stays the single source of truth for which variables a role may hold, and
+   * no second credential list appears here.
+   */
+  stripEnvKeys?: readonly string[];
+  /**
+   * Hands the spawned process-group leader to the worker so its existing
+   * pause/resume/cancel paths can keep operating on `this.process`.
+   */
+  onSpawn?: (child: ChildProcess) => void;
+}
+
+/** Map the SDK's typed assistant-error union to the daemon's {@link ApiErrorKind}. */
+export function mapSdkErrorKind(e: string | undefined): ApiErrorKind | null {
+  switch (e) {
+    case "authentication_failed":
+    case "oauth_org_not_allowed":
+      return "auth";
+    case "billing_error":
+      return "out_of_credits";
+    case "rate_limit":
+    case "overloaded":
+      return "rate_limit";
+    default:
+      // invalid_request / model_not_found / server_error / unknown / max_output_tokens
+      // → generic crash (null). This is deliberate CLI parity: the shared
+      // `error-classifier.ts` regex only treats 401/402/429/529/overloaded/usage
+      // as API conditions, so a plain Anthropic 5xx `server_error` is a generic
+      // crash (attempt counts) on the CLI path too. Mapping it to a retryable
+      // API kind here would make the SDK path more lenient than the CLI and
+      // mis-apply rate-limit cooldown to a one-off 500 — if 5xx-as-outage is
+      // wanted, change error-classifier.ts so BOTH runners share the behavior.
+      return null;
+  }
+}
+
+export class SdkAgentRunner implements AgentRunner {
+  private abort: AbortController | null = null;
+  private capturedSessionId: string | undefined;
+  private child: ChildProcess | null = null;
+  /**
+   * pgid (=== leader pid) of the spawned Claude Code child, recorded so the
+   * group can be reaped after the run ends even once `this.child` has exited
+   * (a live ChildProcess can't be signalled then). See {@link reapGroup}.
+   */
+  private leaderPid: number | undefined;
+  private capturedStderr = "";
+  /** toolUseId → tool name, so tool_result frames can resolve the name (CLI parity). */
+  private toolNames = new Map<string, string>();
+  /** Model observed off the stream — labels cost_updated like the CLI parser does. */
+  private observedModel: string | undefined;
+  /** Effective model for this run (`input.model ?? cfg.model`) — the cost-label
+   * fallback, mirroring how {@link run} resolves the model for the SDK query. */
+  private effectiveModel: string | undefined;
+
+  constructor(private readonly cfg: SdkRunnerConfig = {}) {}
+
+  /** Last session id observed — the handle for {@link resume} (cross-restart steering). */
+  get sessionId(): string | undefined {
+    return this.capturedSessionId;
+  }
+
+  /**
+   * Full captured stderr. The worker folds this into the thrown error so the shared
+   * `classifyRunError` catch reads the API-error signal exactly as it does for the CLI.
+   */
+  get capturedStderrText(): string {
+    return this.capturedStderr;
+  }
+
+  start(input: AgentRunInput): AsyncIterable<AgentRunEventDraft> {
+    return this.run(input);
+  }
+
+  resume(input: ResumeInput): AsyncIterable<AgentRunEventDraft> {
+    return this.run(input, input.resumeSessionId);
+  }
+
+  /**
+   * Queue a human message mid-run. The worker currently steers via stop→resume (queue
+   * -and-resume, same as the CLI), so true streaming-input injection is not yet wired
+   * here — kept explicit rather than a silent no-op.
+   */
+  async send(_message: UserAgentMessage): Promise<void> {
+    throw new Error(
+      "SdkAgentRunner.send() (streaming-input steering) is not wired; the worker steers via stop→resume",
+    );
+  }
+
+  /**
+   * Hard stop. Cooperative `abort()` first (the SDK runs a graceful stdin-EOF + ~2s
+   * grace before force-kill), then escalate on the negative pgid as a belt-and-suspenders
+   * tree-kill so a disowned grandchild can't survive.
+   */
+  async stop(_reason: StopReason): Promise<void> {
+    this.abort?.abort();
+    if (this.child) {
+      await terminateGroup(this.child, {
+        sigintTimeoutMs: STOP_SIGINT_MS,
+        sigtermTimeoutMs: STOP_SIGTERM_MS,
+      });
+    }
+    // Belt-and-suspenders: terminateGroup early-returns once the leader has
+    // exited, so sweep the group by the recorded pgid to catch any survivor
+    // that left the leader behind (the run()'s finally also covers this).
+    reapGroup(this.leaderPid);
+  }
+
+  private async *run(
+    input: AgentRunInput,
+    resumeSessionId?: string,
+  ): AsyncIterable<AgentRunEventDraft> {
+    this.abort = new AbortController();
+    this.capturedStderr = "";
+    this.child = null;
+    this.leaderPid = undefined;
+    this.toolNames.clear();
+    this.observedModel = undefined;
+    // Same resolution the SDK query uses below (options.model = input.model ??
+    // cfg.model), so cost_updated.modelName labels correctly even when the
+    // caller supplies the model via input rather than the runner config.
+    this.effectiveModel = input.model ?? this.cfg.model;
+
+    yield {
+      kind: "run_started",
+      source: "system",
+      payload: { runner: "sdk", model: input.model },
+    };
+
+    const allowed = this.cfg.allowedTools ?? SDK_ALLOWED_TOOLS;
+    // Tool gating = faithful CLI parity. The daemon's CLI path runs `claude -p`
+    // with `--allowedTools` and NO `--permission-mode`, so a tool outside the
+    // allowlist (other built-ins AND any other locally-configured MCP server) is
+    // denied, headless, with no prompt. `permissionMode: "dontAsk"` reproduces
+    // exactly that — "don't prompt; deny if not pre-approved" — with `allowedTools`
+    // (incl. the `mcp__harmony__*` glob) as the pre-approved set. This gates MCP
+    // tools too, so a read-only planning pass can't reach a non-harmony MCP server.
+    // (`bypassPermissions` would skip ALL checks — strictly more permissive than
+    // the CLI — so it is deliberately NOT used.) `tools` additionally trims the
+    // built-in set from the model's context as defense-in-depth; MCP/wildcard
+    // entries are governed by mcpServers + the dontAsk allowlist, not `tools`.
+    const builtinTools = allowed.filter(
+      (t) => !t.startsWith("mcp__") && !t.includes("*"),
+    );
+
+    const options: Options = {
+      cwd: input.cwd,
+      model: input.model ?? this.cfg.model,
+      // Pre-approved allowlist — under dontAsk this is the authoritative gate
+      // for both built-in and MCP tools.
+      allowedTools: allowed,
+      // Denylist (stage runs, #576): wins over the allow-wildcard, so the
+      // daemon-owned session/move tools are removed even though `mcp__harmony__*`
+      // is allowed. Omitted entirely when unset (generic runs).
+      ...(this.cfg.disallowedTools && this.cfg.disallowedTools.length > 0
+        ? { disallowedTools: this.cfg.disallowedTools }
+        : {}),
+      tools: builtinTools,
+      permissionMode: "dontAsk",
+      maxTurns: this.cfg.maxTurns,
+      abortController: this.abort,
+      ...(resumeSessionId ? { resume: resumeSessionId } : {}),
+      ...(this.cfg.maxBudgetUsd ? { maxBudgetUsd: this.cfg.maxBudgetUsd } : {}),
+      ...(this.cfg.settingSources
+        ? { settingSources: this.cfg.settingSources }
+        : {}),
+      ...(this.cfg.mcpServers ? { mcpServers: this.cfg.mcpServers } : {}),
+      ...(this.cfg.strictMcpConfig ? { strictMcpConfig: true } : {}),
+      stderr: (data) => {
+        this.capturedStderr += data;
+      },
+      // Tree-kill escape hatch (requirement #2). Inject the daemon's own
+      // process-group leader so signalling the negative pgid reaps grandchildren.
+      spawnClaudeCodeProcess: (spawnOpts) => this.spawn(spawnOpts),
+    };
+
+    try {
+      const q = query({ prompt: input.prompt, options }) as AsyncGenerator<
+        SDKMessage,
+        void
+      >;
+      // A non-success `result` subtype (error_max_turns / error_max_budget_usd)
+      // or a typed assistant error surfaces as an `error` draft mid-stream rather
+      // than throwing, so the terminal status must reflect it — otherwise the
+      // stream would self-contradict (error followed by `completed`).
+      let failureReason: string | null = null;
+      for await (const msg of q) {
+        for (const ev of this.mapMessage(msg)) {
+          if (ev.kind === "error") {
+            failureReason = ev.payload.errorKind ?? "crash";
+          }
+          yield ev;
+        }
+      }
+      yield {
+        kind: "run_finished",
+        source: "system",
+        payload: failureReason
+          ? { status: "failed", failureReason }
+          : { status: "completed" },
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // Fold captured stderr in so classifyRunError reads the API signal,
+      // exactly as the worker does for the CLI.
+      const cls = classifyRunError(`${message}\n${this.capturedStderr}`);
+      yield {
+        kind: "error",
+        source: "system",
+        payload: {
+          message,
+          errorKind: cls.kind,
+          retryable: cls.kind !== "auth" && cls.kind !== null,
+        },
+      };
+      yield {
+        kind: "run_finished",
+        source: "system",
+        payload: { status: "failed", failureReason: cls.kind ?? "crash" },
+      };
+    } finally {
+      // Reap detached/backgrounded grandchildren on EVERY run end — not just an
+      // explicit stop(). A run that finishes on its own (maxTurns, completion)
+      // otherwise leaks them, since the SDK only exits the Claude child and
+      // nothing signals the group (card #436).
+      reapGroup(this.leaderPid);
+    }
+  }
+
+  /**
+   * Spawn the Claude Code child as a process-group leader (negative-pgid
+   * tree-kill), with {@link SdkRunnerConfig.stripEnvKeys} removed from its
+   * environment.
+   *
+   * The strip is a DELETE inside `spawnInGroup`, not a narrowing of the env
+   * passed here: `spawnOpts.env` comes from the SDK and derives from the
+   * daemon's `process.env`, and `spawnInGroup` merges `process.env` again on
+   * top of whatever it receives. Passing a smaller object would therefore strip
+   * nothing.
+   */
+  private spawn(spawnOpts: SpawnOptions): SpawnedProcess {
+    const child = spawnInGroup(spawnOpts.command, spawnOpts.args, {
+      cwd: spawnOpts.cwd,
+      env: spawnOpts.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      ...(this.cfg.stripEnvKeys ? { stripEnvKeys: this.cfg.stripEnvKeys } : {}),
+    });
+    this.child = child;
+    this.leaderPid = child.pid; // record pgid for the post-exit group sweep
+    // `SpawnedProcess` exposes no stderr, so the SDK's own `stderr` Options sink
+    // never fires for a custom spawn. We MUST drain child.stderr ourselves: an
+    // unread pipe fills (~64KB) and blocks the subprocess until the watchdog
+    // kills it. Draining here also restores stderr capture for the auth/rate-limit
+    // classification path that error recovery depends on.
+    child.stderr?.on("data", (d: Buffer) => {
+      this.capturedStderr += d.toString();
+    });
+    this.cfg.onSpawn?.(child);
+    // Adapt ChildProcess → SpawnedProcess. Override kill() to signal the whole
+    // group (negative pid) instead of just the leader.
+    return {
+      stdin: child.stdin!,
+      stdout: child.stdout!,
+      get killed() {
+        return child.killed;
+      },
+      get exitCode() {
+        return child.exitCode;
+      },
+      kill: (signal: NodeJS.Signals) => {
+        if (!child.pid) return false;
+        try {
+          process.kill(-child.pid, signal);
+          return true;
+        } catch {
+          return child.kill(signal);
+        }
+      },
+      on: (event, listener) => child.on(event, listener as never),
+      once: (event, listener) => child.once(event, listener as never),
+      off: (event, listener) => child.off(event, listener as never),
+    } as SpawnedProcess;
+  }
+
+  /** Map one SDKMessage to zero or more AgentRunEventDrafts. */
+  private *mapMessage(msg: SDKMessage): Generator<AgentRunEventDraft> {
+    // Capture session id from any message that carries it (for resume()).
+    const sid = (msg as { session_id?: string }).session_id;
+    if (sid && !this.capturedSessionId) this.capturedSessionId = sid;
+
+    // Capture the model off any frame that carries it (the assistant frame does),
+    // so cost_updated can be labelled like the CLI parser's observedModel.
+    const model =
+      (msg as { message?: { model?: string } }).message?.model ??
+      (msg as { model?: string }).model;
+    if (typeof model === "string" && !this.observedModel) {
+      this.observedModel = model;
+    }
+
+    switch (msg.type) {
+      case "assistant": {
+        const am = msg as { message?: { content?: unknown[] }; error?: string };
+        // Typed error on the assistant frame — no regex needed.
+        if (am.error) {
+          yield {
+            kind: "error",
+            source: "system",
+            payload: {
+              message: `assistant error: ${am.error}`,
+              errorKind: mapSdkErrorKind(am.error),
+            },
+          };
+        }
+        const blocks = am.message?.content;
+        if (Array.isArray(blocks)) {
+          for (const b of blocks as Array<{
+            type?: string;
+            text?: string;
+            name?: string;
+            id?: string;
+            input?: unknown;
+          }>) {
+            if (b.type === "text" && typeof b.text === "string") {
+              const text = b.text.trim();
+              if (text) {
+                yield {
+                  kind: "assistant_text",
+                  source: "agent",
+                  payload: { text: text.slice(0, MAX_TEXT_LEN) },
+                };
+              }
+            } else if (b.type === "tool_use" && typeof b.name === "string") {
+              // Remember the name so the matching tool_result can resolve it.
+              if (typeof b.id === "string") this.toolNames.set(b.id, b.name);
+              yield {
+                kind: "tool_started",
+                source: "agent",
+                payload: { toolName: b.name, toolUseId: b.id, input: b.input },
+              };
+            }
+          }
+        }
+        break;
+      }
+      case "user": {
+        // tool_result blocks land on user frames in the SDK stream.
+        const um = msg as { message?: { content?: unknown[] } };
+        const blocks = um.message?.content;
+        if (Array.isArray(blocks)) {
+          for (const b of blocks as Array<{
+            type?: string;
+            tool_use_id?: string;
+            content?: unknown;
+            is_error?: boolean;
+          }>) {
+            if (b.type === "tool_result" && typeof b.tool_use_id === "string") {
+              // Resolve the name from the matching tool_use (CLI parity); the
+              // SDK tool_result block itself carries only the id. Drop the entry
+              // after resolving so the map stays flat across a run, exactly like
+              // the CLI StreamParser's `toolNames.delete` on tool_result.
+              const toolName = this.toolNames.get(b.tool_use_id) ?? "";
+              this.toolNames.delete(b.tool_use_id);
+              yield {
+                kind: "tool_ended",
+                source: "agent",
+                payload: {
+                  toolName,
+                  toolUseId: b.tool_use_id,
+                  output: normalize(b.content)?.slice(0, MAX_OUTPUT_LEN),
+                  isError: b.is_error,
+                },
+              };
+            }
+          }
+        }
+        break;
+      }
+      case "result": {
+        const r = msg as {
+          subtype?: string;
+          total_cost_usd?: number;
+          num_turns?: number;
+          duration_ms?: number;
+          usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_creation_input_tokens?: number;
+            cache_read_input_tokens?: number;
+          };
+          errors?: string[];
+        };
+        if (typeof r.total_cost_usd === "number") {
+          yield {
+            kind: "cost_updated",
+            source: "agent",
+            payload: {
+              totalCostUsd: r.total_cost_usd,
+              inputTokens: r.usage?.input_tokens ?? 0,
+              outputTokens: r.usage?.output_tokens ?? 0,
+              cacheCreationInputTokens:
+                r.usage?.cache_creation_input_tokens ?? 0,
+              cacheReadInputTokens: r.usage?.cache_read_input_tokens ?? 0,
+              numTurns: r.num_turns ?? 0,
+              durationMs: r.duration_ms,
+              // Label the cost like the CLI parser does (its CostUpdate carries
+              // modelName). The result frame has no model, so use the model seen
+              // on the stream, falling back to the effective run model
+              // (input.model ?? cfg.model) — not cfg.model alone, which would
+              // drop the label when the caller passes the model via input.
+              modelName: this.observedModel ?? this.effectiveModel,
+            },
+          };
+        }
+        // Surface a result-level error subtype (max_turns / max_budget / exec error).
+        if (r.subtype && r.subtype !== "success") {
+          const joined = (r.errors ?? []).join("\n");
+          const cls = classifyRunError(
+            `${r.subtype}\n${joined}\n${this.capturedStderr}`,
+          );
+          yield {
+            kind: "error",
+            source: "system",
+            payload: {
+              message: `result ${r.subtype}: ${joined || "(no detail)"}`,
+              errorKind: cls.kind,
+              retryable: cls.kind !== "auth" && cls.kind !== null,
+            },
+          };
+        }
+        break;
+      }
+      // system / partial / status / etc. — ignored (matches CLI parser scope).
+    }
+  }
+}
+
+/** Flatten an SDK tool_result `content` (string | block[] | object) to a string. */
+function normalize(raw: unknown): string | undefined {
+  if (raw == null) return undefined;
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw)) {
+    const parts: string[] = [];
+    for (const b of raw) {
+      if (
+        b &&
+        typeof b === "object" &&
+        "text" in b &&
+        typeof (b as { text: unknown }).text === "string"
+      ) {
+        parts.push((b as { text: string }).text);
+      }
+    }
+    return parts.length ? parts.join("") : JSON.stringify(raw);
+  }
+  try {
+    return JSON.stringify(raw);
+  } catch {
+    return String(raw);
+  }
+}