@cat-factory/executor-harness 1.86.2 → 1.88.0

package/dist/agent.d.ts

@@ -46,6 +46,13 @@ export declare function buildPreviewOutcome(standUp: {
  * the restore step entirely.
  */
 export declare function testSecretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
+/**
+ * The shared `{ key, value }[]` → child-env projection behind {@link testSecretEnv} and the
+ * generative integrations' credentials. One implementation because both channels owe the same two
+ * things — the values registered for redaction, and the env returned rather than written to
+ * `process.env` — and a second copy is a second place to forget the redaction.
+ */
+export declare function secretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
 /**
  * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
  * peer repos or read-only reference repos). The post-commit validation command is only wired into

package/dist/agent.js

@@ -248,7 +248,16 @@ export async function handleAgent(job, opts = {}) {
         // inherit this env, so they all read the written npmrc). In a container a job with no
         // entries clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
         const registryEnv = await configurePackageRegistries(job.packageRegistries, scopeDir ? { isolatedDir: scopeDir } : {});
-        const scoped = withAgentEnv(opts, registryEnv);
+        // The credentials of this job's GENERATIVE BINARY INTEGRATIONS, layered on for EVERY mode
+        // rather than inside one of them: the kinds that carry the `binary-output` trait are a
+        // deployment's own and may be explore or coding agents, and a key delivered to one mode and
+        // not the other would be an integration that works or 401s depending on how its step was
+        // registered. Per-job env like everything else here — never `process.env`, which the shared
+        // native host process makes a cross-job leak.
+        const scoped = withAgentEnv(opts, {
+            ...registryEnv,
+            ...secretEnv(job.generatorSecrets),
+        });
         if (job.mode === 'preview')
             return await runPreviewMode(job, scoped);
         return job.mode === 'coding'
@@ -369,6 +378,15 @@ async function runPreviewMode(job, opts) {
  * the restore step entirely.
  */
 export function testSecretEnv(secrets) {
+    return secretEnv(secrets);
+}
+/**
+ * The shared `{ key, value }[]` → child-env projection behind {@link testSecretEnv} and the
+ * generative integrations' credentials. One implementation because both channels owe the same two
+ * things — the values registered for redaction, and the env returned rather than written to
+ * `process.env` — and a second copy is a second place to forget the redaction.
+ */
+export function secretEnv(secrets) {
     if (!secrets?.length)
         return {};
     registerKnownSecrets(secrets.map((s) => s.value));

package/dist/job-env.d.ts

@@ -0,0 +1,44 @@
+/** A required non-empty string field of the job body. */
+export declare function str(value: unknown, path: string): string;
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+export declare const RESERVED_ENV_NAMES: Set<string>;
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+export declare function isReservedEnvName(key: string): boolean;
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+export declare function parseInfraEnv(raw: unknown): Record<string, string>;
+/**
+ * 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 parseSecretEnvPairs}.
+ */
+export interface TestSecretSpec {
+    key: string;
+    value: string;
+}
+/**
+ * Validate a `{ key, value }` env-pair list under `field`. Shared by the tester's `testSecrets`
+ * and by `generatorSecrets` (the credentials of a step's generative binary integrations), because
+ * both are secret values the harness turns into environment variables of the agent's own process
+ * and both owe the same guarantees: valid env-var names, no toolchain-critical
+ * ({@link isReservedEnvName}) names, no duplicates. A second copy of these rules would be a second
+ * place for a drifted body to clobber PATH.
+ */
+export declare function parseSecretEnvPairs(value: unknown, field: string): TestSecretSpec[];

package/dist/job-env.js

@@ -0,0 +1,108 @@
+// The primitive VALUE rules of the untrusted job body: what counts as a required string, which
+// environment-variable names a body may never set, and how the two env-bearing fields (the
+// tester's `testSecrets`, a generative integration's `generatorSecrets`, and a frontend binding's
+// `env`) are parsed against those rules.
+//
+// Extracted from `job.ts` when the generative-integration credentials arrived (the file-size
+// ratchet: split along a cohesive seam, never raise the budget). The seam is a real one — every
+// rule here answers "may this raw value become part of a child process's environment", which is
+// the harness's sharpest untrusted-input boundary, and it is now shared by three parsers rather
+// than being one parser's private business.
+/** A required non-empty string field of the job body. */
+export function str(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid job: '${path}' must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+export const RESERVED_ENV_NAMES = new Set([
+    'PATH',
+    'HOME',
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'NODE_EXTRA_CA_CERTS',
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'BASH_ENV',
+    'ENV',
+    'SHELL',
+    'IFS',
+]);
+/**
+ * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
+ * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
+ * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
+ * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
+ * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
+ * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
+ */
+const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_'];
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+export function isReservedEnvName(key) {
+    if (RESERVED_ENV_NAMES.has(key))
+        return true;
+    const lower = key.toLowerCase();
+    return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
+}
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+export function parseInfraEnv(raw) {
+    const env = {};
+    if (typeof raw === 'object' && raw !== null) {
+        for (const [key, val] of Object.entries(raw)) {
+            if (key && !isReservedEnvName(key) && typeof val === 'string')
+                env[key] = val;
+        }
+    }
+    return env;
+}
+/** 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 a `{ key, value }` env-pair list under `field`. Shared by the tester's `testSecrets`
+ * and by `generatorSecrets` (the credentials of a step's generative binary integrations), because
+ * both are secret values the harness turns into environment variables of the agent's own process
+ * and both owe the same guarantees: valid env-var names, no toolchain-critical
+ * ({@link isReservedEnvName}) names, no duplicates. A second copy of these rules would be a second
+ * place for a drifted body to clobber PATH.
+ */
+export function parseSecretEnvPairs(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`Invalid job: '${field}' 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: '${field}[${i}]' must be an object`);
+        }
+        const entry = raw;
+        const key = str(entry.key, `${field}[${i}].key`).trim();
+        if (!ENV_VAR_NAME_PATTERN.test(key)) {
+            throw new Error(`Invalid job: '${field}[${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, `${field}[${i}].value`) });
+    }
+    return entries;
+}

package/dist/job.d.ts

@@ -6,6 +6,8 @@ import { type ValidationChecksSpec, type ValidationReport } from './validation-c
 import { type ReproductionReport, type ReproductionSpec } from './reproduction-proof.js';
 import { type DependencyInstallSpec } from './dependency-install.js';
 import { type McpServerSpec, type SkillResourceSpec, type SkillSpec } from './agent-capabilities.js';
+import { type TestSecretSpec } from './job-env.js';
+export type { TestSecretSpec };
 export type { McpServerSpec, SkillResourceSpec, SkillSpec };
 /**
  * Per-job auth fields, shared across every job shape. The Pi harness carries the
@@ -130,23 +132,6 @@ export interface PackageRegistrySpec {
 export declare function allowedNpmRegistryHosts(env?: NodeJS.ProcessEnv): Set<string>;
 /** Validate the optional `packageRegistries` list (see {@link PackageRegistrySpec}). */
 export declare function parsePackageRegistries(value: unknown, env?: NodeJS.ProcessEnv): PackageRegistrySpec[];
-/**
- * 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;
-}
-/**
- * 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 declare function parseTestSecrets(value: unknown): TestSecretSpec[];
 /** The new repository a repo-bootstrap run force-pushes its fresh history to. */
 export interface BootstrapTargetSpec {
     owner: string;
@@ -372,6 +357,16 @@ export interface AgentJob extends HarnessAuthFields {
      * Absent ⇒ no secrets injected.
      */
     testSecrets?: TestSecretSpec[];
+    /**
+     * The resolved credentials of the step's GENERATIVE BINARY INTEGRATIONS (the image / music /
+     * video generation APIs its `binaryOutput` selection named), as env pairs the harness injects
+     * into the agent's own process — where the agent's brief has already told it to read them from.
+     * Distinct from {@link testSecrets} because the two have different producers and different
+     * lifetimes: tester secrets are workspace state a human stored, these are a deployment's
+     * registration resolved per dispatch. Absent ⇒ no integration declared a credential, or none
+     * resolved (which the agent is told to report rather than work around).
+     */
+    generatorSecrets?: 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

package/dist/job.js

@@ -2,12 +2,7 @@ import { parseValidationChecksSpec, } from './validation-checks.js';
 import { parseReproductionSpec, } from './reproduction-proof.js';
 import { parseDependencyInstallSpec } from './dependency-install.js';
 import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
-function str(value, path) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new Error(`Invalid job: '${path}' must be a non-empty string`);
-    }
-    return value;
-}
+import { parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js';
 /** A positive finite integer, or undefined for any other input (silently ignored). */
 function posInt(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0
@@ -332,37 +327,6 @@ 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)
@@ -453,64 +417,6 @@ function parseStringMap(value) {
     }
     return Object.keys(out).length ? out : undefined;
 }
-/**
- * Env-var names never injected from a frontend binding: spread over `process.env` at build
- * time, so any of these would break the toolchain (or enable code execution / cert overrides)
- * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
- * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
- */
-const RESERVED_ENV_NAMES = new Set([
-    'PATH',
-    'HOME',
-    'NODE_OPTIONS',
-    'NODE_PATH',
-    'NODE_EXTRA_CA_CERTS',
-    'LD_PRELOAD',
-    'LD_LIBRARY_PATH',
-    'BASH_ENV',
-    'ENV',
-    'SHELL',
-    'IFS',
-]);
-/**
- * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
- * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
- * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
- * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
- * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
- * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
- */
-const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_'];
-/**
- * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
- * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
- * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
- * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
- */
-function isReservedEnvName(key) {
-    if (RESERVED_ENV_NAMES.has(key))
-        return true;
-    const lower = key.toLowerCase();
-    return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
-}
-/**
- * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
- * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
- * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
- * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
- * replace it with a URL and the build would no longer find its tools. Extracted from the infra
- * parsers to keep their cyclomatic complexity down.
- */
-function parseInfraEnv(raw) {
-    const env = {};
-    if (typeof raw === 'object' && raw !== null) {
-        for (const [key, val] of Object.entries(raw)) {
-            if (key && !isReservedEnvName(key) && typeof val === 'string')
-                env[key] = val;
-        }
-    }
-    return env;
-}
 /** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
 function parseFrontendInfraSpec(o) {
     const packageManager = o.packageManager === 'pnpm' || o.packageManager === 'npm' || o.packageManager === 'yarn'
@@ -607,7 +513,8 @@ export function parseAgentJob(input) {
         packageRegistries: parsePackageRegistries(o.packageRegistries),
         skills: parseSkillSpecs(o.skills),
         mcpServers: parseMcpServerSpecs(o.mcpServers),
-        testSecrets: parseTestSecrets(o.testSecrets),
+        testSecrets: parseSecretEnvPairs(o.testSecrets, 'testSecrets'),
+        generatorSecrets: parseSecretEnvPairs(o.generatorSecrets, 'generatorSecrets'),
         guardLimits: parseGuardLimits(o.guardLimits),
         validation: parseValidationSpec(o.validation),
         validationChecks: parseValidationChecksSpec(o.validationChecks),
@@ -669,7 +576,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -689,6 +596,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(skills ? { skills } : {}),
         ...(mcpServers ? { mcpServers } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
+        ...(generatorSecrets.length ? { generatorSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.86.2",
+  "version": "1.88.0",
   "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",
@@ -30,9 +30,9 @@
     "hono": "^4.12.33",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.214.1",
-    "@cat-factory/server": "0.194.0",
-    "@cat-factory/spend": "0.13.1"
+    "@cat-factory/kernel": "0.215.0",
+    "@cat-factory/server": "0.195.0",
+    "@cat-factory/spend": "0.13.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -330,7 +330,16 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
       job.packageRegistries,
       scopeDir ? { isolatedDir: scopeDir } : {},
     )
-    const scoped = withAgentEnv(opts, registryEnv)
+    // The credentials of this job's GENERATIVE BINARY INTEGRATIONS, layered on for EVERY mode
+    // rather than inside one of them: the kinds that carry the `binary-output` trait are a
+    // deployment's own and may be explore or coding agents, and a key delivered to one mode and
+    // not the other would be an integration that works or 401s depending on how its step was
+    // registered. Per-job env like everything else here — never `process.env`, which the shared
+    // native host process makes a cross-job leak.
+    const scoped = withAgentEnv(opts, {
+      ...registryEnv,
+      ...secretEnv(job.generatorSecrets),
+    })
     if (job.mode === 'preview') return await runPreviewMode(job, scoped)
     return job.mode === 'coding'
       ? await runCodingMode(job, scoped)
@@ -454,6 +463,16 @@ async function runPreviewMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
  * the restore step entirely.
  */
 export function testSecretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string> {
+  return secretEnv(secrets)
+}
+
+/**
+ * The shared `{ key, value }[]` → child-env projection behind {@link testSecretEnv} and the
+ * generative integrations' credentials. One implementation because both channels owe the same two
+ * things — the values registered for redaction, and the env returned rather than written to
+ * `process.env` — and a second copy is a second place to forget the redaction.
+ */
+export function secretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string> {
   if (!secrets?.length) return {}
   registerKnownSecrets(secrets.map((s) => s.value))
   return Object.fromEntries(secrets.map(({ key, value }) => [key, value]))

package/src/job-env.ts

@@ -0,0 +1,121 @@
+// The primitive VALUE rules of the untrusted job body: what counts as a required string, which
+// environment-variable names a body may never set, and how the two env-bearing fields (the
+// tester's `testSecrets`, a generative integration's `generatorSecrets`, and a frontend binding's
+// `env`) are parsed against those rules.
+//
+// Extracted from `job.ts` when the generative-integration credentials arrived (the file-size
+// ratchet: split along a cohesive seam, never raise the budget). The seam is a real one — every
+// rule here answers "may this raw value become part of a child process's environment", which is
+// the harness's sharpest untrusted-input boundary, and it is now shared by three parsers rather
+// than being one parser's private business.
+
+/** A required non-empty string field of the job body. */
+export function str(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Invalid job: '${path}' must be a non-empty string`)
+  }
+  return value
+}
+
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+export const RESERVED_ENV_NAMES = new Set([
+  'PATH',
+  'HOME',
+  'NODE_OPTIONS',
+  'NODE_PATH',
+  'NODE_EXTRA_CA_CERTS',
+  'LD_PRELOAD',
+  'LD_LIBRARY_PATH',
+  'BASH_ENV',
+  'ENV',
+  'SHELL',
+  'IFS',
+])
+
+/**
+ * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
+ * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
+ * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
+ * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
+ * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
+ * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
+ */
+const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_']
+
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+export function isReservedEnvName(key: string): boolean {
+  if (RESERVED_ENV_NAMES.has(key)) return true
+  const lower = key.toLowerCase()
+  return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p))
+}
+
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+export function parseInfraEnv(raw: unknown): Record<string, string> {
+  const env: Record<string, string> = {}
+  if (typeof raw === 'object' && raw !== null) {
+    for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+      if (key && !isReservedEnvName(key) && typeof val === 'string') env[key] = val
+    }
+  }
+  return env
+}
+
+/**
+ * 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 parseSecretEnvPairs}.
+ */
+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 a `{ key, value }` env-pair list under `field`. Shared by the tester's `testSecrets`
+ * and by `generatorSecrets` (the credentials of a step's generative binary integrations), because
+ * both are secret values the harness turns into environment variables of the agent's own process
+ * and both owe the same guarantees: valid env-var names, no toolchain-critical
+ * ({@link isReservedEnvName}) names, no duplicates. A second copy of these rules would be a second
+ * place for a drifted body to clobber PATH.
+ */
+export function parseSecretEnvPairs(value: unknown, field: string): TestSecretSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error(`Invalid job: '${field}' 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: '${field}[${i}]' must be an object`)
+    }
+    const entry = raw as Record<string, unknown>
+    const key = str(entry.key, `${field}[${i}].key`).trim()
+    if (!ENV_VAR_NAME_PATTERN.test(key)) {
+      throw new Error(`Invalid job: '${field}[${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, `${field}[${i}].value`) })
+  }
+  return entries
+}

package/src/job.ts

@@ -20,6 +20,11 @@ import {
   type SkillResourceSpec,
   type SkillSpec,
 } from './agent-capabilities.js'
+import { type TestSecretSpec, parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js'
+
+// Re-exported so a handler describing a job keeps ONE import site (the env-pair shape is a job
+// body field like any other; only its VALIDATION moved out).
+export type { TestSecretSpec }
 
 // Re-exported so the job body stays the one import site for a harness handler describing a job.
 export type { McpServerSpec, SkillResourceSpec, SkillSpec }
@@ -142,13 +147,6 @@ export interface ReferenceRepoSpec {
   ghToken?: string
 }
 
-function str(value: unknown, path: string): string {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`Invalid job: '${path}' must be a non-empty string`)
-  }
-  return value
-}
-
 /** A positive finite integer, or undefined for any other input (silently ignored). */
 function posInt(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) && value > 0
@@ -494,49 +492,6 @@ 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. */
@@ -782,6 +737,16 @@ export interface AgentJob extends HarnessAuthFields {
    * Absent ⇒ no secrets injected.
    */
   testSecrets?: TestSecretSpec[]
+  /**
+   * The resolved credentials of the step's GENERATIVE BINARY INTEGRATIONS (the image / music /
+   * video generation APIs its `binaryOutput` selection named), as env pairs the harness injects
+   * into the agent's own process — where the agent's brief has already told it to read them from.
+   * Distinct from {@link testSecrets} because the two have different producers and different
+   * lifetimes: tester secrets are workspace state a human stored, these are a deployment's
+   * registration resolved per dispatch. Absent ⇒ no integration declared a credential, or none
+   * resolved (which the agent is told to report rather than work around).
+   */
+  generatorSecrets?: 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
@@ -1110,66 +1075,6 @@ function parseStringMap(value: unknown): Record<string, string> | undefined {
   return Object.keys(out).length ? out : undefined
 }
 
-/**
- * Env-var names never injected from a frontend binding: spread over `process.env` at build
- * time, so any of these would break the toolchain (or enable code execution / cert overrides)
- * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
- * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
- */
-const RESERVED_ENV_NAMES = new Set([
-  'PATH',
-  'HOME',
-  'NODE_OPTIONS',
-  'NODE_PATH',
-  'NODE_EXTRA_CA_CERTS',
-  'LD_PRELOAD',
-  'LD_LIBRARY_PATH',
-  'BASH_ENV',
-  'ENV',
-  'SHELL',
-  'IFS',
-])
-
-/**
- * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
- * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
- * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
- * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
- * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
- * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
- */
-const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_']
-
-/**
- * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
- * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
- * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
- * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
- */
-function isReservedEnvName(key: string): boolean {
-  if (RESERVED_ENV_NAMES.has(key)) return true
-  const lower = key.toLowerCase()
-  return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p))
-}
-
-/**
- * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
- * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
- * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
- * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
- * replace it with a URL and the build would no longer find its tools. Extracted from the infra
- * parsers to keep their cyclomatic complexity down.
- */
-function parseInfraEnv(raw: unknown): Record<string, string> {
-  const env: Record<string, string> = {}
-  if (typeof raw === 'object' && raw !== null) {
-    for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
-      if (key && !isReservedEnvName(key) && typeof val === 'string') env[key] = val
-    }
-  }
-  return env
-}
-
 /** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
 function parseFrontendInfraSpec(o: Record<string, unknown>): FrontendInfraSpec {
   const packageManager =
@@ -1321,7 +1226,8 @@ export function parseAgentJob(input: unknown): AgentJob {
     packageRegistries: parsePackageRegistries(o.packageRegistries),
     skills: parseSkillSpecs(o.skills),
     mcpServers: parseMcpServerSpecs(o.mcpServers),
-    testSecrets: parseTestSecrets(o.testSecrets),
+    testSecrets: parseSecretEnvPairs(o.testSecrets, 'testSecrets'),
+    generatorSecrets: parseSecretEnvPairs(o.generatorSecrets, 'generatorSecrets'),
     guardLimits: parseGuardLimits(o.guardLimits),
     validation: parseValidationSpec(o.validation),
     validationChecks: parseValidationChecksSpec(o.validationChecks),
@@ -1362,7 +1268,8 @@ interface ParsedAgentJobParts {
   packageRegistries: ReturnType<typeof parsePackageRegistries>
   skills: ReturnType<typeof parseSkillSpecs>
   mcpServers: ReturnType<typeof parseMcpServerSpecs>
-  testSecrets: ReturnType<typeof parseTestSecrets>
+  testSecrets: ReturnType<typeof parseSecretEnvPairs>
+  generatorSecrets: ReturnType<typeof parseSecretEnvPairs>
   guardLimits: ReturnType<typeof parseGuardLimits>
   validation: ReturnType<typeof parseValidationSpec>
   validationChecks: ReturnType<typeof parseValidationChecksSpec>
@@ -1425,6 +1332,7 @@ function assembleAgentJob(
     reproduction,
     dependencyInstall,
     reviewPrNumber,
+    generatorSecrets,
   } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
   return {
@@ -1445,6 +1353,7 @@ function assembleAgentJob(
     ...(skills ? { skills } : {}),
     ...(mcpServers ? { mcpServers } : {}),
     ...(testSecrets.length ? { testSecrets } : {}),
+    ...(generatorSecrets.length ? { generatorSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(pr ? { pr } : {}),
     ...(peerRepos.length ? { peerRepos } : {}),