@cat-factory/executor-harness 1.106.0 → 1.108.0

package/README.md

@@ -128,6 +128,14 @@ from the backend over the SAME container session token the run already holds for
 this needs no extra credential. The FILE NAMES are the backend's, never derived here: the name is
 how the agent learns the view name, and the platform pairs its capture against that name later.
 
+A job for a kind that BUILDS a screen carries the same wire shape under `designImages`, downloaded
+into `.cat-context/design-renders/` instead. Same transfer, opposite instruction: those are the
+design to build, not the views to capture, which is why they get their own directory (a tester
+reading the builder's handful would take it for the complete list of views to capture). The prompt
+naming them is composed by the BACKEND, since only it knows whether this harness/model pair can be
+shown an image at all and which views the run was not sent, so the harness speaks up only to
+CORRECT that list when a picture did not land.
+
 `omitted` carries the views the backend's cap dropped. They are stated to the agent beside the
 transfers that failed, since from where it stands both are a view to capture with nothing to compare
 against. This parser keeps a higher backstop of its own against a body claiming more files than any
@@ -255,6 +263,8 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic: keyed off the job body, never the agent kind. |
 | `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic: keyed off the job body, never the agent kind. |
 | `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries: the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers): with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
+| `src/context-images.ts` | The TRANSFER half of both image manifests: downloads a manifest's images into a subdirectory of `.cat-context/` on the run's own container session token, bounded per image and per pass, and reports what did not land. Best-effort, time-bounded and IDEMPOTENT over the checkout, so a repair round re-costs a stat rather than a transfer. Shared, because the transfer is identical for both; what differs is what the files MEAN, which is each caller's own module below. |
+| `src/design-images.ts` | The task's DESIGN PICTURES: downloads the manifest a building job body carries into `.cat-context/design-renders/`, for an agent CLI that can read an image into its turn. Says NOTHING on success (the backend's prompt already names every file and its view) and speaks only to correct that list when a picture is not here, because an agent told to open a file that is absent goes looking for the design rather than for the transfer. |
 | `src/reference-screenshots.ts` | The task's REFERENCE DESIGN images: downloads the manifest a capturing job body carries into `.cat-context/reference-screenshots/` (on the run's own container session token) and composes the prompt block naming each file's view. Best-effort, time-bounded and IDEMPOTENT over the checkout, so a repair round re-costs a stat rather than a transfer. A reference that is not on disk is NAMED to the agent, whether a transfer failed or the backend's cap dropped the view, because on disk an absent file and a screen the design does not have are the same thing. Backend-authored throughout, including the file names. |
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |

package/dist/agent-capabilities.js

@@ -241,7 +241,7 @@ export function parseSkillSpecs(value) {
  * 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 = ['mcpServers', 'skills'];
+export const HARNESS_BODY_CAPABILITIES = ['mcpServers', 'skills', 'designImages'];
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *

package/dist/agent-shared.d.ts

@@ -1,4 +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';
 /**
  * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
@@ -16,5 +16,6 @@ export declare function mergeEffort(result: AgentResult, effortReport: EffortRep
 export declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
     mcpServers?: McpServerSpec[];
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    designImages?: ImageManifestSpec;
 };

package/dist/agent-shared.js

@@ -21,5 +21,6 @@ export function agentCapabilities(job) {
         ...(job.skills?.length ? { skills: job.skills } : {}),
         ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
         ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
+        ...(job.designImages ? { designImages: job.designImages } : {}),
     };
 }

package/dist/coding-agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJob, AgentResult, HarnessAuthFields, ReferenceScreenshotsSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { AgentJob, AgentResult, HarnessAuthFields, ImageManifestSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
 import type { HarnessCallMetric } from './pi.js';
 import type { PiRunStats } from './pi-reduction.js';
 import { type EffortReport } from './effort.js';
@@ -119,7 +119,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. */
 export interface CodingAgentOutcome {

package/dist/coding-agent.js

@@ -212,6 +212,7 @@ export async function runCodingAgent(spec, opts = {}) {
             ...(spec.referenceScreenshots
                 ? { referenceScreenshots: spec.referenceScreenshots }
                 : {}),
+            ...(spec.designImages ? { designImages: spec.designImages } : {}),
         }, opts);
         let outcome;
         try {
@@ -812,6 +813,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             ...(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);
         // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.

package/dist/context-images.d.ts

@@ -0,0 +1,38 @@
+import type { ImageManifestSpec } from './job.js';
+/** What a transfer pass has on disk, and what it does not. */
+export interface ContextImageOutcome {
+    written: {
+        fileName: string;
+        view: string;
+    }[];
+    /**
+     * One entry per image that is NOT on disk, with the cause stated in `reason`. Covers both halves
+     * of that absence, because the agent's position is the same either way (this view exists and
+     * there is no picture of it here): a transfer that failed, and a view the backend's own 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;
+}
+/**
+ * Download a manifest's images into `<checkout>/.cat-context/<subdir>/` 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 an image 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: images are an aid, not a precondition for running, so a backend outage degrades the
+ * run to its textual context rather than failing it. Every miss is carried out on
+ * {@link ContextImageOutcome.missing} so the caller can say so in the prompt, which is the
+ * difference between an image the platform failed to hand over and a screen that does not exist.
+ */
+export declare function materializeContextImages(cwd: string, subdir: string, spec: ImageManifestSpec, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}): Promise<ContextImageOutcome>;

package/dist/context-images.js

@@ -0,0 +1,207 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONTEXT_DIR, excludeContextDir } from './pi.js';
+// ---------------------------------------------------------------------------
+// The TRANSFER half of every image manifest: download the images the backend resolved for this job
+// into a subdirectory of `.cat-context/`, and report what did not land.
+//
+// Shared by both manifests (the capture references and the design pictures) because the transfer is
+// the same in every respect that matters here: the same download seam, the same per-image and
+// whole-pass budgets, the same idempotence over a checkout an agent flow re-enters once per repair
+// round, and the same rule that a miss is NAMED rather than silently absent. What differs is what
+// the files mean, which is why each caller owns its own directory and its own prompt block.
+//
+// The harness MATERIALISES and never decides: which artifact belongs to which view, and what each
+// file is called, are backend answers that ride the job body.
+// ---------------------------------------------------------------------------
+/** Per-image ceiling, matching the platform's own upload ceiling (16 MiB). */
+const MAX_IMAGE_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 images (stated to the agent) instead of costing it the run.
+ *
+ * Bounds ONE pass, and a job with both manifests runs two. That is deliberate: the alternative is a
+ * shared budget in which whichever manifest is delivered first can starve the other, which would
+ * make a capture's references depend on how many design pictures the same task happens to hold.
+ */
+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 (image limit)';
+/**
+ * Download a manifest's images into `<checkout>/.cat-context/<subdir>/` 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 an image 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: images are an aid, not a precondition for running, so a backend outage degrades the
+ * run to its textual context rather than failing it. Every miss is carried out on
+ * {@link ContextImageOutcome.missing} so the caller can say so in the prompt, which is the
+ * difference between an image the platform failed to hand over and a screen that does not exist.
+ */
+export async function materializeContextImages(cwd, subdir, spec, options = {}) {
+    const dir = join(cwd, CONTEXT_DIR, 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: `${CONTEXT_DIR}/${subdir}`,
+    };
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (error) {
+        // Nowhere to write: report every image 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: 'image 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 image.
+ *
+ * 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;
+    }
+}
+/** Fetch and write one image, 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_IMAGE_BYTES);
+        if (bytes === 'too-large')
+            return 'image 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);
+}

package/dist/context-manifests.d.ts

@@ -25,12 +25,12 @@ export interface ContextFileSpec {
  * container would let a harness image the deployment has not rolled out yet rename every view a
  * run reports, and the pairing would come apart with nothing failing.
  */
-export interface ReferenceScreenshotsSpec {
+export interface ImageManifestSpec {
     /** Base URL of the reference download route; the artifact id is appended as a path segment. */
     url: string;
     /** The run's container session token (the same one the LLM proxy is called with). */
     token: string;
-    files: ReferenceScreenshotSpec[];
+    files: ImageFileSpec[];
     /**
      * View names the task holds a reference for that this job was NOT sent a file for, because the
      * set was capped. Stated to the agent beside the transfers that failed: from where it stands
@@ -43,8 +43,8 @@ export interface ReferenceScreenshotsSpec {
      */
     omitted: string[];
 }
-/** One reference image in a {@link ReferenceScreenshotsSpec}. `fileName` is sanitised on parse. */
-export interface ReferenceScreenshotSpec {
+/** One reference image in a {@link ImageManifestSpec}. `fileName` is sanitised on parse. */
+export interface ImageFileSpec {
     artifactId: string;
     fileName: string;
     view: string;
@@ -58,12 +58,14 @@ export declare function sanitizeContextFileName(value: unknown): string | undefi
 /** Parse the linked-context files, dropping any malformed/unsafe entry. */
 export declare function parseContextFiles(value: unknown): ContextFileSpec[];
 /**
- * Parse the reference-design manifest, or undefined when absent/unusable.
+ * Parse one image manifest (the capture set or the design pictures), or undefined when
+ * absent/unusable.
  *
- * The whole manifest is dropped when its transport half is unusable (no absolute http(s) URL, no
- * token): every file would fail the same way, and one stated cause beats N identical ones. An
- * individual entry is dropped only when it cannot name a file safely: the same basename
- * sanitisation every context file gets, so a hostile `fileName` can neither escape the directory
- * nor clobber a repo file.
+ * ONE parser for both, because the wire shape and every rule over it are the same: only the job
+ * body FIELD and what the harness does with the files afterwards differ. The whole manifest is
+ * dropped when its transport half is unusable (no absolute http(s) URL, no token): every file
+ * would fail the same way, and one stated cause beats N identical ones. An individual entry is
+ * dropped only when it cannot name a file safely: the same basename sanitisation every context
+ * file gets, so a hostile `fileName` can neither escape the directory nor clobber a repo file.
  */
-export declare function parseReferenceScreenshots(value: unknown): ReferenceScreenshotsSpec | undefined;
+export declare function parseImageManifest(value: unknown): ImageManifestSpec | undefined;

package/dist/context-manifests.js

@@ -48,26 +48,33 @@ export function parseContextFiles(value) {
     return files;
 }
 /**
- * How many reference images one job may be handed. The backend caps the set it sends well below
- * this, so this is the harness's own backstop against a malformed or hostile body turning the
- * pre-run setup into an unbounded download, never the ceiling a real run meets.
+ * How many images one job may be handed PER MANIFEST. The backend caps each set it sends well
+ * below this, so this is the harness's own backstop against a malformed or hostile body turning
+ * the pre-run setup into an unbounded download, never the ceiling a real run meets.
+ *
+ * One number for both manifests on purpose: the two real ceilings are the BACKEND's, chosen where
+ * the reason for each is known (transfer time for a capture, input tokens for an attachment). A
+ * second backstop here would only encode those reasons a second time, in the one place that
+ * cannot see either.
  *
  * Hitting it is REPORTED rather than silently obeyed: an entry past the ceiling is dropped from
  * `files` and its view named on `omitted`, so an agent facing a truncated set is still told which
- * views to capture. A cap that shortened the list and said nothing would be indistinguishable, on
- * disk and in the prompt, from a design that simply has no such screen.
+ * views it is not being shown. A cap that shortened the list and said nothing would be
+ * indistinguishable, on disk and in the prompt, from a design that simply has no such screen.
  */
-const MAX_REFERENCE_SCREENSHOTS = 40;
+const MAX_MANIFEST_IMAGES = 40;
 /**
- * Parse the reference-design manifest, or undefined when absent/unusable.
+ * Parse one image manifest (the capture set or the design pictures), or undefined when
+ * absent/unusable.
  *
- * The whole manifest is dropped when its transport half is unusable (no absolute http(s) URL, no
- * token): every file would fail the same way, and one stated cause beats N identical ones. An
- * individual entry is dropped only when it cannot name a file safely: the same basename
- * sanitisation every context file gets, so a hostile `fileName` can neither escape the directory
- * nor clobber a repo file.
+ * ONE parser for both, because the wire shape and every rule over it are the same: only the job
+ * body FIELD and what the harness does with the files afterwards differ. The whole manifest is
+ * dropped when its transport half is unusable (no absolute http(s) URL, no token): every file
+ * would fail the same way, and one stated cause beats N identical ones. An individual entry is
+ * dropped only when it cannot name a file safely: the same basename sanitisation every context
+ * file gets, so a hostile `fileName` can neither escape the directory nor clobber a repo file.
  */
-export function parseReferenceScreenshots(value) {
+export function parseImageManifest(value) {
     if (typeof value !== 'object' || value === null)
         return undefined;
     const o = value;
@@ -97,7 +104,7 @@ export function parseReferenceScreenshots(value) {
         // Past the backstop the entry is NAMED, not dropped: it stays a view the agent must capture.
         // Checked here rather than at the top of the loop so a malformed entry is refused on its own
         // terms (it names no usable view to report) instead of being counted against the ceiling.
-        if (files.length >= MAX_REFERENCE_SCREENSHOTS) {
+        if (files.length >= MAX_MANIFEST_IMAGES) {
             omitted.push(view);
             continue;
         }

package/dist/design-images.d.ts

@@ -0,0 +1,40 @@
+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 design pictures are written to. */
+export declare const DESIGN_RENDER_SUBDIR = "design-renders";
+/** The relative directory the design pictures are written to (what the prompt names). */
+export declare const DESIGN_RENDER_DIR = ".cat-context/design-renders";
+/** Download this job's design pictures. See {@link materializeContextImages}. */
+export declare function materializeDesignImages(cwd: string, spec: ImageManifestSpec, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}): Promise<ContextImageOutcome>;
+/**
+ * Download the design pictures and answer the CORRECTION to the prompt's own list, or '' when
+ * everything the backend named is on disk.
+ *
+ * Silence on success is the difference from the capture delivery, and it is deliberate. The
+ * backend's prompt already names every picture and its view, because it is the side that knows
+ * which views exist and how they were delivered; repeating the list here would give the agent two
+ * lists of the same files, differing only when something went wrong, with nothing saying which one
+ * is current.
+ *
+ * So this speaks only when the container's truth DIVERGES from what the prompt promised. That
+ * divergence has to be stated: an agent told to open a file that is not there re-reads the path,
+ * lists the directory and eventually decides the design is missing something, when the honest
+ * answer is that this one picture did not transfer and the rest are exactly as described.
+ */
+export declare function deliverDesignImages(cwd: string, spec: ImageManifestSpec | undefined, options: {
+    signal?: AbortSignal;
+    log: Logger;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+/**
+ * The prompt correction: the views whose picture is NOT in this container, with the cause.
+ *
+ * Empty whenever the transfer matched the prompt, including the case where the manifest was empty
+ * to begin with. The agent is told to carry on from the textual design description rather than to
+ * ask for the file, because nothing in the run can deliver it after this point.
+ */
+export declare function designImageGuidance(outcome: ContextImageOutcome): string;

package/dist/design-images.js

@@ -0,0 +1,68 @@
+import { CONTEXT_DIR } from './pi.js';
+import { materializeContextImages } from './context-images.js';
+// ---------------------------------------------------------------------------
+// DESIGN PICTURES on disk for a BUILDING kind: what the screen is supposed to look like, in
+// `.cat-context/design-renders/`, for an agent CLI that can read an image into its turn.
+//
+// The other use of the same artifacts the capture path delivers, and the reason each has its own
+// directory: a tester reading these six would take them for the complete list of views to capture,
+// and a builder reading the tester's twenty-four would spend its context on screens it was never
+// asked to touch.
+//
+// The agent is told about these files by the BACKEND's prompt, which is the half that knows which
+// views the platform holds and whether this model can be shown them at all. What this module adds
+// is the container's own half of the truth: which of those files actually landed here.
+// ---------------------------------------------------------------------------
+/** Subdirectory of {@link CONTEXT_DIR} the design pictures are written to. */
+export const DESIGN_RENDER_SUBDIR = 'design-renders';
+/** The relative directory the design pictures are written to (what the prompt names). */
+export const DESIGN_RENDER_DIR = `${CONTEXT_DIR}/${DESIGN_RENDER_SUBDIR}`;
+/** Download this job's design pictures. See {@link materializeContextImages}. */
+export function materializeDesignImages(cwd, spec, options = {}) {
+    return materializeContextImages(cwd, DESIGN_RENDER_SUBDIR, spec, options);
+}
+/**
+ * Download the design pictures and answer the CORRECTION to the prompt's own list, or '' when
+ * everything the backend named is on disk.
+ *
+ * Silence on success is the difference from the capture delivery, and it is deliberate. The
+ * backend's prompt already names every picture and its view, because it is the side that knows
+ * which views exist and how they were delivered; repeating the list here would give the agent two
+ * lists of the same files, differing only when something went wrong, with nothing saying which one
+ * is current.
+ *
+ * So this speaks only when the container's truth DIVERGES from what the prompt promised. That
+ * divergence has to be stated: an agent told to open a file that is not there re-reads the path,
+ * lists the directory and eventually decides the design is missing something, when the honest
+ * answer is that this one picture did not transfer and the rest are exactly as described.
+ */
+export async function deliverDesignImages(cwd, spec, options) {
+    if (!spec)
+        return '';
+    const outcome = await materializeDesignImages(cwd, spec, options);
+    if (outcome.missing.length) {
+        options.log.warn('agent: some design pictures are not on disk', {
+            written: outcome.written.length,
+            missing: outcome.missing.length,
+            reasons: outcome.missing.map((file) => file.reason).slice(0, 5),
+        });
+    }
+    return designImageGuidance(outcome);
+}
+/**
+ * The prompt correction: the views whose picture is NOT in this container, with the cause.
+ *
+ * Empty whenever the transfer matched the prompt, including the case where the manifest was empty
+ * to begin with. The agent is told to carry on from the textual design description rather than to
+ * ask for the file, because nothing in the run can deliver it after this point.
+ */
+export function designImageGuidance(outcome) {
+    if (!outcome.missing.length)
+        return '';
+    return `
+
+## Design pictures: correction
+These views were listed above as pictures, and are NOT in this container. Work from the textual
+design description for them; there is nothing to open and nothing that can fetch them now:
+${outcome.missing.map((file) => `- ${file.view}: NOT on disk (${file.reason})`).join('\n')}`;
+}

package/dist/job-images.d.ts

@@ -0,0 +1,28 @@
+import type { ImageManifestSpec } from './job.js';
+import type { Logger } from './logger.js';
+/** The manifests a job may carry, as they sit on any agent-running spec. */
+export interface JobImageSpecs {
+    referenceScreenshots?: ImageManifestSpec;
+    designImages?: ImageManifestSpec;
+}
+/**
+ * Deliver both manifests into the checkout and answer the prompt text they contribute.
+ *
+ * The two blocks are CONCATENATED rather than kept apart because they say the same kind of thing
+ * (what this container actually holds, against what the run was told it would), and the agent reads
+ * one context. Either half is empty when its manifest is absent or when nothing needs saying, so a
+ * job with one manifest is byte-identical to what it produced before the other existed.
+ *
+ * Runs once per PASS, not once per job: a coding flow re-enters its workspace for every repair
+ * round. That is safe because each delivery is idempotent over the checkout (a file already on disk
+ * is counted, never re-fetched), so a later round costs a stat per image and 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.
+ */
+export declare function deliverJobImages(spec: JobImageSpecs & {
+    dir: string;
+}, options: {
+    signal?: AbortSignal;
+    log: Logger;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;

package/dist/job-images.js

@@ -0,0 +1,21 @@
+import { deliverDesignImages } from './design-images.js';
+import { deliverReferenceScreenshots } from './reference-screenshots.js';
+/**
+ * Deliver both manifests into the checkout and answer the prompt text they contribute.
+ *
+ * The two blocks are CONCATENATED rather than kept apart because they say the same kind of thing
+ * (what this container actually holds, against what the run was told it would), and the agent reads
+ * one context. Either half is empty when its manifest is absent or when nothing needs saying, so a
+ * job with one manifest is byte-identical to what it produced before the other existed.
+ *
+ * Runs once per PASS, not once per job: a coding flow re-enters its workspace for every repair
+ * round. That is safe because each delivery is idempotent over the checkout (a file already on disk
+ * is counted, never re-fetched), so a later round costs a stat per image and 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.
+ */
+export async function deliverJobImages(spec, options) {
+    const references = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, options);
+    const designs = await deliverDesignImages(spec.dir, spec.designImages, options);
+    return `${references}${designs}`;
+}