@cat-factory/executor-harness 1.132.3 → 1.135.0

package/src/agent.ts

@@ -1,8 +1,6 @@
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { mkdir, mkdtemp, rm } from 'node:fs/promises'
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
 import type {
   AgentInfraSpec,
   AgentJob,
@@ -11,10 +9,13 @@ import type {
   ServiceInfraSpec,
   TestSecretSpec,
 } from './job.js'
+// The preview mode drives the frontend stand-up directly rather than through `manageInfra`:
+// its serve/WireMock children outlive the job on purpose, so it wants no cleanup handle.
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
+import { buildInfraNotes, manageInfra } from './infra-standup.js'
 import { artifactUploadEnv } from './artifact-upload.js'
 import { configurePackageRegistries } from './package-registries.js'
-import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js'
+import { registerKnownSecrets } from './redact.js'
 import {
   cloneRepo,
   commitAll,
@@ -71,158 +72,6 @@ import { log, type Logger } from './logger.js'
 // general `if (job.someFlag)` dispatch; anything that doesn't need a checkout belongs in
 // backend pre/post-ops. See backend/docs/custom-agents.md.
 
-const exec = promisify(execFile)
-
-/**
- * Bring the service's docker-compose dependencies up (local infra only). Best-effort:
- * runs `docker compose -f <path> up -d --wait` in the checkout. A missing Docker daemon
- * or a compose failure is logged and surfaced to the agent (as a prompt note) rather
- * than failing the job — the agent can still run unit-level tests and report what it
- * could. A no-op for ephemeral / no-infra / no-compose-path runs.
- *
- * Whether it succeeds or fails, the (redacted, bounded) command output is captured into a
- * {@link InfraSetupRecord} returned alongside the prompt `note`, so the backend can surface
- * the in-container dependency stand-up logs on the Tester step — the failure-class artifact
- * the orchestrator-side provisioning logs can't see.
- */
-async function standUpInfra(
-  dir: string,
-  infra: ServiceInfraSpec,
-  signal: AbortSignal | undefined,
-  logger: Logger,
-): Promise<{ started: boolean; note?: string; record?: InfraSetupRecord }> {
-  if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) {
-    return { started: false }
-  }
-  const startedAt = Date.now()
-  try {
-    logger.info('agent(explore): standing up infra', { composePath: infra.composePath })
-    // Raise maxBuffer well above the 1MB default so a chatty compose stand-up can't fail the
-    // (best-effort) infra step with ENOBUFS; the captured output is tail-bounded on storage.
-    const { stdout, stderr } = await exec(
-      'docker',
-      ['compose', '-f', infra.composePath, 'up', '-d', '--wait'],
-      { cwd: dir, signal, timeout: 5 * 60_000, maxBuffer: 16 * 1024 * 1024 },
-    )
-    const logs = captureRedactedOutput(stdout, stderr)
-    return {
-      started: true,
-      record: {
-        started: true,
-        composePath: infra.composePath,
-        at: Date.now(),
-        durationMs: Date.now() - startedAt,
-        ...(logs ? { logs } : {}),
-      },
-    }
-  } catch (err) {
-    const note = err instanceof Error ? err.message : String(err)
-    logger.warn('agent(explore): infra stand-up failed', { error: note })
-    // `execFile` rejections carry the partial stdout/stderr on the error object — capture them
-    // so the stored logs explain the failure (a port clash, a pull-auth error, an exited
-    // dependency), not just the one-line exit message.
-    const e = err as { stdout?: unknown; stderr?: unknown }
-    const logs = captureRedactedOutput(e.stdout, e.stderr)
-    return {
-      started: false,
-      note,
-      record: {
-        started: false,
-        composePath: infra.composePath,
-        at: Date.now(),
-        durationMs: Date.now() - startedAt,
-        error: redactSecrets(note),
-        ...(logs ? { logs } : {}),
-      },
-    }
-  }
-}
-
-/**
- * Stand the run's infra up and return a single cleanup handle, dispatching on the spec's
- * `kind`: the frontend UI-test flow (`kind: 'frontend'`) builds/serves the app + WireMock as
- * processes (torn down by killing them); the default backend-service flow stands the
- * docker-compose stack up (torn down with `docker compose down`). Unifying the two here keeps
- * `runExploreMode` free of the branch and guarantees the matching teardown runs in its finally.
- *
- * `dir` is the clone ROOT; `workDir` is the service subtree (equal to `dir` when the run is not
- * monorepo-scoped). The docker-compose stand-up runs at the root (its `composePath` is
- * repo-relative), but the FRONTEND stand-up runs in `workDir`: a monorepo frontend's
- * `package.json` / `outputDir` / `mocks/` all live under the service subtree, so installing,
- * building, serving and seeding WireMock from the root would target the wrong directory.
- */
-async function manageInfra(
-  dir: string,
-  workDir: string,
-  infra: AgentInfraSpec,
-  opts: RunOptions,
-  logger: Logger,
-): Promise<{
-  note?: string
-  serveUrl?: string
-  record?: InfraSetupRecord
-  cleanup: () => Promise<void>
-}> {
-  if (infra.kind === 'frontend') {
-    // `onActivity` feeds the inactivity watchdog through the frontend build/serve stand-up,
-    // which (unlike docker-compose's 5-min-capped `up`) can run past the inactivity window.
-    // Runs in `workDir` so a monorepo frontend builds/serves from its own package subtree.
-    const fe = await standUpFrontend(workDir, infra, opts, logger)
-    return {
-      ...(fe.note ? { note: fe.note } : {}),
-      ...(fe.serveUrl ? { serveUrl: fe.serveUrl } : {}),
-      record: fe.record,
-      cleanup: () => tearDownFrontend(fe.processes, logger),
-    }
-  }
-  const standUp = await standUpInfra(dir, infra, opts.signal, logger)
-  return {
-    ...(standUp.note ? { note: standUp.note } : {}),
-    ...(standUp.record ? { record: standUp.record } : {}),
-    cleanup: () => tearDownInfra(dir, infra),
-  }
-}
-
-/**
- * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
- * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
- * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
- * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
- * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
- */
-export function buildInfraNotes(managed: { note?: string; serveUrl?: string }): string[] {
-  const notes: string[] = []
-  if (managed.note) {
-    notes.push(
-      `standing the infra up reported a problem (${managed.note}). Test what you can and ` +
-        `flag any dependency-related gaps as concerns.`,
-    )
-  }
-  if (managed.serveUrl) {
-    notes.push(
-      `The frontend under test is built and served at ${managed.serveUrl}, with its other ` +
-        `backend upstreams handled by WireMock. Drive your UI tests against ${managed.serveUrl}. ` +
-        `If a call to a live backend fails with a CORS / cross-origin error, that is an infra ` +
-        `gap (the backend must allow the ${managed.serveUrl} origin), not an app defect — flag ` +
-        `it as a concern rather than a failing test.`,
-    )
-  }
-  return notes
-}
-
-/** Tear the docker-compose dependencies down (best-effort; a no-op when none were started). */
-async function tearDownInfra(dir: string, infra: ServiceInfraSpec): Promise<void> {
-  if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) return
-  try {
-    await exec('docker', ['compose', '-f', infra.composePath, 'down', '-v'], {
-      cwd: dir,
-      timeout: 2 * 60_000,
-    })
-  } catch {
-    // The container is ephemeral and torn down with the run anyway — ignore.
-  }
-}
-
 /**
  * Parse an agent's final reply into the structured JSON `custom`, shared by the explore and
  * coding structured-output paths. With repair enabled (default) a malformed reply gets ONE
@@ -337,9 +186,9 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
 
 /**
  * Layer extra child-process env onto a job's {@link RunOptions}. The agent CLI is spawned with
- * `{...process.env, ...agentEnv}`, so this is how per-job values reach the agent (and the shell
- * tools it spawns) WITHOUT mutating the harness's own `process.env` — which is shared by every
- * concurrent job when the harness runs as a native host process. Empty `env` ⇒ `opts` unchanged.
+ * `agentChildEnv(agentEnv)`, so this is how per-job values reach the agent (and the shell tools it
+ * spawns) WITHOUT mutating the harness's own `process.env` — which is shared by every concurrent
+ * job when the harness runs as a native host process. Empty `env` ⇒ `opts` unchanged.
  */
 function withAgentEnv(opts: RunOptions, env: Record<string, string>): RunOptions {
   if (Object.keys(env).length === 0) return opts
@@ -646,8 +495,6 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             // Read-only: it inspects and reports, making no edits — so the no-progress
             // guard's no-edit bound must not fire on its legitimately edit-free run.
             expectsEdits: false,
-            webToolsGuidance: job.webToolsGuidance,
-            webSearchProxy: job.webSearch,
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
             ...agentCapabilities(job),
@@ -897,8 +744,6 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
         sessionToken: job.sessionToken,
         // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
         expectsEdits: false,
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
         ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
         guardLimits: job.guardLimits,
         ...agentCapabilities(job),
@@ -1019,8 +864,6 @@ export function buildSingleRepoCodingSpec(
     proxyPhasePath: job.proxyPhasePath,
     sessionToken: job.sessionToken,
     commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-    webToolsGuidance: job.webToolsGuidance,
-    webSearchProxy: job.webSearch,
     guardLimits: job.guardLimits,
     ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
     ...(job.streamFollowUps ? { streamFollowUps: true } : {}),

package/src/captured-command.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process'
 import { killChildProcess, spawnDetached } from './process.js'
+import { agentChildEnv } from './agent-env.js'
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js'
 import type { RunOptions } from './runner.js'
 import type { Logger } from './logger.js'
@@ -54,7 +55,7 @@ export interface CapturedCommandResult {
  * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
  * from settling.
  *
- * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over `agentChildEnv`),
  * not a mutated global: the harness spawns this itself rather than through the agent, so without
  * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
  * had this been staged in `process.env`, against a sibling job's state).
@@ -84,7 +85,7 @@ export async function runCapturedCommand(args: {
       cwd,
       detached: spawnDetached,
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, ...opts.agentEnv },
+      env: agentChildEnv(opts.agentEnv),
     })
     // Keep only the tail (plus the scrub margin); guard against unbounded buffering on a chatty
     // command.

package/src/claude-cli.ts

@@ -0,0 +1,217 @@
+import type { Logger } from './logger.js'
+
+// ---------------------------------------------------------------------------
+// The Claude Code CLI's INVOCATION surface: which of its built-in tools a run asks for, the argv
+// that asks, and the read-back that says what the CLI actually granted.
+//
+// The three belong together because they are one decision seen from three sides. Before this
+// module the harness declared nothing and took whatever the CLI's headless default happened to
+// be, which drifted across CLI versions: 2.1.226 offered the plan tools, 2.1.245 did not, and
+// nothing in the run said so. Both halves of that default were wrong for a disposable container:
+// no `Grep`/`Glob` (so every search went through `Bash` and counted against the progress guard's
+// no-edit budget), no plan tools (so `step.progress` had no signal to lift), and a dozen tools
+// (`CronCreate`, `DesignSync`, `EnterWorktree`, `ScheduleWakeup`, `SendMessage`, `Workflow`,
+// `ReportFindings`, …) an agent in a per-run container can act on none of.
+//
+// Declaring a set therefore has to be measured against the default it replaces, not just against
+// the issue that asked for it: everything the default carried and a container CAN use has to be
+// asked for by name, or the declaration is itself a capability loss. That is what `Monitor` and
+// the web tools are doing in the list below.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every built-in tool a run asks the CLI for, and the ONE value that rides both `--tools` and the
+ * `--allowedTools` re-grant.
+ *
+ * One value rather than two derived ones, because the allow-list turned out to be ADDITIVE rather
+ * than inert: a name in it is UNLOCKED, not merely re-permitted (measured: `--allowedTools
+ * "Bash,Grep"` yields the default set PLUS `Glob` and `Grep`). Two independently-computed lists
+ * would therefore not merely disagree, they would silently re-grant what the other withheld.
+ *
+ * Deliberately OVER-inclusive, and safe to be, because a name the build does not have is dropped
+ * silently rather than refused. The cost is one-directional: a name the CLI HAS and this list
+ * LACKS is a capability silently removed from every run. So the list is measured against the
+ * headless default it replaces, not only against what was wanted, and when the CLI gains a tool a
+ * container agent can use, it is added here.
+ *
+ * A name 2.1.246 does not serve is kept for one of two measured reasons, and they are different
+ * facts worth keeping apart (each probed alone, reading the `init` event's own `tools` array):
+ *
+ *  - ALIASED onto a successor, so the old spelling still buys the capability: `BashOutput` grants
+ *    `TaskOutput`, `KillBash` and `KillShell` both grant `TaskStop`, `Agent` grants `Task`.
+ *  - DROPPED outright (`ListMcpResources`, `ReadMcpResource`, `MultiEdit`, `NotebookRead`,
+ *    `TodoWrite`), and kept only because the harness image is pinned per workspace, so one build
+ *    of this source faces several CLI versions and an older one still serves them.
+ *
+ * The second category is why the CURRENT spelling has to be listed beside the old one rather than
+ * instead of it: `ListMcpResources`/`ReadMcpResource` were carried alone, and since neither is an
+ * alias, every tool-server run reached its resources through nothing at all.
+ *
+ * `WebSearch`/`WebFetch` are unconditional, which is a deliberate reversal of the first cut of this
+ * module. They were gated on the job's `webSearch` flag, which states whether OUR PROXY can serve
+ * web research for the run's account (see `resolveWebSearchAvailability`, whose whole rationale is
+ * that Pi's proxy-backed tools "would just fail/return nothing" without a key). The CLI's web tools
+ * are not proxy-backed: the vendor the leased subscription already pays serves them, and they work
+ * on a deployment with no search provider wired at all. Gating them on that flag therefore withheld
+ * a WORKING capability on the strength of an unrelated fact, which is the opposite of the
+ * pass-through an unwired capability owes. The flag that would legitimately withhold them is a
+ * per-run "may this run reach the web" POLICY, which this platform does not have today; when it
+ * gains one, it gates here and on the Pi path together.
+ */
+export const CLAUDE_TOOL_SET: readonly string[] = [
+  'Agent',
+  'Bash',
+  'BashOutput',
+  'Edit',
+  'Glob',
+  'Grep',
+  'KillBash',
+  'KillShell',
+  'ListMcpResources',
+  'ListMcpResourcesTool',
+  // Waits on the background shells `Bash(run_in_background)` starts. A tool in its own right
+  // (measured: `Monitor` grants `Monitor`), not an alias of the retired kill/output pair, and it
+  // is in the headless default, so omitting it was this declaration's own capability loss.
+  'Monitor',
+  'MultiEdit',
+  'NotebookEdit',
+  'NotebookRead',
+  'Read',
+  'ReadMcpResource',
+  'ReadMcpResourceTool',
+  'Skill',
+  'Task',
+  'TaskCreate',
+  'TaskGet',
+  'TaskList',
+  'TaskOutput',
+  'TaskStop',
+  'TaskUpdate',
+  'TodoWrite',
+  // Loads the schemas of tools a build defers rather than declaring up front. Dropped by 2.1.246
+  // (measured, with and without a tool server wired), and asked for anyway under the
+  // over-inclusive rule: a run wiring several tool servers is exactly the shape a build that
+  // defers tool schemas would hand one to.
+  'ToolSearch',
+  'WebFetch',
+  'WebSearch',
+  'Write',
+]
+
+/**
+ * One capability the run genuinely cannot do without, and every CLI spelling that satisfies it.
+ *
+ * The floor is expressed as CAPABILITIES rather than as names because {@link CLAUDE_TOOL_SET}
+ * is over-inclusive on purpose: a literal "warn on anything requested but absent" would fire on
+ * every single run for the alternate spellings this image carries for other CLI versions, and a
+ * warning that is always on is one nobody reads. A capability with no granted spelling is the
+ * fact worth a line: it means an upstream rename or removal took a tool out of every run of this
+ * image, which otherwise surfaces days later as an agent behaving oddly.
+ */
+interface ClaudeToolCapability {
+  capability: string
+  spellings: readonly string[]
+}
+
+const CLAUDE_TOOL_FLOOR: readonly ClaudeToolCapability[] = [
+  { capability: 'shell', spellings: ['Bash'] },
+  { capability: 'read', spellings: ['Read'] },
+  { capability: 'write', spellings: ['Write'] },
+  { capability: 'edit', spellings: ['Edit', 'MultiEdit'] },
+  { capability: 'search', spellings: ['Grep'] },
+  { capability: 'glob', spellings: ['Glob'] },
+  { capability: 'subagents', spellings: ['Task', 'Agent'] },
+  // The plan signal the harness lifts into `step.subtasks` / `step.progress`, in the two
+  // vocabularies the CLI has used for it (see `progress.ts`, which reads both).
+  { capability: 'plan', spellings: ['TaskCreate', 'TodoWrite'] },
+]
+
+/** The floor, exported so a test can assert every spelling is one this harness actually asks for. */
+export const CLAUDE_TOOL_CAPABILITIES: readonly ClaudeToolCapability[] = CLAUDE_TOOL_FLOOR
+
+/**
+ * The `claude` argv for one run, in the order the CLI's variadic flags require.
+ *
+ * `--tools` and `--allowedTools` are both declared `<tools...>`, so each swallows any trailing
+ * POSITIONAL argument as another tool name; only a following `--flag` terminates them. The prompt
+ * therefore stays on stdin (see `streamCli`) and every flag here is placed before the variadic
+ * pair or introduced by its own `--`, so a new flag cannot be eaten by the one in front of it.
+ */
+export function claudeCliArgs(opts: {
+  model: string
+  /** The built-in tools this run asks for; see {@link CLAUDE_TOOL_SET}. */
+  tools: readonly string[]
+  /** `--mcp-config` + `--strict-mcp-config` + any `--allowedTools`; empty when no server is wired. */
+  mcpArgs: readonly string[]
+  /** `--append-system-prompt <prompt>`, or empty when the prompt was folded into stdin. */
+  appendArgs: readonly string[]
+}): string[] {
+  return [
+    '-p',
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    // The per-run container IS the sandbox, and the run is fully headless (no one to approve a
+    // tool call) — so bypass permissions entirely. `acceptEdits` would auto-accept file edits but
+    // still gate Bash, which in `-p` mode is then denied, leaving the agent unable to run
+    // builds/tests/git to verify its work.
+    '--permission-mode',
+    'bypassPermissions',
+    '--model',
+    opts.model,
+    // Declared rather than defaulted: see this module's header for what the default set costs.
+    '--tools',
+    opts.tools.join(','),
+    ...opts.mcpArgs,
+    ...opts.appendArgs,
+  ]
+}
+
+/**
+ * Read the CLI's startup report (`{"type":"system","subtype":"init"}`) back against what this run
+ * asked for, and say when a required capability is missing.
+ *
+ * The same pairing, and for the same reason, as `assertOnboardingKeysCurrent`: the CLI is the only
+ * one who knows what it granted, it says so exactly once before the first model call, and pairing
+ * that answer with the CLI version is what makes an upstream rename diffable instead of a mystery.
+ * The version comes off the event itself (`claude_code_version`) rather than an env var the image
+ * would have to remember to bake.
+ *
+ * Best-effort and never throws: a run whose tool surface is short is still a run, and the honest
+ * disposition for a floor this image cannot verify is to SAY it could not be read, not to fail the
+ * job and not to stay silent (which reads exactly like a satisfied request).
+ */
+export function assertClaudeToolsCurrent(
+  event: Record<string, unknown>,
+  requested: readonly string[],
+  log: Logger | undefined,
+): void {
+  if (!log || event.type !== 'system' || event.subtype !== 'init') return
+  const version =
+    typeof event.claude_code_version === 'string' ? event.claude_code_version : undefined
+  const cliVersion = version ? { cliVersion: version } : {}
+  if (!Array.isArray(event.tools)) {
+    log.warn('claude-code announced no tool list, so this run has an unverified tool surface', {
+      requestedTools: [...requested],
+      ...cliVersion,
+    })
+    return
+  }
+  const granted = new Set(event.tools.filter((t): t is string => typeof t === 'string'))
+  const missing = CLAUDE_TOOL_FLOOR.filter((c) => !c.spellings.some((s) => granted.has(s))).map(
+    (c) => c.capability,
+  )
+  const fields = {
+    requestedTools: [...requested],
+    grantedTools: [...granted].sort(),
+    ...cliVersion,
+  }
+  if (missing.length > 0) {
+    log.warn('claude-code granted no tool for a capability this run requires', {
+      ...fields,
+      missingCapabilities: missing,
+    })
+    return
+  }
+  log.info('claude-code tool set granted', fields)
+}