ravensight-playtest 0.1.0

package/src/run/args.js

@@ -0,0 +1,111 @@
+/**
+ * `run` and `profile` are declared in cli-core's commander program with
+ * `allowUnknownOption()`, and everything commander did not recognise arrives
+ * as `flags.argv`. So the runner parses its own options, which is the right
+ * place for them: they are about driving a game, and cli-core has no business
+ * knowing what `--godot-project` means.
+ *
+ * Only the flags spec 17 section 1.2 lists are understood. An unknown one is
+ * reported rather than ignored, because a silently dropped `--max-actions 5`
+ * spends the developer's money on 25 actions.
+ */
+
+/** Options that take a value. */
+const VALUED = new Map([
+  ['--personas', 'personas'],
+  ['--driver', 'driver'],
+  ['--build-url', 'buildUrl'],
+  ['--build-dir', 'buildDir'],
+  ['--godot-project', 'godotProject'],
+  ['--cli', 'cli'],
+  ['--max-actions', 'maxActions'],
+  ['--concurrency', 'concurrency'],
+  ['--budget-usd', 'budgetUsd'],
+  ['--quality', 'quality']
+]);
+
+/** Options that are just present or absent. */
+const BOOLEAN = new Map([
+  ['--upload-video', 'uploadVideo'],
+  ['--upload-transcript', 'uploadTranscript'],
+  ['--dry-upload', 'dryUpload'],
+  ['--offline-upload', 'offlineUpload'],
+  ['--headed', 'headed'],
+  ['--headless', 'headless'],
+  ['--verbose', 'verbose'],
+  // Resume only: replay an interrupted run from the start instead of writing a
+  // partial report from the transcript it already has.
+  ['--restart-interrupted', 'restartInterrupted']
+]);
+
+/** Options whose value is a number. */
+const NUMERIC = new Set(['maxActions', 'concurrency', 'budgetUsd']);
+
+/**
+ * @param {string[]} argv the leftovers commander handed over
+ * @returns {{options: Object, unknown: string[]}}
+ */
+export function parseRunArgv(argv = []) {
+  const options = {};
+  const unknown = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = String(argv[i]);
+    // `--flag=value` and `--flag value` are both what a developer will type.
+    const split = token.indexOf('=');
+    const name = split === -1 ? token : token.slice(0, split);
+    const inline = split === -1 ? null : token.slice(split + 1);
+
+    if (BOOLEAN.has(name)) {
+      options[BOOLEAN.get(name)] = inline === null ? true : inline !== 'false';
+      continue;
+    }
+    if (VALUED.has(name)) {
+      const key = VALUED.get(name);
+      const raw = inline === null ? argv[i + 1] : inline;
+      if (inline === null) i += 1;
+      if (raw === undefined) {
+        unknown.push(`${name} needs a value`);
+        continue;
+      }
+      options[key] = NUMERIC.has(key) ? Number(raw) : String(raw);
+      continue;
+    }
+    if (name.startsWith('-')) unknown.push(name);
+  }
+  return { options, unknown };
+}
+
+/**
+ * Merge the flags cli-core parsed with the ones this file parsed, flags
+ * winning, and normalise the two names for the repository root.
+ *
+ * @param {Object} flags
+ * @returns {{options: Object, unknown: string[]}}
+ */
+export function optionsFrom(flags = {}) {
+  const { options, unknown } = parseRunArgv(flags.argv);
+  return {
+    options: {
+      ...options,
+      ...stripUndefined({
+        repo: flags.repoRoot || flags.repo,
+        apiUrl: flags.apiUrl,
+        game: flags.game,
+        yes: flags.yes,
+        json: flags.json,
+        token: flags.token,
+        idempotencyKey: flags.idempotencyKey,
+        // `resume` declares this one in commander rather than leaving it to the
+        // argv leftovers, so it arrives as a flag and has to be read here too.
+        restartInterrupted: flags.restartInterrupted
+      })
+    },
+    unknown
+  };
+}
+
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+export default { parseRunArgv, optionsFrom };

package/src/run/context.js

@@ -0,0 +1,181 @@
+/**
+ * Keeping the conversation small enough to be affordable and legal.
+ *
+ * Two independent ceilings:
+ *
+ * 1. **Images.** `routing.json`'s `persona_playtest.act` sets
+ *    `max_images: 1`, and the proxy counts image blocks across the WHOLE
+ *    `messages` array and answers 400 `too_many_images` past that. So the
+ *    ceiling is on the context, not on the newest turn: exactly one image
+ *    may be in flight, and it has to be the newest one, because that is the
+ *    screen the persona is looking at. Older images become a one line
+ *    placeholder rather than being deleted, so the turn structure and the
+ *    tool_use / tool_result pairing stay intact.
+ *
+ *    The brief asked for at most two images per call. One is what the
+ *    server actually allows on this step, and a body with two comes back
+ *    400 with nothing played, so this file follows routing.json. It is a
+ *    constant rather than a literal so that a routing change is a one line
+ *    change here, and `shrinkImages` exists so a caller that meets
+ *    `too_many_images` anyway can retry smaller instead of failing the run.
+ *
+ * 2. **Observations.** Spec 03 keeps the last K=6 observations and lets
+ *    older ones fall back to a stub. A snapshot of a busy screen is several
+ *    thousand characters, so without this a 25 action run pays for its first
+ *    screen twenty five times.
+ */
+
+/** What `persona_playtest.act` allows in one request. */
+export const MAX_IMAGES_IN_CONTEXT = 1;
+
+/** How many full observations stay in context (spec 03's K). */
+export const KEEP_OBSERVATIONS = 6;
+
+const DROPPED_IMAGE_TEXT = '[screenshot dropped from context; only the newest screen is kept]';
+const DROPPED_OBSERVATION_TEXT = '[older observation dropped from context; ask for a snapshot if you need to look again]';
+
+/**
+ * @param {Array} content
+ * @returns {boolean}
+ */
+function hasImage(content) {
+  return Array.isArray(content) && content.some(block => block && block.type === 'image');
+}
+
+/**
+ * Keep the newest `max` image blocks and replace the rest with a
+ * placeholder. Walks backwards, because "newest" is what matters.
+ *
+ * @param {Array} messages
+ * @param {number} [max]
+ * @returns {Array} a new array; the input is not mutated
+ */
+export function pruneImages(messages, max = MAX_IMAGES_IN_CONTEXT) {
+  let budget = Math.max(0, max);
+  const out = messages.map(message => message);
+  for (let i = out.length - 1; i >= 0; i -= 1) {
+    const message = out[i];
+    if (!message || !Array.isArray(message.content)) continue;
+    const content = [];
+    // Within one message the blocks are also newest-last, so the same
+    // backwards walk keeps the right image when a single tool_result
+    // somehow carries two.
+    const blocks = [...message.content];
+    for (let j = blocks.length - 1; j >= 0; j -= 1) {
+      const block = blocks[j];
+      if (block && block.type === 'image') {
+        if (budget > 0) {
+          budget -= 1;
+          content.unshift(block);
+        } else {
+          content.unshift({ type: 'text', text: DROPPED_IMAGE_TEXT });
+        }
+        continue;
+      }
+      if (block && block.type === 'tool_result' && hasImage(block.content)) {
+        const inner = [];
+        const innerBlocks = [...block.content];
+        for (let k = innerBlocks.length - 1; k >= 0; k -= 1) {
+          const child = innerBlocks[k];
+          if (child && child.type === 'image') {
+            if (budget > 0) {
+              budget -= 1;
+              inner.unshift(child);
+            } else {
+              inner.unshift({ type: 'text', text: DROPPED_IMAGE_TEXT });
+            }
+            continue;
+          }
+          inner.unshift(child);
+        }
+        content.unshift({ ...block, content: inner });
+        continue;
+      }
+      content.unshift(block);
+    }
+    out[i] = { ...message, content };
+  }
+  return out;
+}
+
+/**
+ * Count image blocks the way the proxy does, so a caller can assert before
+ * it spends a call.
+ *
+ * @param {Array} messages
+ * @returns {number}
+ */
+export function countImages(messages) {
+  let images = 0;
+  for (const message of messages) {
+    if (!message || !Array.isArray(message.content)) continue;
+    for (const block of message.content) {
+      if (!block) continue;
+      if (block.type === 'image') images += 1;
+      else if (block.type === 'tool_result' && Array.isArray(block.content)) {
+        for (const child of block.content) {
+          if (child && child.type === 'image') images += 1;
+        }
+      }
+    }
+  }
+  return images;
+}
+
+/**
+ * Replace all but the newest `keep` observation texts with a stub. An
+ * observation is a `tool_result` whose text begins `step N`, which is the
+ * shape ./tools.js writes.
+ *
+ * @param {Array} messages
+ * @param {number} [keep]
+ * @returns {Array}
+ */
+export function pruneObservations(messages, keep = KEEP_OBSERVATIONS) {
+  const indexes = [];
+  messages.forEach((message, i) => {
+    if (!message || !Array.isArray(message.content)) return;
+    message.content.forEach((block, j) => {
+      if (block && block.type === 'tool_result' && Array.isArray(block.content)) {
+        const first = block.content.find(child => child && child.type === 'text');
+        if (first && /^(?:[^\n]*\n)?step \d+/.test(String(first.text))) indexes.push([i, j]);
+      }
+    });
+  });
+
+  const stale = indexes.slice(0, Math.max(0, indexes.length - keep));
+  if (stale.length === 0) return messages;
+
+  const out = messages.map(message => (message && Array.isArray(message.content) ? { ...message, content: [...message.content] } : message));
+  for (const [i, j] of stale) {
+    const block = out[i].content[j];
+    out[i].content[j] = { ...block, content: [{ type: 'text', text: DROPPED_OBSERVATION_TEXT }] };
+  }
+  return out;
+}
+
+/**
+ * Both ceilings, in the order that matters: drop stale observations first
+ * (which removes their images too), then enforce the image budget on what
+ * is left.
+ *
+ * @param {Array} messages
+ * @param {{maxImages?: number, keepObservations?: number}} [opts]
+ * @returns {Array}
+ */
+export function prepareMessages(messages, { maxImages = MAX_IMAGES_IN_CONTEXT, keepObservations = KEEP_OBSERVATIONS } = {}) {
+  return pruneImages(pruneObservations(messages, keepObservations), maxImages);
+}
+
+/**
+ * The retry after a `too_many_images`: the step allows fewer than we
+ * thought, so halve and try again rather than losing the run.
+ *
+ * @param {number} current
+ * @returns {number}
+ */
+export function shrinkImages(current) {
+  return Math.max(0, Math.floor(current / 2));
+}
+
+export default { prepareMessages, pruneImages, pruneObservations, countImages, shrinkImages, MAX_IMAGES_IN_CONTEXT, KEEP_OBSERVATIONS };

package/src/run/deps.js

@@ -0,0 +1,184 @@
+/**
+ * The seam between the runner (this directory) and cli-core.
+ *
+ * Nothing under `src/run/**` imports cli-core except through `getDeps()`, so
+ * the whole integration is this one file, and every test in this directory
+ * injects fakes with `setDeps()` rather than standing up an HTTP server it
+ * does not need.
+ *
+ * ## What cli-core provides
+ *
+ * `src/api/index.js` is the only importable module (its own README says so).
+ * The names used here:
+ *
+ * | Name | Shape |
+ * |---|---|
+ * | `createContext({ apiUrl, repoRoot, requireAuth })` | `{ api, apiUrl, token, config, repoRoot }` in one call |
+ * | `api.jobs.estimate(gameId, { modules, personas })` | `{ estimate_cents, breakdown, balance_cents, ok, topup_url }` |
+ * | `api.jobs.register(gameId, body, { idempotencyKey })` | `{ job_id, runs: [{ run_id, module, persona, playtest_token, budget_usd }], price, links, replayed }` |
+ * | `api.jobs.finish(gameId, jobId, { state, reason })` | `{ job, refunded_cents, already_settled }` |
+ * | `api.jobs.capabilityReport(gameId, jobId, body)` | `{ capability_report }` |
+ * | `api.jobs.aggregateComplete(gameId, jobId, body)` | `{ aggregate }` |
+ * | `api.jobs.uploads(gameId, jobId, { files })` | job-level presign, used for the aggregate |
+ * | `api.brief.get(gameId)` | `{ brief, rendered }` or `{ brief: null }`; the frozen expectations brief every persona is told to respect |
+ * | `api.runs.heartbeat(gameId, jobId, runId, opts)` | `{ run, cancel_requested }`; `opts` is camelCase (`actionsTaken`, `checkpointStep`) |
+ * | `api.runs.transition(gameId, jobId, runId, state, opts)` | the same PATCH with a state |
+ * | `api.runs.complete(gameId, jobId, runId, body)` | reached through `finalizeRun` |
+ * | `packs.get({ api, gameId, modules })` | `{ bundle, etag, fromCache, stale }`; the runner wants `bundle` |
+ * | `uploadRunDir(runDir, opts)` / `finalizeRun(runDir, opts)` | presign, PUT, `complete`, with the 422 `upload_unverified` repair pass |
+ * | `putFile`, `contentTypeFor` | the one PUT the runner makes itself, for the job-level aggregate |
+ * | `ui`, `paths`, `loadConfig`, `resolveGameId`, `CLI_VERSION`, `ApiError` | output, layout, config |
+ *
+ * Two deliberate differences from what cli-core hands over:
+ *
+ * 1. **`packs.get` is unwrapped here.** Everything above this file wants the
+ *    bundle, not the cache metadata, and a `bundle.bundle` would be a trap.
+ * 2. **The job-level upload is `uploadRunDir` with no `runId`.** The aggregate
+ *    lives at job level rather than in a run directory, and cli-core's uploader
+ *    already covers that: its allowlist has `aggregate-report.md` and
+ *    `aggregate-report.json` in it, and its presign helper falls back to
+ *    `api.jobs.uploads` when there is no run. So `publishJobFiles` delegates,
+ *    which is what keeps the upload journal (`upload-queue.jsonl`, so a crash
+ *    can be drained later) and the 403 re-presign in the one module that owns
+ *    them. All it adds is the size and digest of the markdown, which
+ *    `aggregate/complete` has to be told and the uploader does not return.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** @type {Object|null} */
+let injected = null;
+
+/**
+ * Replace every dependency. Tests use this; so does anything that wants to
+ * drive the loop against a fake.
+ *
+ * @param {Object|null} deps
+ */
+export function setDeps(deps) {
+  injected = deps;
+}
+
+/** Undo `setDeps`. */
+export function resetDeps() {
+  injected = null;
+}
+
+/**
+ * The path prefix every playtest route hangs off. Tenancy is structural on the
+ * server (`/api/v1/games/:gameId/playtest/...` behind `requireGame`), so the
+ * game id is in the path rather than in a body field, and it is built once.
+ *
+ * @param {string} gameId
+ * @returns {string}
+ */
+export function playtestBase(gameId) {
+  if (!gameId) throw new Error('a game id is required; run "ravensight-playtest init --game <gameId>" first');
+  return `/api/v1/games/${encodeURIComponent(gameId)}/playtest`;
+}
+
+/**
+ * Wrap cli-core's barrel into the surface `src/run/**` uses.
+ *
+ * @param {Object} core the `src/api/index.js` module
+ * @returns {Object}
+ */
+export function normalise(core) {
+  if (!core || typeof core.createContext !== 'function') {
+    throw new Error('src/api/index.js did not export createContext; see src/run/deps.js for the interface the runner needs');
+  }
+  return {
+    core,
+    createContext: core.createContext,
+    loadConfig: core.loadConfig,
+    resolveGameId: core.resolveGameId,
+    cliVersion: core.CLI_VERSION,
+    ui: core.ui,
+    paths: core.paths,
+    ApiError: core.ApiError,
+    uploadRunDir: core.uploadRunDir,
+    finalizeRun: core.finalizeRun,
+    brief: {
+      /**
+       * The expectations brief, or null when this game has none.
+       *
+       * Unwrapped from `{ brief, rendered }` because everything above this
+       * file wants the brief itself, and because a null brief is a normal
+       * answer: a `game_profile` job legitimately runs without one, and the
+       * persona skill has a "when expectations_brief is not null" branch for
+       * exactly this. A failure to fetch is NOT swallowed: a persona playing
+       * without the brief reports findings nobody asked for and re-reports
+       * known issues, which is worse than not running.
+       *
+       * @param {{api: Object, gameId: string}} options
+       * @returns {Promise<Object|null>}
+       */
+      async get({ api, gameId }) {
+        const answer = await api.brief.get(gameId);
+        return (answer && answer.brief) || null;
+      }
+    },
+    packs: {
+      /**
+       * @param {{api: Object, gameId: string, modules: string[], offline?: boolean}} options
+       * @returns {Promise<Object>} the bundle itself
+       */
+      async get(options) {
+        const answer = await core.packs.get(options);
+        return answer && answer.bundle ? answer.bundle : answer;
+      }
+    },
+    publishJobFiles: buildPublishJobFiles(core)
+  };
+}
+
+/**
+ * Upload job-level files (the aggregate) and answer their sizes and digests,
+ * which is what `aggregate/complete` then has to be told.
+ *
+ * @param {Object} core
+ * @returns {(args: Object) => Promise<Object>}
+ */
+export function buildPublishJobFiles(core) {
+  return async function publishJobFiles({ api, gameId, jobId, dir, files, repoRoot }) {
+    // The digests first, because `aggregate/complete` verifies the markdown
+    // against a size and a sha256 and the uploader does not hand those back.
+    // Same bytes either way: both read the file that is on disk now.
+    const digests = {};
+    for (const name of files) {
+      const body = await readFile(path.join(dir, name));
+      digests[name] = { size: body.length, sha256: createHash('sha256').update(body).digest('hex') };
+    }
+
+    // `runId: null` is what makes this the job-level presign, and `allowedPaths`
+    // confines the walk to the two aggregate files so nothing else in the job
+    // directory can be swept up.
+    const result = await core.uploadRunDir(dir, {
+      api,
+      gameId,
+      jobId,
+      runId: null,
+      allowedPaths: files,
+      repoRoot
+    });
+
+    const failed = (result && result.skipped ? result.skipped : [])
+      .filter(entry => files.includes(entry.path) && entry.reason !== 'already uploaded');
+    if (failed.length > 0) {
+      throw new Error(`the aggregate was not uploaded: ${failed.map(entry => `${entry.path} (${entry.reason})`).join(', ')}`);
+    }
+    return digests;
+  };
+}
+
+/**
+ * @returns {Promise<Object>}
+ */
+export async function getDeps() {
+  if (injected) return injected;
+  return normalise(await import('../api/index.js'));
+}
+
+export default { getDeps, setDeps, resetDeps, normalise, playtestBase, buildPublishJobFiles };

package/src/run/drivers/driver.js

@@ -0,0 +1,183 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The driver interface. One shape, three implementations (spec 03's
+ * "Driver interface (all drivers)"): `playwright_web` here in ./web.js,
+ * `godot_driver` in ./godot.js, and `cli_stdio` later.
+ *
+ * A driver is the ONLY thing in this CLI that touches the game. The model
+ * never gets a shell, a file write outside the run directory, or a network
+ * tool: the whole tool surface it sees is this interface, wrapped by
+ * ../tools.js. That is what keeps prompt injection from game text
+ * (a level name, an NPC line, a leaderboard entry) to a small blast
+ * radius, and it is why `act` takes a closed union of actions rather than
+ * anything the model would like to run.
+ *
+ * ```
+ * launch({ target, runDir, recordVideo, viewport, env, signal }) -> void
+ * observe()                -> Observation
+ * act(action)              -> ActResult
+ * screenshot(name, opts)   -> { path, relativePath }
+ * stop()                   -> { videoPath?: string|null, framesDir?: string }
+ * ```
+ *
+ * Optional, used when present:
+ *
+ * ```
+ * chapter(title)  -> void            video chapter marker
+ * consoleErrors() -> ConsoleEntry[]  errors since the previous call
+ * ```
+ *
+ * Two places where the drivers legitimately differ, and callers have to
+ * cope with both rather than assume the web one:
+ *
+ * - **A string `click` target is driver-specific.** On `playwright_web` it
+ *   is an accessibility node, a text fragment or a CSS selector; on
+ *   `godot_driver` it is a node path out of the scene tree. The tool
+ *   description in ../tools.js says so, because the model is the one
+ *   choosing.
+ * - **`stop()` may return no video.** `playwright_web` hands back a
+ *   `session.webm` from Playwright's own recorder. `godot_driver` returns
+ *   `videoPath: null` and leaves a `frames/` sequence, which the CLI
+ *   stitches only when ffmpeg is present. That is what keeps ffmpeg
+ *   optional, and it means "no video" is a normal outcome, not a failure.
+ *
+ * `Observation.scene`, `.scenes` and `.scripts` are how a finding from a
+ * running Godot game can cite a `res://` path; the web driver leaves them
+ * unset.
+ *
+ * @typedef {Object} Observation
+ * @property {number} step monotonic, one per observe()
+ * @property {string} text accessibility snapshot, scene tree summary or
+ *   stdout delta, truncated to OBSERVATION_MAX_CHARS
+ * @property {unknown} [structured] the raw payload, never sent to the model
+ *   unless it is small
+ * @property {string} [screenshotBase64] a PNG, only when the text
+ *   observation is too thin to play from (canvas games)
+ * @property {string} [screenshotMediaType]
+ * @property {string} [url]
+ * @property {string} [scene] the current scene path, godot_driver only
+ * @property {string[]} [scenes] scene paths behind this screen
+ * @property {string[]} [scripts] script paths behind this screen
+ * @property {number} elapsedMs
+ *
+ * @typedef {{kind: 'key', key: string}
+ *   | {kind: 'type', text: string, submit?: boolean}
+ *   | {kind: 'click', target: string | {x: number, y: number}}
+ *   | {kind: 'press_action', action: string, durationMs?: number}
+ *   | {kind: 'navigate', url: string}
+ *   | {kind: 'wait', ms: number}} Action
+ *
+ * @typedef {Object} ActResult
+ * @property {boolean} ok
+ * @property {string} [error]
+ * @property {boolean} changed whether the observation hash moved
+ *
+ * @typedef {{type: string, text: string}} ConsoleEntry
+ */
+
+/** Observation text is truncated to this many characters (spec 03). */
+export const OBSERVATION_MAX_CHARS = 12000;
+
+/**
+ * Under this much snapshot text the accessibility tree is not worth
+ * playing from, so the driver attaches a screenshot instead. Typical of a
+ * Godot or Unity web export, which is one canvas element and nothing else
+ * (spec 03, `playwright_web`).
+ */
+export const THIN_OBSERVATION_CHARS = 200;
+
+/** The five methods every driver has to have. */
+export const DRIVER_METHODS = Object.freeze(['launch', 'observe', 'act', 'screenshot', 'stop']);
+
+/** Action kinds a driver may be asked for. A driver may refuse a kind it cannot do. */
+export const ACTION_KINDS = Object.freeze(['key', 'type', 'click', 'press_action', 'navigate', 'wait']);
+
+export class DriverError extends Error {
+  /**
+   * @param {string} message
+   * @param {{fatal?: boolean}} [opts] fatal means the driver itself is
+   *   unusable, which ends the run as `error` rather than as a finding. A
+   *   crashed *game* is a finding (spec 03); a crashed *driver* is not.
+   */
+  constructor(message, { fatal = false } = {}) {
+    super(message);
+    this.name = 'DriverError';
+    this.fatal = fatal;
+  }
+}
+
+/**
+ * Refuse a driver that does not implement the interface at load time,
+ * rather than discovering it three actions into a paid run.
+ *
+ * @param {any} driver
+ * @param {string} name
+ * @returns {any} the same driver
+ */
+export function assertDriver(driver, name) {
+  if (!driver || typeof driver !== 'object') {
+    throw new DriverError(`driver ${name} did not return an object`, { fatal: true });
+  }
+  const missing = DRIVER_METHODS.filter(method => typeof driver[method] !== 'function');
+  if (missing.length > 0) {
+    throw new DriverError(`driver ${name} is missing: ${missing.join(', ')}`, { fatal: true });
+  }
+  return driver;
+}
+
+/**
+ * The hash that decides `changed` and feeds the stuck detector. Whitespace
+ * is collapsed first, because a repainted but identical screen often
+ * differs only in trailing spaces and a stuck persona should still read as
+ * stuck.
+ *
+ * @param {Observation|string|null|undefined} observation
+ * @returns {string}
+ */
+export function observationHash(observation) {
+  const text = typeof observation === 'string' ? observation : String((observation && observation.text) || '');
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  return createHash('sha256').update(normalized, 'utf8').digest('hex').slice(0, 32);
+}
+
+/**
+ * @param {string} text
+ * @param {number} [max]
+ * @returns {string}
+ */
+export function truncateObservation(text, max = OBSERVATION_MAX_CHARS) {
+  const value = String(text == null ? '' : text);
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\n... [truncated, ${value.length - max} more characters]`;
+}
+
+/**
+ * `screenshots/NN-slug.png`, the name the report schema's `screenshot`
+ * evidence refs point at. The number is the driver's own screenshot
+ * counter, so the files sort in the order they were taken.
+ *
+ * @param {number} index 1-based
+ * @param {string} name
+ * @returns {string}
+ */
+export function screenshotName(index, name) {
+  const slug = String(name || 'shot')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'shot';
+  return `${String(index).padStart(2, '0')}-${slug}.png`;
+}
+
+export default {
+  OBSERVATION_MAX_CHARS,
+  THIN_OBSERVATION_CHARS,
+  DRIVER_METHODS,
+  ACTION_KINDS,
+  DriverError,
+  assertDriver,
+  observationHash,
+  truncateObservation,
+  screenshotName
+};