gstack/test/helpers/agent-sdk-runner.ts

/**
 * Claude Agent SDK wrapper for the overlay-efficacy harness.
 *
 * This sits alongside session-runner.ts (which drives `claude -p` as a
 * subprocess) but runs the model via the published @anthropic-ai/claude-agent-sdk
 * instead. The SDK exposes the same harness primitives Claude Code itself uses,
 * so overlay-driven behavior change is measured against a closer approximation
 * of real Claude Code than the `claude -p` subprocess path provides.
 *
 * Explicit design rules (from plan review):
 *   - Use SDK-exported SDKMessage types. No `| unknown` union collapse.
 *   - Permission surface is explicit: bypassPermissions + settingSources:[] +
 *     disallowedTools inverse. Without these, the SDK inherits user settings,
 *     project .claude/, and local hooks, and arms are no longer comparable.
 *   - Binary pinning via pathToClaudeCodeExecutable. Resolve with `which claude`
 *     at setup time; the SDK would otherwise use its bundled binary.
 *   - 3-shape rate-limit detection: thrown error, result-message error subtype,
 *     mid-stream SDKRateLimitEvent. All three recover on retry.
 *   - On retry, caller resets workspace via a setupWorkspace callback so
 *     partial Bash side-effects don't contaminate the next attempt.
 *   - Process-level semaphore caps concurrent queries across all callers in
 *     the same bun-test process. Composes with bun's own --concurrent flag.
 */

import {
  query,
  type SDKMessage,
  type SDKAssistantMessage,
  type SDKResultMessage,
  type SDKSystemMessage,
  type PermissionMode,
  type SettingSource,
  type Options,
  type CanUseTool,
} from '@anthropic-ai/claude-agent-sdk';
import * as fs from 'fs';
import * as path from 'path';
import { resolveClaudeBinary as resolveClaudeBinaryShared } from '../../lib/claude-bin';
import { resolveEvalModel } from '../../lib/eval-model';
import { streamedUsageCostUsd } from '../../lib/pricing';
import { sdkSystemPrompt, type SystemPromptOption } from './sdk-system-prompt';
import { SessionObserver, appendSessionLedger, sessionKey, type SessionEnd } from './session-ledger';
import { hermeticChildEnv } from './hermetic-env';
import type { SkillTestResult } from './session-runner';

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface AgentSdkResult {
  /** Full raw event stream for forensic recovery. */
  events: SDKMessage[];
  /** Assistant-typed subset, in order. */
  assistantTurns: SDKAssistantMessage[];
  /** Flat tool-call list, in order of emission. */
  toolCalls: Array<{ tool: string; input: unknown; output: string }>;
  /** Concatenated assistant text, newline-joined. */
  output: string;
  /** 'success' | 'error_during_execution' | 'error_max_turns' | ... */
  exitReason: string;
  turnsUsed: number;
  durationMs: number;
  firstResponseMs: number;
  maxInterTurnMs: number;
  costUsd: number;
  model: string;
  sdkVersion: string;
  /** claude_code_version from the SDK's system/init event (authoritative). */
  sdkClaudeCodeVersion: string;
  /** Path to the claude binary we pinned. */
  resolvedBinaryPath: string;
  /** browse-error pattern scan for SkillTestResult parity. Always empty here. */
  browseErrors: string[];
}

/** Signature matching `query()` from the SDK. DI hook for unit tests. */
export type QueryProvider = typeof query;

export type { SystemPromptOption };

export interface RunAgentSdkOptions {
  /**
   * System prompt surface (test/helpers/sdk-system-prompt.ts).
   *   - { type:'preset', preset:'claude_code' } -> use Claude Code default
   *   - { type:'preset', preset:'claude_code', append: "..." } -> default + append
   *   - { type:'sdk-default', reason } -> omit; the SDK runs its bare stub
   *   - { type:'custom', text, reason } -> REPLACE default with given text
   *
   * For overlay-efficacy measurement, the preset+append pattern is the right
   * one: it measures "does adding overlay text to the REAL Claude Code system
   * prompt change behavior" rather than "does the overlay alone (stripped of
   * base scaffolding) change behavior".
   */
  systemPrompt: SystemPromptOption;
  userPrompt: string;
  workingDirectory: string;
  model?: string;
  maxTurns?: number;
  allowedTools?: string[];
  disallowedTools?: string[];
  permissionMode?: PermissionMode;
  settingSources?: SettingSource[];
  env?: Record<string, string>;
  pathToClaudeCodeExecutable?: string;
  testName?: string;
  runId?: string;
  fixtureId?: string;
  queryProvider?: QueryProvider;
  /** Cancel queueing, SDK work and retries under the caller's case deadline. */
  signal?: AbortSignal;
  onAdmission?: () => void;
  /** Max 429 retries per call. Default 3. */
  maxRetries?: number;
  /**
   * Caller provides this when retry should reset the workspace. The harness
   * invokes it with a fresh dir after a rate-limit failure. When omitted,
   * retries reuse the original workingDirectory (fine for read-only tests).
   */
  onRetry?: (freshDir: string) => void;
  /**
   * Optional canUseTool callback. When supplied, the harness flips
   * permissionMode from 'bypassPermissions' to 'default' so the SDK actually
   * routes tool-use approval decisions through the callback. Without this
   * flip, bypassPermissions short-circuits the callback and tests that want
   * to assert on AskUserQuestion content silently pass without asserting.
   *
   * Callback contract matches the SDK: fires on every tool-use approval
   * request and on AskUserQuestion invocations. For non-AskUserQuestion
   * tools that tests don't care about, use `passThroughNonAskUserQuestion`
   * to auto-allow them.
   */
  canUseTool?: CanUseTool;
  /** A custom queryProvider that drops `stream_event` rows from its own evidence opts in to partial messages. */
  streamLiveness?: boolean;
  /** The session timeout the caller armed (a getter when armed at admission), for the session ledger. */
  sessionBudgetMs?: number | (() => number | undefined);
}

/**
 * Pass-through helper: auto-allows any tool_use that isn't AskUserQuestion.
 * Most plan-mode handshake tests only care about the handshake AskUserQuestion;
 * every other tool (Read, Grep, Bash, Write, Edit, ExitPlanMode) should just
 * run. Compose with a test-specific AskUserQuestion handler:
 *
 *   canUseTool: async (toolName, input, options) => {
 *     if (toolName === 'AskUserQuestion') {
 *       // custom assertions + canned answer
 *       return { behavior: 'allow', updatedInput: { questions: input.questions, answers: {...} } };
 *     }
 *     return passThroughNonAskUserQuestion(toolName, input);
 *   }
 */
export function passThroughNonAskUserQuestion(
  toolName: string,
  input: Record<string, unknown>,
): { behavior: 'allow'; updatedInput: Record<string, unknown> } {
  // SDK requires an allow response to include updatedInput — pass the original
  // input through unchanged so the tool runs as the model intended.
  void toolName;
  return { behavior: 'allow', updatedInput: input };
}

export class RateLimitExhaustedError extends Error {
  readonly attempts: number;
  constructor(attempts: number, cause?: unknown) {
    super(`rate limit exhausted after ${attempts} attempts`);
    this.name = 'RateLimitExhaustedError';
    this.attempts = attempts;
    if (cause !== undefined) (this as { cause?: unknown }).cause = cause;
  }
}

// ---------------------------------------------------------------------------
// Process-level semaphore for API concurrency
// ---------------------------------------------------------------------------

/**
 * Bounded token bucket. Shared across all runAgentSdkTest calls in this
 * process so that bun's --concurrent flag does not compound with in-test
 * concurrency to blow past Anthropic's rate limits.
 *
 * Default capacity 3. Override via GSTACK_SDK_MAX_CONCURRENCY env var.
 */
class Semaphore {
  private available: number;
  private readonly queue: Array<() => void> = [];
  constructor(capacity: number) {
    this.available = capacity;
  }
  async acquire(signal?: AbortSignal): Promise<void> {
    signal?.throwIfAborted();
    if (this.available > 0) {
      this.available--;
      return;
    }
    await new Promise<void>((resolve, reject) => {
      const grant = () => { signal?.removeEventListener('abort', abort); resolve(); };
      const abort = () => {
        const index = this.queue.indexOf(grant);
        if (index >= 0) this.queue.splice(index, 1);
        reject(signal?.reason ?? new Error('SDK query aborted while queued'));
      };
      this.queue.push(grant);
      signal?.addEventListener('abort', abort, { once: true });
    });
  }
  release(): void {
    const next = this.queue.shift();
    if (next) {
      next();
    } else {
      this.available++;
    }
  }
  /** For tests. Returns tokens currently in-flight. */
  inFlight(): number {
    // Not introspectable from outside without tracking; approximate.
    return this.queue.length;
  }
}

const DEFAULT_SDK_CONCURRENCY = Number(process.env.GSTACK_SDK_MAX_CONCURRENCY ?? 3);
let _apiSemaphore: Semaphore | null = null;
function getApiSemaphore(): Semaphore {
  if (!_apiSemaphore) _apiSemaphore = new Semaphore(DEFAULT_SDK_CONCURRENCY);
  return _apiSemaphore;
}

/** Test-only. Resets the process-level semaphore. */
export function __resetSemaphoreForTests(capacity: number): void {
  _apiSemaphore = new Semaphore(capacity);
}

// ---------------------------------------------------------------------------
// Rate-limit detection
// ---------------------------------------------------------------------------

/** True if `err` looks like a rate-limit thrown from the SDK. */
export function isRateLimitThrown(err: unknown): boolean {
  if (!err || typeof err !== 'object') return false;
  const msg = (err as { message?: string }).message ?? '';
  const name = (err as { name?: string }).name ?? '';
  const status = (err as { status?: number }).status;
  return (
    status === 429 ||
    /rate.?limit|429|too many requests/i.test(msg) ||
    /RateLimit/i.test(name)
  );
}

/** True if a SDKResultMessage is a rate-limit-shaped error. */
export function isRateLimitResult(msg: SDKMessage): boolean {
  if (msg.type !== 'result') return false;
  const r = msg as SDKResultMessage;
  if (r.subtype === 'success') return false;
  // subtype === 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | ...
  if (r.subtype !== 'error_during_execution') return false;
  const errs = (r as { errors?: string[] }).errors ?? [];
  return errs.some((e) => /rate.?limit|429|too many requests/i.test(e));
}

/** True if mid-stream SDKRateLimitEvent indicates a blocking rate-limit. */
export function isRateLimitEvent(msg: SDKMessage): boolean {
  if (msg.type !== 'rate_limit_event') return false;
  const info = (msg as { rate_limit_info?: { status?: string } }).rate_limit_info;
  return info?.status === 'rejected';
}

/**
 * True if `err` is the SDK's "max turns reached" throw. Some SDK versions
 * raise this as an exception from the generator instead of emitting a
 * result message with subtype='error_max_turns'. We treat it as terminal-
 * but-recoverable: record what we collected and continue, rather than
 * failing the whole run.
 */
export function isMaxTurnsError(err: unknown): boolean {
  if (!err || typeof err !== 'object') return false;
  const msg = (err as { message?: string }).message ?? '';
  return /reached maximum number of turns|max.?turns/i.test(msg);
}

// ---------------------------------------------------------------------------
// Version resolution (cached)
// ---------------------------------------------------------------------------

let _sdkVersionCache: string | null = null;
function resolveSdkVersion(): string {
  if (_sdkVersionCache) return _sdkVersionCache;
  try {
    const pkgPath = require.resolve('@anthropic-ai/claude-agent-sdk/package.json');
    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version?: string };
    _sdkVersionCache = pkg.version ?? 'unknown';
  } catch {
    _sdkVersionCache = 'unknown';
  }
  return _sdkVersionCache;
}

export function resolveClaudeBinary(): string | null {
  return resolveClaudeBinaryShared();
}

// ---------------------------------------------------------------------------
// Main runner
// ---------------------------------------------------------------------------

/**
 * Execute a single SDK query with retries. Returns a typed result.
 *
 * The retry loop treats 429 as recoverable and any other error as fatal.
 * Exponential backoff: 1s, 2s, 4s. After maxRetries failures, throws
 * RateLimitExhaustedError so the caller can decide what to do with the run.
 */
export async function runAgentSdkTest(
  opts: RunAgentSdkOptions,
): Promise<AgentSdkResult> {
  const sem = getApiSemaphore();
  const systemPrompt = sdkSystemPrompt(opts.systemPrompt);
  const maxRetries = opts.maxRetries ?? 3;
  const queryImpl: QueryProvider = opts.queryProvider ?? query;
  // Default matches session-runner's frontier eval fallback. Tests that need a
  // cheaper or historical model pin it via opts.model or EVALS_MODEL.
  const model = opts.model ?? process.env.EVALS_MODEL ?? resolveEvalModel('capture');

  // NOTE on env: the SDK child gets the COMPLETE hermetic env (allowlist
  // scrub + ANTHROPIC_API_KEY + hermetic CLAUDE_CONFIG_DIR/GSTACK_HOME), with
  // per-test opts.env merging last. The historical "passing env: breaks SDK
  // auth" failure (old CLAUDE.md warning) was partial-env replacement —
  // Options.env REPLACES the child's entire environment, so an object without
  // the key killed auth. A complete env is safe (validated 2026-06-12 via
  // query() with hermeticChildEnv(): success, real cost, Bash tool working).
  // Do not mutate process.env ambiently here (it would leak into later
  // interactive-path tests in the same Bun process — Codex review finding);
  // ambient ANTHROPIC_API_KEY mutation by tests still works because the
  // builder reads process.env at call time.

  let attempt = 0;
  let lastErr: unknown = null;
  let admitted = false;

  while (attempt <= maxRetries) {
    await sem.acquire(opts.signal);
    const startMs = Date.now();
    const startMono = performance.now();
    const startedAt = new Date().toISOString();
    const observer = new SessionObserver(startMono);
    let recorded = false;
    /** One ledger row per attempt; an abort at the armed budget is a session timeout. */
    const recordSession = (fallback: SessionEnd) => {
      if (recorded) return;
      recorded = true;
      const elapsed = performance.now() - startMono;
      const budget = typeof opts.sessionBudgetMs === 'function' ? opts.sessionBudgetMs() : opts.sessionBudgetMs;
      const aborted = controller.signal.aborted || opts.signal?.aborted === true;
      const structured = observer.verdict();
      const streamed = observer.billed ? undefined : streamedUsageCostUsd(assistantTurns, model);
      const end: SessionEnd = aborted ? (budget !== undefined && elapsed + 1000 >= budget ? 'session_timeout' : 'aborted') : structured?.end ?? fallback;
      appendSessionLedger({ key: sessionKey('agent-sdk', opts.testName), ...(opts.testName ? { test_name: opts.testName } : {}), runner: 'agent-sdk',
        started_at: startedAt, ...(budget !== undefined ? { budget_ms: budget } : {}), elapsed_ms: elapsed, end,
        ...(end === 'session_timeout' ? { evidence: `armed ${budget}ms session timeout fired` } : structured && !aborted ? { evidence: structured.evidence } : {}),
        liveness: observer.summary(performance.now()), billed: observer.billed, ...(streamed !== undefined ? { streamed_cost_usd: streamed } : {}) });
    };
    const controller = new AbortController();
    let activeQuery: ReturnType<QueryProvider> | undefined;
    const abort = () => {
      controller.abort(opts.signal?.reason);
      try { activeQuery?.close(); } catch { /* cancellation remains authoritative */ }
    };
    opts.signal?.addEventListener('abort', abort, { once: true });

    // Hoisted so the max-turns catch branch can synthesize a result from
    // whatever we captured before the SDK threw.
    const events: SDKMessage[] = [];
    const assistantTurns: SDKAssistantMessage[] = [];
    const toolCalls: Array<{ tool: string; input: unknown; output: string }> = [];
    const assistantTextParts: string[] = [];
    let firstResponseMs = 0;
    let lastEventMs = startMs;
    let maxInterTurnMs = 0;
    let systemInitVersion = 'unknown';
    let rateLimited: unknown = null;
    let terminalResult: SDKResultMessage | null = null;
    // A generator can emit its terminal result and then throw. Keep its
    // authoritative usage in both paths, while preserving the caller's outcome.
    const finishResult = (exitReason: string): AgentSdkResult => (recordSession(exitReason === 'success' ? 'completed' : 'error'), {
      events,
      assistantTurns,
      toolCalls,
      output: assistantTextParts.join('\n'),
      exitReason,
      turnsUsed: terminalResult?.num_turns ?? assistantTurns.length,
      durationMs: Date.now() - startMs,
      firstResponseMs,
      maxInterTurnMs,
      costUsd: terminalResult?.total_cost_usd ?? 0, // Unknown only when no usage was returned.
      model,
      sdkVersion: resolveSdkVersion(),
      sdkClaudeCodeVersion: systemInitVersion,
      resolvedBinaryPath: opts.pathToClaudeCodeExecutable ?? 'sdk-default',
      browseErrors: [],
    });

    try {
      opts.signal?.throwIfAborted();
      if (!admitted) {
        admitted = true;
        opts.onAdmission?.();
      }
      // When canUseTool is supplied, the SDK must route tool-use approval
      // decisions through the callback. bypassPermissions short-circuits
      // that. Flip to 'default' mode so canUseTool actually fires. Tests
      // that want AskUserQuestion interception without this flip would
      // silently auto-pass — the exact testability gap D14/D4-eng fix.
      const hasCanUseTool = typeof opts.canUseTool === 'function';
      const resolvedPermissionMode: PermissionMode =
        opts.permissionMode ?? (hasCanUseTool ? 'default' : 'bypassPermissions');

      // When canUseTool is supplied, ensure AskUserQuestion is in the allowed
      // tools list. Without it, Claude can't invoke AskUserQuestion at all
      // and the callback never has a chance to fire on it.
      const baseTools = opts.allowedTools ?? ['Read', 'Glob', 'Grep', 'Bash'];
      const resolvedTools =
        hasCanUseTool && !baseTools.includes('AskUserQuestion')
          ? [...baseTools, 'AskUserQuestion']
          : baseTools;

      const sdkOpts: Options = {
        abortController: controller,
        model,
        cwd: opts.workingDirectory,
        maxTurns: opts.maxTurns ?? 5,
        tools: resolvedTools,
        disallowedTools: opts.disallowedTools,
        allowedTools: resolvedTools,
        permissionMode: resolvedPermissionMode,
        allowDangerouslySkipPermissions: resolvedPermissionMode === 'bypassPermissions',
        settingSources: opts.settingSources ?? [],
        env: hermeticChildEnv(opts.env),
        pathToClaudeCodeExecutable: opts.pathToClaudeCodeExecutable,
        // Liveness only: stream_event rows are observed, never kept in events. A custom
        // queryProvider sees every row first, so it streams them only when it opts in.
        includePartialMessages: !opts.queryProvider || opts.streamLiveness === true,
        ...(hasCanUseTool ? { canUseTool: async (...args: Parameters<CanUseTool>) => {
          observer.permission(1);
          try { return await opts.canUseTool!(...args); } finally { observer.permission(-1); }
        } } : {}),
      };
      Object.assign(sdkOpts, systemPrompt);

      opts.signal?.throwIfAborted();
      const q = queryImpl({
        prompt: opts.userPrompt,
        options: sdkOpts,
      });
      activeQuery = q;
      if (opts.signal?.aborted) abort();
      opts.signal?.throwIfAborted();

      for await (const ev of q) {
        observer.observe(ev, performance.now());
        opts.signal?.throwIfAborted();
        if (ev.type === 'stream_event') continue;
        const now = Date.now();
        if (firstResponseMs === 0) firstResponseMs = now - startMs;
        const interTurn = now - lastEventMs;
        if (interTurn > maxInterTurnMs) maxInterTurnMs = interTurn;
        lastEventMs = now;

        events.push(ev);

        if (ev.type === 'system' && (ev as SDKSystemMessage).subtype === 'init') {
          systemInitVersion =
            (ev as SDKSystemMessage).claude_code_version ?? 'unknown';
        } else if (ev.type === 'assistant') {
          const am = ev as SDKAssistantMessage;
          assistantTurns.push(am);
          const content = am.message?.content;
          if (Array.isArray(content)) {
            for (const block of content as Array<
              | { type: 'text'; text?: string }
              | { type: 'tool_use'; name?: string; input?: unknown }
              | { type: string }
            >) {
              if (block.type === 'text') {
                const t = (block as { text?: string }).text;
                if (t) assistantTextParts.push(t);
              } else if (block.type === 'tool_use') {
                const tb = block as { name?: string; input?: unknown };
                toolCalls.push({
                  tool: tb.name ?? 'unknown',
                  input: tb.input ?? {},
                  output: '',
                });
              }
            }
          }
        } else if (isRateLimitEvent(ev)) {
          rateLimited = new Error(
            `mid-stream rate limit: ${JSON.stringify(
              (ev as { rate_limit_info?: unknown }).rate_limit_info,
            )}`,
          );
        } else if (ev.type === 'result') {
          terminalResult = ev as SDKResultMessage;
          if (isRateLimitResult(ev)) {
            rateLimited = new Error(
              `result-message rate limit: ${((ev as { errors?: string[] }).errors ?? []).join('; ')}`,
            );
          }
        }
      }

      opts.signal?.throwIfAborted();

      if (rateLimited) {
        throw rateLimited;
      }
      if (!terminalResult) {
        throw new Error('query stream ended without a result event');
      }

      return finishResult(terminalResult.subtype ?? 'unknown');
    } catch (err) {
      lastErr = err;
      if (!isMaxTurnsError(err)) recordSession('error');
      opts.signal?.throwIfAborted();

      // Some SDK versions throw max-turns after emitting a terminal result;
      // others throw without one. Preserve captured usage when present and
      // keep error_max_turns even if an earlier terminal claimed success.
      if (isMaxTurnsError(err)) {
        return finishResult('error_max_turns');
      }

      const isRetryable = isRateLimitThrown(err);
      if (!isRetryable || attempt >= maxRetries) {
        if (isRetryable) {
          throw new RateLimitExhaustedError(attempt + 1, err);
        }
        throw err;
      }
      attempt++;
      // backoff: 1s, 2s, 4s
      await new Promise<void>((resolve, reject) => {
        const aborted = () => { clearTimeout(timer); reject(opts.signal?.reason ?? new Error('SDK retry aborted')); };
        const timer = setTimeout(() => { opts.signal?.removeEventListener('abort', aborted); resolve(); }, 1000 * Math.pow(2, attempt - 1));
        opts.signal?.addEventListener('abort', aborted, { once: true });
        if (opts.signal?.aborted) aborted();
      });
      opts.signal?.throwIfAborted();
      // Let caller reset workspace since prior attempt may have partially
      // mutated files via Bash.
      if (opts.onRetry) {
        opts.onRetry(opts.workingDirectory);
      }
    } finally {
      opts.signal?.removeEventListener('abort', abort);
      sem.release();
    }
  }

  throw new RateLimitExhaustedError(attempt + 1, lastErr);
}

// ---------------------------------------------------------------------------
// Legacy shape mapper
// ---------------------------------------------------------------------------

/**
 * Adapt AgentSdkResult to the legacy SkillTestResult shape so helpers that
 * expect the old `claude -p` output (extractToolSummary, etc) work unchanged.
 */
export function toSkillTestResult(r: AgentSdkResult): SkillTestResult {
  // Cost estimate: use SDK's authoritative cost; back-compute chars.
  // session-runner.ts:30 requires inputChars/outputChars/estimatedTokens.
  // These are rough; real consumers of CostEstimate use cost + turns.
  const outputChars = r.output.length;
  const inputChars = 0; // unknown from SDK path; not used for pass/fail
  const estimatedTokens = Math.round((inputChars + outputChars) / 4);

  // Build a flat transcript list mimicking the NDJSON shape:
  // parseNDJSON emits [{ type: 'assistant', message: {...} }, ...].
  // Use the SDK's assistantTurns directly since their shape matches.
  const transcript: unknown[] = r.events.slice();

  return {
    toolCalls: r.toolCalls,
    browseErrors: r.browseErrors,
    exitReason: r.exitReason,
    duration: r.durationMs,
    output: r.output,
    costEstimate: {
      inputChars,
      outputChars,
      estimatedTokens,
      estimatedCost: r.costUsd,
      turnsUsed: r.turnsUsed,
    },
    transcript,
    model: r.model,
    firstResponseMs: r.firstResponseMs,
    maxInterTurnMs: r.maxInterTurnMs,
  };
}

// ---------------------------------------------------------------------------
// Metric helpers (re-exported for fixtures)
// ---------------------------------------------------------------------------

/**
 * Count `tool_use` blocks in the first assistant turn of an SDK result.
 * Returns 0 if there is no first turn or no content array.
 *
 * This is the core "fanout" metric. A turn with N tool_use blocks = N
 * parallel tool invocations.
 */
export function firstTurnParallelism(firstTurn: SDKAssistantMessage | undefined): number {
  if (!firstTurn) return 0;
  const content = firstTurn.message?.content;
  if (!Array.isArray(content)) return 0;
  return (content as Array<{ type: string }>).filter((b) => b.type === 'tool_use').length;
}