@cat-factory/executor-harness 1.106.0 → 1.110.0

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}`;
+}

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
@@ -86,8 +86,13 @@ export interface PrSpec {
  */
 export interface PeerRepoSpec {
     repo: RepoSpec;
-    /** The involved service frame this repo resolved from, echoed back on the peer PR. */
-    frameId?: string;
+    /**
+     * The involved service frames this repo resolved from, echoed back on the peer PR verbatim.
+     * More than one when the peer is a monorepo hosting several of the run's involved services:
+     * they share this ONE checkout, its work branch and its pull request. Opaque to the harness,
+     * which decides no frame attribution of its own.
+     */
+    frameIds?: string[];
     /**
      * The work branch to create off the peer's base and push (the shared `cat-factory/<block>`).
      * Present for a COING fan-out (coder / ci-fixer). Absent for a READ-ONLY explore fan-out
@@ -320,11 +325,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
@@ -581,10 +598,14 @@ export interface AgentResult {
      * repo the run actually changed (service-connections phase 3). Beside the own-service
      * `prUrl`/`branch`; the backend lifts these onto the block's `peerPullRequests`. Absent for
      * a single-repo run.
+     *
+     * `frameIds` is the dispatch's own attribution echoed back untouched (see
+     * {@link PeerRepoSpec.frameIds}): one entry per repo, carrying every involved frame that
+     * repo hosts.
      */
     peerPullRequests?: {
         repo: string;
-        frameId?: string;
+        frameIds?: string[];
         prUrl: string;
         branch: string;
     }[];

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
@@ -169,8 +169,11 @@ function parsePeerRepos(value) {
         if (e.cloneBranch !== undefined) {
             spec.cloneBranch = str(e.cloneBranch, `peerRepos[${i}].cloneBranch`);
         }
-        if (typeof e.frameId === 'string' && e.frameId)
-            spec.frameId = e.frameId;
+        if (Array.isArray(e.frameIds)) {
+            const frameIds = e.frameIds.filter((f) => typeof f === 'string' && !!f);
+            if (frameIds.length)
+                spec.frameIds = frameIds;
+        }
         if (typeof e.ghToken === 'string' && e.ghToken)
             spec.ghToken = e.ghToken;
         if (typeof e.pr === 'object' && e.pr !== null) {
@@ -478,7 +481,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 +549,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 +566,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/multi-repo-coding.d.ts

@@ -0,0 +1,16 @@
+import type { AgentJob, AgentResult } from './job.js';
+import type { RunOptions } from './runner.js';
+/**
+ * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
+ * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
+ * that root (so it makes the cross-service change coherently across all of them), then commit +
+ * push each repo that actually changed and open one PR per dirty repo. The task's own-service PR
+ * is reported as `prUrl`/`branch`; the peer PRs as `peerPullRequests`.
+ *
+ * Deliberately simpler than the single-repo {@link runCodingAgent} for the first cut: NO mid-run
+ * checkpoint pushes (an evicted multi-repo run re-clones on retry — the deterministic work branch
+ * still lets it resume any commits it managed to push at the end), NO warm-pool persistent
+ * checkout (always ephemeral), and NO follow-up sentinel streaming. It reuses the SAME dir-scoped
+ * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
+ */
+export declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;