@cat-factory/executor-harness 1.104.0 → 1.108.0

package/dist/job.d.ts

@@ -8,10 +8,10 @@ import { type ReproductionReport, type ReproductionSpec } from './reproduction-p
 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';
-import { type ContextFileSpec, type ReferenceScreenshotSpec, type ReferenceScreenshotsSpec } from './context-manifests.js';
+import { type ContextFileSpec, type ImageFileSpec, type ImageManifestSpec } from './context-manifests.js';
 export type { TestSecretSpec };
 export type { McpServerSpec, SkillResourceSpec, SkillSpec };
-export type { ContextFileSpec, ReferenceScreenshotSpec, ReferenceScreenshotsSpec };
+export type { ContextFileSpec, ImageFileSpec, ImageManifestSpec };
 /**
  * Per-job auth fields, shared across every job shape. The Pi harness carries the
  * proxy base URL + a model-locked session token; the subscription harnesses
@@ -320,11 +320,23 @@ export interface AgentJob extends HarnessAuthFields {
     contextFiles?: ContextFileSpec[];
     /**
      * The task's reference design images, downloaded into `.cat-context/reference-screenshots/`
-     * before the agent runs (see {@link ReferenceScreenshotsSpec}). Sent only for a kind that
+     * before the agent runs (see {@link ImageManifestSpec}). Sent only for a kind that
      * CAPTURES views and only when the task actually has references, so absent is the normal case
      * and means the agent names its own views.
      */
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    /**
+     * The PICTURES of the task's designs, for a kind that builds or plans a screen. Downloaded into
+     * `.cat-context/design-renders/` before the run; the agent's prompt (composed by the backend)
+     * names each file and its view, and the agent opens them with its own image-reading tool.
+     *
+     * The same wire shape and the same download seam as {@link AgentJob.referenceScreenshots}, and a
+     * separate field with a separate directory because the two are opposite instructions: that one
+     * names the views to CAPTURE, this one is the design to BUILD. Sent only when the backend
+     * decided this harness can read an image at all, so absent is the normal case and means the run
+     * works from the textual design description (its prompt says which).
+     */
+    designImages?: ImageManifestSpec;
     /**
      * Private package-registry auth (npm private orgs, GitHub Packages), rendered into
      * `~/.npmrc` before the run so the checkout's installs — the agent's own and the

package/dist/job.js

@@ -3,7 +3,7 @@ import { parseReproductionSpec, } from './reproduction-proof.js';
 import { parseDependencyInstallSpec } from './dependency-install.js';
 import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 import { parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js';
-import { parseContextFiles, parseReferenceScreenshots, } from './context-manifests.js';
+import { parseContextFiles, parseImageManifest, } from './context-manifests.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
@@ -478,7 +478,8 @@ export function parseAgentJob(input) {
         referenceBranches: parseReferenceBranches(o.referenceBranches),
         bootstrap: parseAgentBootstrapSpec(o.bootstrap),
         contextFiles: parseContextFiles(o.contextFiles),
-        referenceScreenshots: parseReferenceScreenshots(o.referenceScreenshots),
+        referenceScreenshots: parseImageManifest(o.referenceScreenshots),
+        designImages: parseImageManifest(o.designImages),
         packageRegistries: parsePackageRegistries(o.packageRegistries),
         skills: parseSkillSpecs(o.skills),
         mcpServers: parseMcpServerSpecs(o.mcpServers),
@@ -545,7 +546,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, referenceScreenshots, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, referenceScreenshots, designImages, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -562,6 +563,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(referenceScreenshots ? { referenceScreenshots } : {}),
+        ...(designImages ? { designImages } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
         ...(skills ? { skills } : {}),
         ...(mcpServers ? { mcpServers } : {}),

package/dist/pi-workspace.d.ts

@@ -1,4 +1,4 @@
-import type { RepoSpec, ReferenceScreenshotsSpec } from './job.js';
+import type { RepoSpec, ImageManifestSpec } from './job.js';
 import type { McpServerSpec, SkillSpec } from './agent-capabilities.js';
 import { type ContextFileInfo, type PiRunOutcome } from './pi.js';
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js';
@@ -110,7 +110,14 @@ export interface AgentRunSpec {
      * before the run and named in the agent's prompt, so a capturing agent can compare against them
      * and use their view names. Absent ⇒ nothing is downloaded and nothing is said.
      */
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    /**
+     * The PICTURES of the task's designs. Downloaded into `.cat-context/design-renders/` before the
+     * run; the agent's prompt (composed by the backend) already names each file and its view, so the
+     * only thing said here is a CORRECTION when one of them did not land. Absent ⇒ nothing is
+     * downloaded and nothing is said.
+     */
+    designImages?: ImageManifestSpec;
     /**
      * The skills to make available for this run — a `skill` step's picked skill and/or the playbooks
      * the running agent kind declares. Installed HARNESS-AWARE: the claude-code runner writes them

package/dist/pi-workspace.js

@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { deliverReferenceScreenshots } from './reference-screenshots.js';
+import { deliverJobImages } from './job-images.js';
 import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
 import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
@@ -154,7 +154,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // cannot report a view an earlier round successfully delivered as absent. A view that MISSED is
     // retried, which is the behaviour worth having: the next round is a fresh chance at a blob
     // backend that was briefly down.
-    const referenceGuidance = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, {
+    const imageGuidance = await deliverJobImages(spec, {
         ...(opts.signal ? { signal: opts.signal } : {}),
         log: opts.log ?? log,
     });
@@ -180,7 +180,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         const subOutcome = await runSubscriptionHarness(spec.harness, {
             cwd: spec.dir,
             model: spec.model,
-            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${referenceGuidance}`,
+            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
             userPrompt: spec.userPrompt,
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
@@ -251,7 +251,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         serviceDirectory: spec.serviceDirectory,
         contextFiles,
         hasBlueprints,
-        ...(referenceGuidance ? { referenceGuidance } : {}),
+        ...(imageGuidance ? { referenceGuidance: imageGuidance } : {}),
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
     // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so

package/dist/reference-screenshots.d.ts

@@ -1,47 +1,15 @@
-import type { ReferenceScreenshotsSpec } from './job.js';
+import type { ImageManifestSpec } from './job.js';
 import type { Logger } from './logger.js';
+import { type ContextImageOutcome } from './context-images.js';
 /** Subdirectory of {@link CONTEXT_DIR} the reference designs are written to. */
 export declare const REFERENCE_SCREENSHOT_SUBDIR = "reference-screenshots";
-/** What the pass has on disk, and what it does not. */
-export interface ReferenceScreenshotOutcome {
-    written: {
-        fileName: string;
-        view: string;
-    }[];
-    /**
-     * One entry per reference that is NOT on disk, with the cause stated in `reason`. Covers both
-     * halves of that absence, because the agent's job is the same either way (capture the view under
-     * its own name, with nothing to compare against): a transfer that failed, and a view the cap
-     * dropped before this container was ever asked to fetch it.
-     */
-    missing: {
-        view: string;
-        reason: string;
-    }[];
-    /** Where the written files live, relative to the checkout root. */
-    dir: string;
-}
 /** The relative directory the references are written to (what the prompt points the agent at). */
 export declare const REFERENCE_SCREENSHOT_DIR = ".cat-context/reference-screenshots";
-/**
- * Download the manifest's images into the checkout and report what landed.
- *
- * IDEMPOTENT, and that is load-bearing rather than an optimisation: an agent flow re-enters its
- * workspace once per repair round, so this pass runs several times over one checkout. A file
- * already on disk is counted and never re-fetched, which keeps a later round from spending the
- * budget again AND from reporting a view as absent that pass 1 successfully delivered. A view that
- * MISSED is retried, since the next round is a fresh chance at whatever was transiently down.
- *
- * Never throws: references are an aid to a comparison, not a precondition for running, so a
- * backend outage degrades a UI run to "name your own views" (the documented fallback) rather than
- * failing it. Every miss is carried out on {@link ReferenceScreenshotOutcome.missing} so the caller
- * can say so in the prompt, which is the difference between a design the platform failed to hand
- * over and one that has no such screen.
- */
-export declare function materializeReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec, options?: {
+/** Download this job's capture references. See {@link materializeContextImages}. */
+export declare function materializeReferenceScreenshots(cwd: string, spec: ImageManifestSpec, options?: {
     signal?: AbortSignal;
     fetchImpl?: typeof fetch;
-}): Promise<ReferenceScreenshotOutcome>;
+}): Promise<ContextImageOutcome>;
 /**
  * The whole delivery in one call: download the manifest (when there is one) and answer the prompt
  * block naming what landed, reporting any miss to the operator on the way.
@@ -51,7 +19,7 @@ export declare function materializeReferenceScreenshots(cwd: string, spec: Refer
  * never arrives is otherwise invisible in the run's output: the gallery simply pairs against
  * nothing, months later, with no line anywhere saying why.
  */
-export declare function deliverReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec | undefined, options: {
+export declare function deliverReferenceScreenshots(cwd: string, spec: ImageManifestSpec | undefined, options: {
     signal?: AbortSignal;
     log: Logger;
     fetchImpl?: typeof fetch;
@@ -68,4 +36,4 @@ export declare function deliverReferenceScreenshots(cwd: string, spec: Reference
  * the directory could not be created at all) sends the agent looking for a path that may not even
  * exist, and reads as a platform bug at exactly the moment the platform is already degraded.
  */
-export declare function referenceScreenshotGuidance(outcome: ReferenceScreenshotOutcome): string;
+export declare function referenceScreenshotGuidance(outcome: ContextImageOutcome): string;

package/dist/reference-screenshots.js

@@ -1,130 +1,22 @@
-import { mkdir, stat, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { CONTEXT_DIR, excludeContextDir } from './pi.js';
+import { CONTEXT_DIR } from './pi.js';
+import { materializeContextImages } from './context-images.js';
 // ---------------------------------------------------------------------------
-// REFERENCE DESIGNS on disk: download the images the backend resolved for this task into
-// `.cat-context/reference-screenshots/`, the directory the UI-tester prompt has always named and
-// nothing wrote.
+// REFERENCE DESIGNS on disk for a CAPTURING kind: the images a UI tester compares its own
+// screenshots against, in `.cat-context/reference-screenshots/` — the directory the UI-tester
+// prompt has always named and nothing wrote.
 //
-// The harness MATERIALISES and never decides: which artifact is the reference for which view, and
-// what each file is called, are backend answers that ride the job body. What lives here is the
-// transfer and its failure reporting: a reference the container could not fetch is NAMED to the
-// agent rather than silently missing, because an absent file and a design that has no such screen
-// look identical on disk.
+// The transfer itself lives in `context-images.ts`, shared with the design-picture delivery. What
+// stays here is what makes this manifest a CAPTURE instruction: the directory, and the prompt block
+// telling the tester to name each screenshot after the view it was handed, including the views it
+// was handed no image for.
 // ---------------------------------------------------------------------------
 /** Subdirectory of {@link CONTEXT_DIR} the reference designs are written to. */
 export const REFERENCE_SCREENSHOT_SUBDIR = 'reference-screenshots';
-/** Per-image ceiling, matching the platform's own upload ceiling (16 MiB). */
-const MAX_REFERENCE_BYTES = 16 * 1024 * 1024;
-/** Per-image request timeout. */
-const REQUEST_TIMEOUT_MS = 20_000;
-/**
- * Wall-clock ceiling on the WHOLE pass.
- *
- * Downloading is activity-silent from the watchdog's point of view (no agent stream, no output),
- * and `JOB_INACTIVITY_MS` (10 min) is what kills a job that stops producing. Rather than heartbeat
- * a transfer that should take seconds, the pass is bounded far below that: a slow or wedged blob
- * backend costs the run its references (stated to the agent) instead of costing it the run.
- */
-const TOTAL_BUDGET_MS = 90_000;
-/** How many images are fetched at once. Small on purpose: this is a shared blob backend. */
-const CONCURRENCY = 4;
-/** The cause reported for a view the backend resolved but never sent this job a file for. */
-const OMITTED_REASON = 'not sent to this container (reference limit)';
 /** The relative directory the references are written to (what the prompt points the agent at). */
 export const REFERENCE_SCREENSHOT_DIR = `${CONTEXT_DIR}/${REFERENCE_SCREENSHOT_SUBDIR}`;
-/**
- * Download the manifest's images into the checkout and report what landed.
- *
- * IDEMPOTENT, and that is load-bearing rather than an optimisation: an agent flow re-enters its
- * workspace once per repair round, so this pass runs several times over one checkout. A file
- * already on disk is counted and never re-fetched, which keeps a later round from spending the
- * budget again AND from reporting a view as absent that pass 1 successfully delivered. A view that
- * MISSED is retried, since the next round is a fresh chance at whatever was transiently down.
- *
- * Never throws: references are an aid to a comparison, not a precondition for running, so a
- * backend outage degrades a UI run to "name your own views" (the documented fallback) rather than
- * failing it. Every miss is carried out on {@link ReferenceScreenshotOutcome.missing} so the caller
- * can say so in the prompt, which is the difference between a design the platform failed to hand
- * over and one that has no such screen.
- */
-export async function materializeReferenceScreenshots(cwd, spec, options = {}) {
-    const dir = join(cwd, CONTEXT_DIR, REFERENCE_SCREENSHOT_SUBDIR);
-    const outcome = {
-        written: [],
-        // The backend's own dropped views are missing before a single byte is fetched, and for a cause
-        // no transfer could have changed.
-        missing: spec.omitted.map((view) => ({ view, reason: OMITTED_REASON })),
-        dir: REFERENCE_SCREENSHOT_DIR,
-    };
-    try {
-        await mkdir(dir, { recursive: true });
-    }
-    catch (error) {
-        // Nowhere to write: report every reference as missed rather than half of them, since none of
-        // them can land and the cause is the same for all.
-        for (const file of spec.files)
-            outcome.missing.push({ view: file.view, reason: describe(error) });
-        return sortByManifest(outcome, spec);
-    }
-    const deadline = Date.now() + TOTAL_BUDGET_MS;
-    const queue = [...spec.files];
-    const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
-        for (;;) {
-            const file = queue.shift();
-            if (!file)
-                return;
-            // An earlier pass over this same checkout already delivered it. Checked before the budget so
-            // a fully-delivered set costs one stat per file and no network at all, however long an
-            // earlier round took.
-            if (await alreadyOnDisk(dir, file.fileName)) {
-                outcome.written.push({ fileName: file.fileName, view: file.view });
-                continue;
-            }
-            if (Date.now() >= deadline) {
-                outcome.missing.push({ view: file.view, reason: 'reference download budget exhausted' });
-                continue;
-            }
-            const failure = await downloadOne(dir, spec, file, options);
-            if (failure)
-                outcome.missing.push({ view: file.view, reason: failure });
-            else
-                outcome.written.push({ fileName: file.fileName, view: file.view });
-        }
-    });
-    await Promise.all(workers);
-    // Even a partial set must not reach the agent's PR (same rule as every other context file).
-    await excludeContextDir(cwd);
-    return sortByManifest(outcome, spec);
-}
-/**
- * Order both lists the way the BACKEND composed the set (its own gallery order) rather than the
- * order the transfers happened to finish in, so the list the agent reads is stable across rounds.
- * The dropped views trail the sent ones, having no position in the manifest to sort by.
- */
-function sortByManifest(outcome, spec) {
-    const rank = new Map(spec.files.map((file, index) => [file.view, index]));
-    const at = (view) => rank.get(view) ?? Number.MAX_SAFE_INTEGER;
-    outcome.written.sort((a, b) => at(a.view) - at(b.view));
-    outcome.missing.sort((a, b) => at(a.view) - at(b.view));
-    return outcome;
-}
-/**
- * Whether a previous pass over this checkout already wrote this reference.
- *
- * Non-empty is the test, not mere existence: a zero-length file is what a half-written transfer
- * leaves behind, and treating it as delivered would hand the agent a blank image it reads as a
- * design with nothing on the screen (the same case {@link downloadOne} refuses to write).
- */
-async function alreadyOnDisk(dir, fileName) {
-    try {
-        return (await stat(join(dir, fileName))).size > 0;
-    }
-    catch {
-        // silent-catch-ok: absence is the ordinary answer here (first pass over the checkout), and any
-        // other stat failure is answered the same way — by attempting the download.
-        return false;
-    }
+/** Download this job's capture references. See {@link materializeContextImages}. */
+export function materializeReferenceScreenshots(cwd, spec, options = {}) {
+    return materializeContextImages(cwd, REFERENCE_SCREENSHOT_SUBDIR, spec, options);
 }
 /**
  * The whole delivery in one call: download the manifest (when there is one) and answer the prompt
@@ -148,84 +40,6 @@ export async function deliverReferenceScreenshots(cwd, spec, options) {
     }
     return referenceScreenshotGuidance(outcome);
 }
-/** Fetch and write one reference, answering a failure reason or undefined on success. */
-async function downloadOne(dir, spec, file, options) {
-    const fetchImpl = options.fetchImpl ?? fetch;
-    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
-    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
-    try {
-        const response = await fetchImpl(`${spec.url}/${encodeURIComponent(file.artifactId)}`, {
-            headers: { authorization: `Bearer ${spec.token}` },
-            signal,
-        });
-        if (!response.ok)
-            return `HTTP ${response.status}`;
-        const bytes = await readBounded(response, MAX_REFERENCE_BYTES);
-        if (bytes === 'too-large')
-            return 'reference exceeds size limit';
-        // A zero-length body is a miss, not a file: written out it would be an image the agent opens,
-        // finds empty, and reads as a design with nothing on the screen.
-        if (!bytes.byteLength)
-            return 'empty response';
-        await writeFile(join(dir, file.fileName), bytes);
-        return undefined;
-    }
-    catch (error) {
-        return describe(error);
-    }
-}
-/**
- * Read a response body, refusing one that goes past `limit` WITHOUT buffering all of it first.
- *
- * The ceiling has to bound the transfer and not just the write. Buffering the whole body and then
- * measuring it means an oversized (or endless) response is already resident, times the pass's
- * concurrency, by the time it is rejected — which is the container's memory, in a run whose whole
- * point is that it has not started working yet. So the declared length is refused up front where
- * it is honest, and the stream is counted as it arrives and cancelled the moment it crosses the
- * line, which is what makes a chunked or lying body cost no more than a truthful one.
- */
-async function readBounded(response, limit) {
-    const declared = Number(response.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > limit)
-        return 'too-large';
-    const body = response.body;
-    if (!body) {
-        // No stream to count (a mocked or already-buffered response): fall back to measuring after the
-        // fact, which is sound because there is nothing left to stop arriving.
-        const bytes = new Uint8Array(await response.arrayBuffer());
-        return bytes.byteLength > limit ? 'too-large' : bytes;
-    }
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            total += value.byteLength;
-            if (total > limit) {
-                await reader.cancel();
-                return 'too-large';
-            }
-            chunks.push(value);
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    const bytes = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        bytes.set(chunk, offset);
-        offset += chunk.byteLength;
-    }
-    return bytes;
-}
-/** A one-line cause for a failed transfer (never the token, which only rides a header). */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /**
  * The prompt block naming what the agent was handed, or '' when the pass produced nothing at all.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.104.0",
+  "version": "1.108.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",
@@ -26,13 +26,13 @@
   },
   "devDependencies": {
     "@hono/node-server": "^2.1.0",
-    "@types/node": "^26.1.2",
-    "hono": "^4.13.0",
+    "@types/node": "^26.2.0",
+    "hono": "^4.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.275.0",
-    "@cat-factory/server": "0.255.0",
-    "@cat-factory/spend": "0.15.43"
+    "@cat-factory/kernel": "0.284.0",
+    "@cat-factory/server": "0.267.0",
+    "@cat-factory/spend": "0.15.63"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -343,7 +343,7 @@ export function parseSkillSpecs(value: unknown): SkillSpec[] | undefined {
  * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
  * the whole value of the list is that it is the image's own honest answer.
  */
-export const HARNESS_BODY_CAPABILITIES: readonly string[] = ['mcpServers', 'skills']
+export const HARNESS_BODY_CAPABILITIES: readonly string[] = ['mcpServers', 'skills', 'designImages']
 
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.

package/src/agent-shared.ts

@@ -1,10 +1,4 @@
-import type {
-  AgentJob,
-  AgentResult,
-  McpServerSpec,
-  ReferenceScreenshotsSpec,
-  SkillSpec,
-} from './job.js'
+import type { AgentJob, AgentResult, McpServerSpec, ImageManifestSpec, SkillSpec } from './job.js'
 import type { EffortReport } from './effort.js'
 
 // Small helpers shared by every agent MODE (explore / coding / bootstrap / preview). They live
@@ -33,11 +27,13 @@ export function mergeEffort(
 export function agentCapabilities(job: AgentJob): {
   skills?: SkillSpec[]
   mcpServers?: McpServerSpec[]
-  referenceScreenshots?: ReferenceScreenshotsSpec
+  referenceScreenshots?: ImageManifestSpec
+  designImages?: ImageManifestSpec
 } {
   return {
     ...(job.skills?.length ? { skills: job.skills } : {}),
     ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
     ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
+    ...(job.designImages ? { designImages: job.designImages } : {}),
   }
 }

package/src/coding-agent.ts

@@ -8,7 +8,7 @@ import type {
   HarnessAuthFields,
   PeerRepoSpec,
   ReferenceRepoSpec,
-  ReferenceScreenshotsSpec,
+  ImageManifestSpec,
   RepoSpec,
   SkillSpec,
   McpServerSpec,
@@ -188,7 +188,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * UI-facing kind may well be a coding one, and nothing here switches on which built-in it is.
    * Absent ⇒ none (the normal case).
    */
-  referenceScreenshots?: ReferenceScreenshotsSpec
+  referenceScreenshots?: ImageManifestSpec
+  /**
+   * The PICTURES of the task's designs, downloaded into `.cat-context/design-renders/` before the
+   * agent's first turn. Carried here for the same reason the capture set is: what earns a run its
+   * pictures is the KIND's declared trait plus a harness that can read an image, and a coding kind
+   * is the commonest holder of both. Absent ⇒ none (the normal case).
+   */
+  designImages?: ImageManifestSpec
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -470,6 +477,7 @@ export async function runCodingAgent(
             ...(spec.referenceScreenshots
               ? { referenceScreenshots: spec.referenceScreenshots }
               : {}),
+            ...(spec.designImages ? { designImages: spec.designImages } : {}),
           },
           opts,
         )
@@ -1203,6 +1211,7 @@ export async function runMultiRepoCoding(
           ...(job.skills?.length ? { skills: job.skills } : {}),
           ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
           ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
+          ...(job.designImages ? { designImages: job.designImages } : {}),
           multiRepo: true,
         },
         opts,