@cat-factory/executor-harness 1.106.0 → 1.110.0

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.106.0",
+  "version": "1.110.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.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.279.2",
-    "@cat-factory/server": "0.260.2",
-    "@cat-factory/spend": "0.15.53"
+    "@cat-factory/kernel": "0.285.0",
+    "@cat-factory/server": "0.268.0",
+    "@cat-factory/spend": "0.15.64"
   },
   "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/agent.ts

@@ -30,7 +30,8 @@ import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js'
 import { applyPrDescription } from './pr-description.js'
 import { makeDirClaimer } from './checkout-dir.js'
-import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js'
+import { noChangesReason, runCodingAgent } from './coding-agent.js'
+import { runMultiRepoCoding } from './multi-repo-coding.js'
 import { validationFailureMessage } from './validation-checks.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
 import { agentCapabilities, mergeEffort } from './agent-shared.js'