@cat-factory/executor-harness 1.39.0 → 1.39.3

package/dist/agent.js

@@ -5,7 +5,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
-import { captureRedactedOutput, redactSecrets } from './redact.js';
+import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -323,6 +323,32 @@ async function runPreviewMode(job, opts) {
         throw err;
     }
 }
+/**
+ * Inject the tester's sensitive secrets into the PROCESS environment so the agent's shell tools
+ * (spawned as child processes that inherit this env) can read `$KEY` — the out-of-band delivery
+ * channel. Each value is registered for redaction so it can't leak into captured output/logs.
+ * Returns a restore closure that puts the environment back afterward (warm-pool hygiene, so a
+ * later job on a reused container never inherits a prior run's secrets). Reserved/toolchain env
+ * names were already dropped at parse. A no-op when there are no secrets.
+ */
+function applyTestSecrets(secrets) {
+    if (!secrets?.length)
+        return () => { };
+    registerKnownSecrets(secrets.map((s) => s.value));
+    const previous = new Map();
+    for (const { key, value } of secrets) {
+        previous.set(key, process.env[key]);
+        process.env[key] = value;
+    }
+    return () => {
+        for (const [key, prior] of previous) {
+            if (prior === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = prior;
+        }
+    };
+}
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -386,6 +412,10 @@ async function runExploreMode(job, opts) {
         const infraSetupFields = managed?.record
             ? { infraSetup: managed.record }
             : {};
+        // Inject the tester's sensitive secrets into the environment (out of band) so the agent's
+        // shell can read them as `$KEY`; restore afterwards so a reused (warm-pool) container never
+        // leaks them to a later job. A no-op for non-tester runs (no `testSecrets`).
+        const restoreSecrets = applyTestSecrets(job.testSecrets);
         try {
             opts.onPhase?.('agent');
             logger.info('agent(explore): running agent', { serviceDirectory });
@@ -412,6 +442,7 @@ async function runExploreMode(job, opts) {
             return await finalizeExploreResult(job, { summary, stats, stderrTail, usage, callMetrics, runDiag }, { infra, infraSetupFields, logger, signal: opts.signal });
         }
         finally {
+            restoreSecrets();
             if (managed)
                 await managed.cleanup();
         }

package/dist/job.js

@@ -286,6 +286,37 @@ export function parsePackageRegistries(value, env = process.env) {
     }
     return entries;
 }
+/** A valid POSIX shell variable name (letters, digits, underscore; not starting with a digit). */
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validate the optional tester `testSecrets` list — `{ key, value }` env pairs the harness
+ * injects into the run environment. Keys must be valid env-var names; toolchain-critical /
+ * reserved names ({@link isReservedEnvName}) and duplicates are dropped so a drifted body can't
+ * clobber PATH/NODE_OPTIONS/etc. Absent ⇒ no secrets injected.
+ */
+export function parseTestSecrets(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'testSecrets' must be an array");
+    const entries = [];
+    const seen = new Set();
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`Invalid job: 'testSecrets[${i}]' must be an object`);
+        }
+        const entry = raw;
+        const key = str(entry.key, `testSecrets[${i}].key`).trim();
+        if (!ENV_VAR_NAME_PATTERN.test(key)) {
+            throw new Error(`Invalid job: 'testSecrets[${i}].key' must be a valid environment variable name`);
+        }
+        if (isReservedEnvName(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        entries.push({ key, value: str(entry.value, `testSecrets[${i}].value`) });
+    }
+    return entries;
+}
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
 function parseAgentBootstrapSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -540,6 +571,7 @@ export function parseAgentJob(input) {
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
+    const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const job = {
         jobId: str(o.jobId, 'jobId'),
@@ -560,6 +592,7 @@ export function parseAgentJob(input) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
+        ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
         ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.39.0",
+  "version": "1.39.3",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.104.0",
-    "@cat-factory/spend": "0.11.21"
+    "@cat-factory/server": "0.106.0",
+    "@cat-factory/spend": "0.12.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -9,10 +9,11 @@ import type {
   AgentResult,
   InfraSetupRecord,
   ServiceInfraSpec,
+  TestSecretSpec,
 } from './job.js'
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
 import { configurePackageRegistries } from './package-registries.js'
-import { captureRedactedOutput, redactSecrets } from './redact.js'
+import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js'
 import {
   cloneRepo,
   commitAll,
@@ -408,6 +409,30 @@ async function runPreviewMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
   }
 }
 
+/**
+ * Inject the tester's sensitive secrets into the PROCESS environment so the agent's shell tools
+ * (spawned as child processes that inherit this env) can read `$KEY` — the out-of-band delivery
+ * channel. Each value is registered for redaction so it can't leak into captured output/logs.
+ * Returns a restore closure that puts the environment back afterward (warm-pool hygiene, so a
+ * later job on a reused container never inherits a prior run's secrets). Reserved/toolchain env
+ * names were already dropped at parse. A no-op when there are no secrets.
+ */
+function applyTestSecrets(secrets: TestSecretSpec[] | undefined): () => void {
+  if (!secrets?.length) return () => {}
+  registerKnownSecrets(secrets.map((s) => s.value))
+  const previous = new Map<string, string | undefined>()
+  for (const { key, value } of secrets) {
+    previous.set(key, process.env[key])
+    process.env[key] = value
+  }
+  return () => {
+    for (const [key, prior] of previous) {
+      if (prior === undefined) delete process.env[key]
+      else process.env[key] = prior
+    }
+  }
+}
+
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -473,6 +498,11 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
         ? { infraSetup: managed.record }
         : {}
 
+      // Inject the tester's sensitive secrets into the environment (out of band) so the agent's
+      // shell can read them as `$KEY`; restore afterwards so a reused (warm-pool) container never
+      // leaks them to a later job. A no-op for non-tester runs (no `testSecrets`).
+      const restoreSecrets = applyTestSecrets(job.testSecrets)
+
       try {
         opts.onPhase?.('agent')
         logger.info('agent(explore): running agent', { serviceDirectory })
@@ -513,6 +543,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           { infra, infraSetupFields, logger, signal: opts.signal },
         )
       } finally {
+        restoreSecrets()
         if (managed) await managed.cleanup()
       }
     },

package/src/job.ts

@@ -418,6 +418,49 @@ export function parsePackageRegistries(
   return entries
 }
 
+/**
+ * One sensitive test credential the tester receives: an env-var name + its (secret) value.
+ * The backend seals these at rest and decrypts them at dispatch; the harness injects each as an
+ * environment variable the tester's shell can read (out of band — the value is NEVER in the
+ * prompt/telemetry). See {@link parseTestSecrets}.
+ */
+export interface TestSecretSpec {
+  key: string
+  value: string
+}
+
+/** A valid POSIX shell variable name (letters, digits, underscore; not starting with a digit). */
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * Validate the optional tester `testSecrets` list — `{ key, value }` env pairs the harness
+ * injects into the run environment. Keys must be valid env-var names; toolchain-critical /
+ * reserved names ({@link isReservedEnvName}) and duplicates are dropped so a drifted body can't
+ * clobber PATH/NODE_OPTIONS/etc. Absent ⇒ no secrets injected.
+ */
+export function parseTestSecrets(value: unknown): TestSecretSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'testSecrets' must be an array")
+  const entries: TestSecretSpec[] = []
+  const seen = new Set<string>()
+  for (const [i, raw] of value.entries()) {
+    if (typeof raw !== 'object' || raw === null) {
+      throw new Error(`Invalid job: 'testSecrets[${i}]' must be an object`)
+    }
+    const entry = raw as Record<string, unknown>
+    const key = str(entry.key, `testSecrets[${i}].key`).trim()
+    if (!ENV_VAR_NAME_PATTERN.test(key)) {
+      throw new Error(
+        `Invalid job: 'testSecrets[${i}].key' must be a valid environment variable name`,
+      )
+    }
+    if (isReservedEnvName(key) || seen.has(key)) continue
+    seen.add(key)
+    entries.push({ key, value: str(entry.value, `testSecrets[${i}].value`) })
+  }
+  return entries
+}
+
 // ---- Shared repo-bootstrap target ---------------------------------------
 
 /** The new repository a repo-bootstrap run force-pushes its fresh history to. */
@@ -613,6 +656,13 @@ export interface AgentJob extends HarnessAuthFields {
    * job on a reused container is removed.
    */
   packageRegistries?: PackageRegistrySpec[]
+  /**
+   * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
+   * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value
+   * ever appearing in the prompt or telemetry. Reserved/toolchain env names are dropped at parse.
+   * Absent ⇒ no secrets injected.
+   */
+  testSecrets?: TestSecretSpec[]
   /**
    * Explore mode: stand the service's dependencies up before the agent runs (the
    * tester). Brings the docker-compose infra up on localhost for the duration of the
@@ -1053,6 +1103,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
+  const testSecrets = parseTestSecrets(o.testSecrets)
   const guardLimits = parseGuardLimits(o.guardLimits)
   const job: AgentJob = {
     jobId: str(o.jobId, 'jobId'),
@@ -1073,6 +1124,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
+    ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
     ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),