ravensight-playtest 0.5.2 → 0.6.0

package/src/api/http.js

@@ -1,4 +1,4 @@
-import { ApiError, codeRetryLimit, isRetryable, parseRetryAfter } from './errors.js';
+import { ApiError, codeRetryLimit, isRetryable, nothingMoved, parseRetryAfter } from './errors.js';
 
 export const DEFAULT_RETRIES = 4;
 export const DEFAULT_TIMEOUT_MS = 30000;
@@ -42,12 +42,18 @@ export function buildUrl(apiUrl, path, query) {
   return url.toString();
 }
 
+/** Carries a capture hook's own error past the request loop's network catch. */
+class CaptureFailure {
+  constructor(error) { this.error = error; }
+}
+
 /**
  * Read a response body without throwing for body or JSON decoding errors. A 502 from a load balancer is
  * HTML, a 204 is empty, and a JSON parse failure on the error path would
- * replace a useful status code with a useless SyntaxError.
+ * replace a useful status code with a useless SyntaxError. `cut` says the connection
+ * went before the body finished, which is not the same as an empty body.
  * @param {Response} response
- * @returns {Promise<{json: unknown, text: string}>}
+ * @returns {Promise<{json: unknown, text: string, cut?: Error}>}
  */
 async function readBody(response, onResponseRaw) {
   let text = '';
@@ -57,12 +63,22 @@ async function readBody(response, onResponseRaw) {
     catch { /* Preserve a read-failure observation, never invent complete bytes. */ }
     // Opt-in capture runs on every HTTP status BEFORE JSON parsing or an
     // ApiError. Capture failures propagate and cannot trigger a request retry.
-    await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    try {
+      await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    } catch (error) {
+      throw new CaptureFailure(error);
+    }
+    // A capture caller owns an incomplete body: the observation says so, and it
+    // must decide from that record (an admission never POSTs again on an unknown
+    // outcome), so this is not turned into a retryable network error.
     if (!bodyComplete) return { json: null, text: '' };
     text = new TextDecoder().decode(bytes);
   } else {
-    try { text = await response.text(); }
-    catch { return { json: null, text: '' }; }
+    try {
+      text = await response.text();
+    } catch (cause) {
+      return { json: null, text: '', cut: cause };
+    }
   }
   if (!text) return { json: null, text: '' };
   try {
@@ -95,7 +111,8 @@ function errorFrom(response, parsed, { method, path }) {
  * Retries cover a network failure, a timeout, 408, 425, 429 and 5xx, plus the
  * two error codes whose status alone gives the wrong answer (see
  * `codeRetryLimit`): `charge_in_progress` is retried on its own `Retry-After`
- * although it is a 409, and `too_many_active_jobs` is not retried although it
+ * although it is a 409, `settle_contended` likewise and on any method because it
+ * promises nothing moved, and `too_many_active_jobs` is not retried although it
  * is a 429. A mutation is only ever retried when the caller says
  * `idempotent: true`, which in practice means a GET, a heartbeat, or a POST
  * carrying an `Idempotency-Key` the server uses to replay rather than repeat.
@@ -150,7 +167,16 @@ export async function requestWithRetry(options) {
   for (let attempt = 1; ; attempt += 1) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const unreachable = cause => new ApiError({
+      status: 0,
+      code: 'network_error',
+      message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
+      method,
+      path,
+      cause
+    });
     let response = null;
+    let parsed = null;
     try {
       response = await fetchImpl(url, {
         method,
@@ -158,21 +184,21 @@ export async function requestWithRetry(options) {
         body: bodyText === undefined ? undefined : bodyText,
         signal: controller.signal
       });
+      // The time limit covers the body too, and a success whose body never finished
+      // is no answer: reading it as an empty 200 lost the job id of a job just charged.
+      parsed = await readBody(response, onResponseRaw);
+      if (parsed.cut) {
+        lastError = unreachable(parsed.cut);
+        response = null;
+      }
     } catch (cause) {
-      lastError = new ApiError({
-        status: 0,
-        code: 'network_error',
-        message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
-        method,
-        path,
-        cause
-      });
+      if (cause instanceof CaptureFailure) throw cause.error;
+      lastError = unreachable(cause);
     } finally {
       clearTimeout(timer);
     }
 
     if (response) {
-      const parsed = await readBody(response, onResponseRaw);
       if (response.ok || response.status === 304) {
         return {
           status: response.status,
@@ -183,7 +209,7 @@ export async function requestWithRetry(options) {
       lastError = errorFrom(response, parsed, { method, path });
     }
 
-    if (!retryable) throw lastError;
+    if (!retryable && !nothingMoved(lastError)) throw lastError;
 
     const limit = codeRetryLimit(lastError);
     let canRetry;

package/src/assets/formats.js

@@ -0,0 +1,267 @@
+import { inflateSync } from 'node:zlib';
+
+/**
+ * Plain parsers for the three formats the inventory measures closely: PNG, WAV
+ * and Ogg. No dependency, because this runs inside a CLI that ships with few, and
+ * none of these needs more than a header and, for PNG, one inflate.
+ *
+ * Each parser answers what it read and `problem` when the file is damaged, and
+ * never throws on hostile bytes: a studio's folder can hold anything.
+ */
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Above this the pixels are not decoded: the header still answers the size. */
+export const MAX_DECODED_PIXELS = 64 * 1024 * 1024;
+
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const VALID_DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+/**
+ * The PNG's chunks up to IEND, without decoding the pixels.
+ *
+ * @param {Buffer} data
+ * @returns {{width: number, height: number, bitDepth: number, colorType: number, interlaced: boolean, palette: Buffer|null, transparency: Buffer|null, idat: Buffer[], problem: string|null}|null} null when it is not a PNG at all
+ */
+export function readPngHeader(data) {
+  if (data.length < 33 || !data.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  const out = { width: 0, height: 0, bitDepth: 0, colorType: 0, interlaced: false, palette: null, transparency: null, idat: [], problem: null };
+  let at = 8;
+  let sawHeader = false;
+  let sawEnd = false;
+  while (at + 8 <= data.length) {
+    const length = data.readUInt32BE(at);
+    const type = data.toString('latin1', at + 4, at + 8);
+    const start = at + 8;
+    if (start + length > data.length) {
+      out.problem = `the ${type} chunk runs past the end of the file`;
+      break;
+    }
+    const body = data.subarray(start, start + length);
+    if (type === 'IHDR') {
+      if (length < 13) return { ...out, problem: 'the image header is too short' };
+      out.width = body.readUInt32BE(0);
+      out.height = body.readUInt32BE(4);
+      out.bitDepth = body[8];
+      out.colorType = body[9];
+      out.interlaced = body[12] === 1;
+      sawHeader = true;
+    } else if (type === 'PLTE') out.palette = body;
+    else if (type === 'tRNS') out.transparency = body;
+    else if (type === 'IDAT') out.idat.push(body);
+    else if (type === 'IEND') { sawEnd = true; break; }
+    at = start + length + 4;
+  }
+  if (!sawHeader) return { ...out, problem: out.problem || 'there is no image header' };
+  if (!(VALID_DEPTHS[out.colorType] || []).includes(out.bitDepth)) return { ...out, problem: 'the colour type and bit depth are not valid together' };
+  if (!sawEnd && !out.problem) out.problem = 'the file ends before the image does';
+  return out;
+}
+
+/** The Paeth predictor, from the PNG specification. */
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/**
+ * Decode a non-interlaced PNG to 8-bit RGBA.
+ *
+ * @param {ReturnType<typeof readPngHeader>} header
+ * @returns {{width: number, height: number, rgba: Uint8Array}|{problem: string}|null} null for what is
+ *   not decoded on purpose: interlaced, or over MAX_DECODED_PIXELS
+ */
+export function decodePng(header) {
+  const { width, height, bitDepth, colorType } = header;
+  if (header.interlaced || width * height > MAX_DECODED_PIXELS || width * height === 0) return null;
+  const channels = CHANNELS[colorType];
+  const stride = Math.ceil((width * channels * bitDepth) / 8);
+  const bytesPerPixel = Math.max(1, (channels * bitDepth) >> 3);
+  const expected = (stride + 1) * height;
+  let raw;
+  try {
+    raw = inflateSync(Buffer.concat(header.idat), { maxOutputLength: expected + 1024 });
+  } catch {
+    return { problem: 'the pixel data does not decompress' };
+  }
+  if (raw.length < expected) return { problem: 'the pixel data is shorter than the image' };
+
+  const line = new Uint8Array(stride);
+  const previous = new Uint8Array(stride);
+  const rgba = new Uint8Array(width * height * 4);
+  const palette = header.palette;
+  const alphas = header.transparency;
+  const keyed = colorType !== 3 && alphas && alphas.length >= (colorType === 0 ? 2 : 6) ? alphas : null;
+  for (let y = 0; y < height; y += 1) {
+    const offset = y * (stride + 1);
+    const filter = raw[offset];
+    if (filter > 4) return { problem: 'a row of pixels has an unknown filter' };
+    for (let x = 0; x < stride; x += 1) {
+      const value = raw[offset + 1 + x];
+      const a = x >= bytesPerPixel ? line[x - bytesPerPixel] : 0;
+      const b = previous[x];
+      const c = x >= bytesPerPixel ? previous[x - bytesPerPixel] : 0;
+      let out = value;
+      if (filter === 1) out = value + a;
+      else if (filter === 2) out = value + b;
+      else if (filter === 3) out = value + ((a + b) >> 1);
+      else if (filter === 4) out = value + paeth(a, b, c);
+      line[x] = out & 0xff;
+    }
+    for (let x = 0; x < width; x += 1) {
+      const to = (y * width + x) * 4;
+      if (colorType === 3 || (colorType === 0 && bitDepth < 8)) {
+        const bitAt = x * bitDepth;
+        const sample = (line[bitAt >> 3] >> (8 - bitDepth - (bitAt & 7))) & ((1 << bitDepth) - 1);
+        if (colorType === 3) {
+          rgba[to] = palette ? palette[sample * 3] : 0;
+          rgba[to + 1] = palette ? palette[sample * 3 + 1] : 0;
+          rgba[to + 2] = palette ? palette[sample * 3 + 2] : 0;
+          rgba[to + 3] = alphas && sample < alphas.length ? alphas[sample] : 255;
+        } else {
+          const grey = Math.round((sample * 255) / ((1 << bitDepth) - 1));
+          rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+          rgba[to + 3] = keyed && keyed.readUInt16BE(0) === sample ? 0 : 255;
+        }
+        continue;
+      }
+      // At 16 bits the high byte of each sample is what a screen shows.
+      const step = bitDepth === 16 ? 2 : 1;
+      const from = x * channels * step;
+      if (colorType === 0 || colorType === 4) {
+        const grey = line[from];
+        rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+        rgba[to + 3] = colorType === 4 ? line[from + step]
+          : (keyed && (bitDepth === 16 ? (line[from] << 8) | line[from + 1] : line[from]) === keyed.readUInt16BE(0) ? 0 : 255);
+      } else {
+        rgba[to] = line[from];
+        rgba[to + 1] = line[from + step];
+        rgba[to + 2] = line[from + step * 2];
+        if (colorType === 6) rgba[to + 3] = line[from + step * 3];
+        else {
+          const sample = i => (bitDepth === 16 ? (line[from + i * 2] << 8) | line[from + i * 2 + 1] : line[from + i]);
+          rgba[to + 3] = keyed && sample(0) === keyed.readUInt16BE(0) && sample(1) === keyed.readUInt16BE(2) && sample(2) === keyed.readUInt16BE(4) ? 0 : 255;
+        }
+      }
+    }
+    previous.set(line);
+  }
+  return { width, height, rgba };
+}
+
+/** Whether a PNG can carry transparency at all, from its header. */
+export function pngHasAlphaChannel(header) {
+  return header.colorType === 4 || header.colorType === 6 || Boolean(header.transparency);
+}
+
+const WAV_FORMATS = { 1: 'pcm', 3: 'float', 6: 'a-law', 7: 'mu-law' };
+
+/**
+ * A WAV's format and length, from its `fmt ` and `data` chunks.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, extensible: boolean, channels: number, sampleRate: number, bitsPerSample: number, durationSeconds: number|null, problem: string|null}|null} null when it is not a WAV
+ */
+export function parseWav(data) {
+  if (data.length < 12 || data.toString('latin1', 0, 4) !== 'RIFF' || data.toString('latin1', 8, 12) !== 'WAVE') return null;
+  let at = 12;
+  let format = null;
+  let dataBytes = null;
+  let problem = null;
+  while (at + 8 <= data.length) {
+    const id = data.toString('latin1', at, at + 4);
+    const length = data.readUInt32LE(at + 4);
+    const start = at + 8;
+    if (id === 'fmt ' && start + 16 <= data.length) {
+      const tag = data.readUInt16LE(start);
+      // An extensible header names the real format in the first bytes of its subformat.
+      const extended = tag === 0xfffe && start + 26 <= data.length ? data.readUInt16LE(start + 24) : null;
+      format = {
+        tag: extended ?? tag,
+        extensible: tag === 0xfffe,
+        channels: data.readUInt16LE(start + 2),
+        sampleRate: data.readUInt32LE(start + 4),
+        byteRate: data.readUInt32LE(start + 8),
+        bitsPerSample: data.readUInt16LE(start + 14)
+      };
+    } else if (id === 'data') {
+      dataBytes = length;
+      if (start + length > data.length) {
+        dataBytes = data.length - start;
+        problem = 'the sound data runs past the end of the file';
+      }
+      break;
+    }
+    at = start + length + (length & 1);
+  }
+  if (!format) return { codec: 'unknown', extensible: false, channels: 0, sampleRate: 0, bitsPerSample: 0, durationSeconds: null, problem: 'there is no format chunk' };
+  if (dataBytes === null) problem = problem || 'there is no sound data';
+  return {
+    codec: WAV_FORMATS[format.tag] || `format ${format.tag}`,
+    extensible: format.extensible,
+    channels: format.channels,
+    sampleRate: format.sampleRate,
+    bitsPerSample: format.bitsPerSample,
+    durationSeconds: dataBytes !== null && format.byteRate > 0 ? dataBytes / format.byteRate : null,
+    problem
+  };
+}
+
+/** One Ogg page: its header fields and where its body sits. */
+function oggPageAt(data, at) {
+  if (at + 27 > data.length || data.toString('latin1', at, at + 4) !== 'OggS') return null;
+  const segments = data[at + 26];
+  if (at + 27 + segments > data.length) return null;
+  let size = 0;
+  for (let i = 0; i < segments; i += 1) size += data[at + 27 + i];
+  return { granule: data.readBigInt64LE(at + 6), serial: data.readUInt32LE(at + 14), bodyStart: at + 27 + segments, next: at + 27 + segments + size };
+}
+
+/**
+ * An Ogg's codec and length: the first page names the codec, and the last page's
+ * granule position is how far the stream got. Vorbis counts samples; Opus counts
+ * at 48 kHz, less its pre-skip.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, channels: number, sampleRate: number, bitsPerSample: null, durationSeconds: number|null, problem: string|null}|null} null when it is not an Ogg
+ */
+export function parseOgg(data) {
+  const first = oggPageAt(data, 0);
+  if (!first) return null;
+  const body = data.subarray(first.bodyStart, first.next);
+  const out = { codec: 'unknown', channels: 0, sampleRate: 0, bitsPerSample: null, durationSeconds: null, problem: null };
+  let ticksPerSecond = 0;
+  let skip = 0;
+  if (body.length >= 30 && body[0] === 1 && body.toString('latin1', 1, 7) === 'vorbis') {
+    out.codec = 'vorbis';
+    out.channels = body[11];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = out.sampleRate;
+  } else if (body.length >= 19 && body.toString('latin1', 0, 8) === 'OpusHead') {
+    out.codec = 'opus';
+    out.channels = body[9];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = 48000;
+    skip = body.readUInt16LE(10);
+  } else {
+    out.problem = 'the first page does not name a codec this reads';
+    return out;
+  }
+  let at = 0;
+  let lastGranule = -1n;
+  for (;;) {
+    const page = oggPageAt(data, at);
+    if (!page || page.next > data.length) break;
+    if (page.serial === first.serial && page.granule >= 0n) lastGranule = page.granule;
+    at = page.next;
+  }
+  if (at < data.length) out.problem = 'the file ends part way through a page';
+  if (lastGranule >= 0n && ticksPerSecond > 0) out.durationSeconds = Math.max(0, Number(lastGranule) - skip) / ticksPerSecond;
+  return out;
+}
+
+export default { readPngHeader, decodePng, pngHasAlphaChannel, parseWav, parseOgg, MAX_DECODED_PIXELS };

package/src/assets/index.js

@@ -0,0 +1,260 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { checkResultText, RUN_CHECK_TOOL } from '../run/checks.js';
+import { ASSET_CHECK_NAMES, createAssetChecks, scanUsage } from './integration.js';
+import { buildInventory, countsLine, DEFAULT_ASSETS_DIR, describeFile, isMediaPath, manifestText, warningKinds } from './inventory.js';
+
+/**
+ * Bring your own assets: the one seam the feature and create loops call.
+ *
+ *   const assets = await prepareAssets({ repoRoot, projectDir, folder, grid });
+ *   if (!assets.ok) refuse with assets.reason, before any charge
+ *
+ *   plan prompt:   ...assets.planLines
+ *   apply prompt:  ...assets.instructions
+ *   repo tools:    assets.guardRepo(createRepoTools(...))            plan and apply
+ *   after checks:  const bound = assets.bindChecks({ checks, changedFiles, ... })
+ *   apply tools:   bound.withChecks(withRunCheck(guardedRepo, checks))
+ *   gate:          const gate = await bound.gate(await runGateChecks(checks, log), log)
+ *                  a failure joins gate.failed; gate.assetsBlock blocks the upload
+ *   placeholders:  assets.placeholders(plan, spec)
+ *   report:        const summary = await assets.report({ runDir, changed, placeholders, log })
+ *                  summary.reportLines go in the uploaded report
+ *
+ * The studio's files stay where they are. The server stores none of them, there is
+ * no price of its own, and nothing is generated. The manifest reaches the model
+ * through the same proxy every read does; the report that uploads carries counts
+ * and kinds of warning only, and the file-by-file list stays in the run directory.
+ */
+
+/** The path the model reads the manifest at. It is answered from memory: no file is written there. */
+export const MANIFEST_PATH = '.ravensight/assets.json';
+
+/** Written beside a run. Neither is on the upload allowlist, so neither can leave. */
+export const LOCAL_REPORT_FILE = 'assets-report.md';
+export const LOCAL_MANIFEST_FILE = 'assets.json';
+
+const REFUSED_CONTENT = file => `Refused: ${file} is an art or audio file. Its content is never read or sent. Its measurements are in ${MANIFEST_PATH}.`;
+const REFUSED_WRITE = file => `Refused: ${file} is the studio's art or audio. You cannot make or change those: use what ${MANIFEST_PATH} lists, or a placeholder primitive named in placeholders.`;
+
+function refusal(id, text) {
+  return { result: { type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], is_error: true } };
+}
+
+function inFolder(file, folder) {
+  // Case blind: on macOS and Windows `ART/hero.tres` is `art/hero.tres`.
+  const normal = path.posix.normalize(String(file).split(path.sep).join('/')).replace(/^\.\//, '').toLowerCase();
+  const declared = folder ? folder.toLowerCase() : folder;
+  return declared && (normal === declared || normal.startsWith(`${declared}/`));
+}
+
+/**
+ * Repository tools that know about assets. The manifest can be read, art and audio
+ * cannot be read or quoted, and nothing can be written over them or into the
+ * declared folder, except the `.import` settings beside a file.
+ *
+ * @param {Object} repo a `createRepoTools` surface
+ * @param {{manifest: string, folder: string, prefix?: string}} input `prefix` is the project's path inside the repository
+ * @returns {Object}
+ */
+export function guardRepoTools(repo, { manifest, folder, prefix = '' }) {
+  const declared = prefix ? path.posix.join(prefix, folder) : folder;
+  return {
+    tools: repo.tools,
+    get written() {
+      return repo.written;
+    },
+    async execute(toolUse) {
+      const input = toolUse.input || {};
+      const target = String(input.path || '');
+      if (toolUse.name === 'read_file') {
+        if (path.posix.normalize(target) === MANIFEST_PATH) return manifestAnswer(toolUse, manifest, input);
+        if (isMediaPath(target)) return refusal(toolUse.id, REFUSED_CONTENT(target));
+      }
+      if (toolUse.name === 'write_file' || toolUse.name === 'edit_file') {
+        if (isMediaPath(target) || (inFolder(target, declared) && !target.endsWith('.import'))) return refusal(toolUse.id, REFUSED_WRITE(target));
+      }
+      const answer = await repo.execute(toolUse);
+      if (toolUse.name === 'grep') return withoutMediaLines(answer);
+      return answer;
+    }
+  };
+}
+
+function manifestAnswer(toolUse, manifest, input) {
+  const lines = manifest.split('\n');
+  const start = Math.max(1, Number(input.start_line) || 1);
+  const limit = Number(input.limit) || lines.length;
+  const text = lines.slice(start - 1, start - 1 + limit).join('\n');
+  return { result: { type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text }] } };
+}
+
+/** A grep result quotes the line it found, and a line of a PNG is file content. */
+function withoutMediaLines(answer) {
+  const block = answer && answer.result && answer.result.content && answer.result.content[0];
+  if (!block || typeof block.text !== 'string') return answer;
+  const kept = block.text.split('\n').filter(line => {
+    const match = /^(.+?):\d+: /.exec(line);
+    return !(match && isMediaPath(match[1]));
+  });
+  block.text = kept.join('\n') || '(no matches)';
+  return answer;
+}
+
+/** The run_check tool, with the asset checks in its list. */
+function assetRunCheckTool(tool) {
+  return {
+    ...tool,
+    description: `${tool.description} asset_references says whether every art or audio path you named exists; asset_import imports the project in Godot and reads what it made for each of them; pixel_art_settings says whether pixel art you named has the nearest filter and clean import settings.`,
+    input_schema: {
+      ...tool.input_schema,
+      properties: { check: { type: 'string', enum: [...tool.input_schema.properties.check.enum, ...ASSET_CHECK_NAMES] } }
+    }
+  };
+}
+
+/**
+ * The tool surface from `withRunCheck`, with the asset checks answerable too.
+ *
+ * @param {Object} surface
+ * @param {{run: Function}} assetChecks
+ * @param {{maxRuns?: number}} [options]
+ */
+export function withAssetChecks(surface, assetChecks, { maxRuns = 6 } = {}) {
+  let runs = 0;
+  return {
+    tools: surface.tools.map(tool => (tool.name === RUN_CHECK_TOOL.name ? assetRunCheckTool(tool) : tool)),
+    get written() {
+      return surface.written;
+    },
+    async execute(toolUse) {
+      const name = toolUse.input && toolUse.input.check;
+      if (toolUse.name !== RUN_CHECK_TOOL.name || !ASSET_CHECK_NAMES.includes(name)) return surface.execute(toolUse);
+      const answer = (text, isError = false) => ({ result: { type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text }], ...(isError ? { is_error: true } : {}) } });
+      if (runs >= maxRuns) return answer(`refused: ${maxRuns} asset checks have run this turn set, which is the limit`, true);
+      runs += 1;
+      const result = await assetChecks.run(name);
+      return answer(checkResultText(result), result.status === 'failed');
+    }
+  };
+}
+
+function planLinesFor(inventory) {
+  return [
+    '',
+    `<assets>The studio's own art and audio are listed in ${MANIFEST_PATH} (${countsLine(inventory.counts)}). Read that file with read_file before you plan any art or audio. List in "placeholders" only what the specification needs and that file does not cover; your list is final and replaces the specification's expected placeholders.</assets>`
+  ];
+}
+
+function instructionsFor(dimension) {
+  const primitives = dimension === '3d' ? 'a MeshInstance3D with a BoxMesh, a SphereMesh or a CapsuleMesh, or a Label' : 'a ColorRect, a Polygon2D or a Label';
+  return [
+    `Art and audio belong to the studio. Read ${MANIFEST_PATH} with read_file: it lists every file you may use, with its res_path and what was measured about it. Use those files by their res_path, and never invent a path, because a file not listed there does not exist. Do not try to read the files themselves; you cannot.`,
+    'Believe the measurements over a file\'s name or any size the specification assumes: size nodes from the width and height listed, and use the listed cell size for a sheet. A row\'s warnings say what will go wrong with that file, so work around them or say so in one line.',
+    `If something the feature needs is missing, build it with a placeholder primitive such as ${primitives}, and name it plainly in your final message and in the plan's placeholders. Never draw, write or fetch art or audio, and never suggest a tool or service for them.`,
+    'For a file with pixel_art true, set texture_filter = CanvasItem.TEXTURE_FILTER_NEAREST on the node that draws it, unless the manifest says the project default is already nearest. Before you finish, call run_check with asset_references, then asset_import.'
+  ];
+}
+
+/**
+ * The uploaded section of the report: counts, and kinds of warning with how many.
+ * It names no file, on purpose. Test this before changing it.
+ */
+export function reportLines({ inventory, usage, placeholderCount, localPath }) {
+  const lines = ['### Assets', ''];
+  if (inventory.counts.files === 0) {
+    lines.push(`The project has no files in its declared asset folder, so anything the feature needed is a placeholder (${placeholderCount}).`, '');
+    return lines;
+  }
+  lines.push(
+    `The declared asset folder holds ${countsLine(inventory.counts)}. This change wired in ${usage.wired.length}, the project now uses ${usage.used.length} and ${usage.unused.length} are unused. ${placeholderCount} placeholder(s) remain, named below.`,
+    '',
+    `Which files is on your machine only, in \`${localPath}\`. No file name from that list and no file content is uploaded.`,
+    ''
+  );
+  const kinds = warningKinds(inventory);
+  if (kinds.length > 0) {
+    lines.push('Warnings from the inventory:', '', ...kinds.map(item => `- ${item.count} x ${item.summary}`), '');
+  }
+  return lines;
+}
+
+function localReport({ inventory, usage, placeholders }) {
+  const list = (title, items, empty) => ['', `## ${title}`, '', ...(items.length ? items.map(item => `- ${item}`) : [empty])];
+  const warned = inventory.files.filter(file => file.warnings.length > 0);
+  const wired = new Set(usage.wired);
+  return [
+    '# Assets in this run',
+    '',
+    `Read from \`${inventory.folder}\`: ${countsLine(inventory.counts)}. This file stays on this machine.`,
+    ...list('Used', usage.used.map(name => `\`${name}\`${wired.has(name) ? ' (wired in by this change)' : ''}${usage.built_in_code.includes(name) ? ' (a path built in code, so a likely match)' : ''}`), 'None.'),
+    ...list('Unused', usage.unused.map(name => `\`${name}\``), 'None.'),
+    ...list('Placeholders still to supply', placeholders, 'None.'),
+    ...list('Warnings', [
+      ...inventory.warnings.map(item => item.text),
+      ...warned.flatMap(file => file.warnings.map(item => `\`${file.path}\`: ${item.text}`))
+    ], 'None.'),
+    ''
+  ].join('\n');
+}
+
+/**
+ * Inventory the declared folder and hand back everything a loop needs.
+ *
+ * A folder that was named and cannot be used is a refusal. The default folder being
+ * absent is not: that is a project with no assets yet, and the loop uses placeholders.
+ *
+ * @param {Object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.projectDir
+ * @param {string} [input.folder] default `assets`
+ * @param {number|null} [input.grid] the grid the studio expects, for a warning
+ * @returns {Promise<Object>}
+ */
+export async function prepareAssets({ repoRoot, projectDir, folder, grid = null, dimension = '2d' }) {
+  const named = Boolean(folder);
+  const inventory = await buildInventory({ projectDir, folder: folder || DEFAULT_ASSETS_DIR, grid });
+  if (!inventory.ok) return { ok: false, reason: inventory.reason };
+  if (named && !inventory.exists) return { ok: false, reason: `There is no folder ${folder} in the project.` };
+
+  const prefix = path.relative(repoRoot, projectDir).split(path.sep).join('/');
+  const manifest = manifestText(inventory, prefix);
+  return {
+    ok: true,
+    inventory,
+    manifest,
+    planLines: planLinesFor(inventory),
+    instructions: instructionsFor(dimension),
+    guardRepo: repo => guardRepoTools(repo, { manifest, folder: inventory.folder, prefix }),
+    bindChecks: options => {
+      const bound = createAssetChecks({ projectDir, inventory, ...options });
+      return { ...bound, withChecks: surface => withAssetChecks(surface, bound) };
+    },
+    /** The plan read the manifest, so its list is the one that stands when it gave one. */
+    placeholders: (plan, spec) => {
+      const planned = plan && Array.isArray(plan.placeholders) ? plan.placeholders : null;
+      const expected = (spec && spec.placeholders) || [];
+      return [...new Set(planned || expected)].slice(0, 40);
+    },
+    /**
+     * Write the local files, print the names on this terminal, and answer the lines
+     * for the uploaded report.
+     */
+    report: async ({ runDir, changed = [], placeholders = [], log = () => {} }) => {
+      const usage = await scanUsage({ projectDir, inventory, changed });
+      await mkdir(runDir, { recursive: true });
+      await writeFile(path.join(runDir, LOCAL_MANIFEST_FILE), manifest, 'utf8');
+      await writeFile(path.join(runDir, LOCAL_REPORT_FILE), localReport({ inventory, usage, placeholders }), 'utf8');
+      const localPath = path.relative(repoRoot, path.join(runDir, LOCAL_REPORT_FILE)).split(path.sep).join('/');
+      if (inventory.counts.files > 0) log(`assets: ${usage.wired.length} wired in by this change, ${usage.used.length} used, ${usage.unused.length} unused. ${localPath}`);
+      for (const name of usage.wired) log(`  wired in: ${name}`);
+      return { usage, localPath, reportLines: reportLines({ inventory, usage, placeholderCount: placeholders.length, localPath }) };
+    }
+  };
+}
+
+export { buildInventory, describeFile, manifestText, warningKinds } from './inventory.js';
+export { ASSET_CHECK_NAMES, createAssetChecks, scanUsage } from './integration.js';
+
+export default prepareAssets;