ravensight-playtest 0.1.0

package/src/run/personaLoop.js

@@ -0,0 +1,871 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareMessages, MAX_IMAGES_IN_CONTEXT, KEEP_OBSERVATIONS, shrinkImages } from './context.js';
+import { observationHash } from './drivers/driver.js';
+import { callStepWithRetry, ProxyError, STEPS } from './model.js';
+import { RUN_FILES } from './paths.js';
+import { checkEvidence, createReportValidator, lintMarkdownSections, repairInstruction, REQUIRED_MARKDOWN_SECTIONS, stampReport, writeReportFiles } from './report.js';
+import { assertNoSecrets } from './secretScan.js';
+import { ACTION_TOOLS, PLAY_TOOLS, REPORT_TOOLS, executeTool } from './tools.js';
+import { createTranscript } from './transcript.js';
+import { createUsageLedger, writeUsageFile } from './usage.js';
+
+/**
+ * One persona's playthrough: PLAYING then REPORTING (spec 03).
+ *
+ * The two phases are two different steps at the proxy
+ * (`persona_playtest.act` and `persona_playtest.report`), with different
+ * tool allowlists and different token ceilings, and REPORTING reads only
+ * stored inputs. That split is what makes `regenerate` possible: the report
+ * can be rebuilt later from `transcript.jsonl` plus the screenshots, without
+ * the game running and without replaying anything.
+ *
+ * Billing shapes the control flow more than anything else does. A model turn
+ * is the billable unit, so every turn here has to be worth its money:
+ *
+ * - The screen is observed once per turn, inside the tool result the model
+ *   already asked for, rather than as a separate turn.
+ * - Old observations and old images fall out of context (./context.js), so
+ *   turn twenty does not pay for turn one's screen again.
+ * - `X-Playtest-Budget: warn` at 80 percent of the run budget starts a wrap
+ *   up, so the report (which is the product) gets written while there is
+ *   still budget to write it with.
+ * - A 402 means the money is gone. Nothing further is asked of the model,
+ *   including the report: a partial `report.md` is written locally from the
+ *   notes, `complete` is sent with `state: budget_exceeded` and no
+ *   `report`, and the process exits 2.
+ */
+
+/** Stop injecting the "nothing changed" hint after this many identical screens. */
+export const STUCK_HINT_AFTER = 5;
+
+/** Give up entirely after this many identical screens: the persona is wedged. */
+export const STUCK_LIMIT = 12;
+
+/** Turns allowed after a budget warning, to land the report. */
+export const WRAP_UP_TURNS = 3;
+
+/** Token ceiling asked for per act turn. The proxy clamps it to the step's own. */
+export const ACT_MAX_TOKENS = 1024;
+
+/** Token ceiling asked for when writing the report. */
+export const REPORT_MAX_TOKENS = 4096;
+
+/**
+ * @typedef {Object} PersonaRunOutcome
+ * @property {string} state one of succeeded, failed, canceled, budget_exceeded
+ * @property {string} quitReason a report schema quit_reason
+ * @property {string} [quitDetail]
+ * @property {number} actionsTaken
+ * @property {Object|null} report the validated report.json, null when none
+ *   was written
+ * @property {boolean} budgetWarned
+ * @property {Array<string>} reportLint
+ * @property {string|null} videoPath
+ * @property {Object} usage
+ */
+
+/**
+ * @param {Object} args
+ * @returns {Promise<PersonaRunOutcome>}
+ */
+export async function runPersona(args) {
+  const {
+    client,
+    api,
+    gameId,
+    jobId,
+    runId,
+    persona,
+    module: moduleName = 'persona_playtest',
+    driver,
+    driverName,
+    target,
+    runDirectory,
+    skill,
+    brief = null,
+    intentNotes = [],
+    schemas,
+    maxActions,
+    maxImages = MAX_IMAGES_IN_CONTEXT,
+    keepObservations = KEEP_OBSERVATIONS,
+    heartbeat = null,
+    onProgress = () => {},
+    log = () => {},
+    recordVideo = false,
+    viewport
+  } = args;
+
+  const validator = createReportValidator(schemas);
+  // The caller may own the ledger, which is how the run's authoritative spend
+  // gets into it: the heartbeat answer carries `run.usage.total_usd`, and only
+  // the caller has the heartbeat.
+  const ledger = args.ledger || createUsageLedger();
+  const startedAt = new Date().toISOString();
+  const notes = [];
+  const screenshots = [];
+  let imageBudget = maxImages;
+
+  await mkdir(path.join(runDirectory, 'screenshots'), { recursive: true });
+  const transcript = await createTranscript(runDirectory).open();
+  transcript.write({
+    kind: 'header',
+    run_id: runId,
+    job_id: jobId,
+    persona: persona.slug,
+    driver: driverName,
+    target,
+    prompt_version: promptVersionOf(skill),
+    brief_id: brief ? brief.brief_id || null : null,
+    brief_version: brief ? brief.version ?? null : null,
+    max_actions: maxActions
+  });
+
+  let outcome = {
+    state: 'failed',
+    quitReason: 'error',
+    quitDetail: '',
+    actionsTaken: 0,
+    report: null,
+    budgetWarned: false,
+    reportLint: [],
+    videoPath: null,
+    usage: null,
+    // The last state the SERVER accepted, which is not the same thing as the
+    // outcome: the caller has to know whether this run ever reached
+    // `reporting`, because the server's table only allows `uploading` from
+    // there and a hop it refuses is a 409, not a no-op.
+    reachedState: 'queued'
+  };
+
+  /**
+   * Move the run and remember where it got to.
+   * @param {string} state
+   * @param {string} [reason]
+   */
+  async function advance(state, reason = '') {
+    await transition(api, gameId, jobId, runId, state, reason);
+    outcome.reachedState = state;
+  }
+
+  try {
+    // `launching` first, then launch: the state means "we are starting the
+    // game", and a launch that hangs or dies should leave the server holding
+    // that rather than still holding `queued`.
+    await advance('launching');
+    await driver.launch({ target, runDir: runDirectory, recordVideo, viewport });
+    await advance('playing');
+
+    const play = await playLoop({
+      ...args,
+      transcript,
+      ledger,
+      notes,
+      screenshots,
+      imageBudget,
+      keepObservations,
+      onImageBudget: next => {
+        imageBudget = next;
+      }
+    });
+    imageBudget = play.imageBudget;
+    outcome = { ...outcome, ...play };
+
+    const endedAt = new Date().toISOString();
+    await driverStop(driver, outcome, log);
+
+    if (play.canceled) {
+      outcome.state = 'canceled';
+      outcome.quitReason = play.quitReason || 'error';
+      await writePartialMarkdown({ runDirectory, persona, driverName, target, notes, screenshots, play, reason: 'The run was cancelled before the report was written.' });
+      return finish(outcome, ledger, runDirectory, transcript, heartbeat);
+    }
+
+    if (play.budgetExceeded) {
+      outcome.state = 'budget_exceeded';
+      outcome.quitReason = 'cost_cap';
+      // Nothing more is asked of the model: there is no budget left to ask
+      // with, and a refused call would just be another 402.
+      await writePartialMarkdown({ runDirectory, persona, driverName, target, notes, screenshots, play, reason: 'The run reached its model budget before the report step. What the persona saw is below; there is no report.json for this run.' });
+      return finish(outcome, ledger, runDirectory, transcript, heartbeat);
+    }
+
+    await advance('reporting');
+    onProgress({ phase: 'reporting', persona: persona.slug });
+
+    const written = await reportPhase({
+      client,
+      jobId,
+      runId,
+      persona,
+      driverName,
+      target,
+      runDirectory,
+      schemas,
+      validator,
+      skill: args.reportSkill || skill,
+      brief,
+      intentNotes,
+      transcript,
+      ledger,
+      notes,
+      screenshots,
+      play,
+      startedAt,
+      endedAt,
+      log
+    });
+
+    outcome.report = written.report;
+    outcome.reportMarkdown = written.markdown;
+    outcome.reportLint = written.lint;
+    outcome.state = 'succeeded';
+    outcome.quitReason = written.report.quit_reason;
+    outcome.quitDetail = written.report.quit_detail || '';
+    return finish(outcome, ledger, runDirectory, transcript, heartbeat);
+  } catch (error) {
+    await driverStop(driver, outcome, log);
+    if (error instanceof ProxyError && error.isBudget) {
+      outcome.state = 'budget_exceeded';
+      outcome.quitReason = 'cost_cap';
+    } else if (error instanceof ProxyError && error.isClosed) {
+      outcome.state = 'canceled';
+      outcome.quitReason = 'error';
+    } else {
+      outcome.state = 'failed';
+      outcome.quitReason = 'error';
+    }
+    outcome.quitDetail = String(error && error.message ? error.message : error);
+    transcript.write({ kind: 'error', message: outcome.quitDetail });
+    await finish(outcome, ledger, runDirectory, transcript, heartbeat);
+    throw Object.assign(error, { outcome });
+  }
+}
+
+/**
+ * The PLAYING phase.
+ *
+ * @returns {Promise<Object>}
+ */
+async function playLoop({
+  client,
+  jobId,
+  runId,
+  persona,
+  driver,
+  driverName,
+  target,
+  skill,
+  brief,
+  intentNotes,
+  maxActions,
+  transcript,
+  ledger,
+  notes,
+  screenshots,
+  imageBudget,
+  keepObservations,
+  heartbeat,
+  onProgress = () => {},
+  log = () => {}
+}) {
+  const system = buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions });
+  const messages = [];
+  let actions = 0;
+  let turns = 0;
+  let quitReason = 'budget_exhausted';
+  let quitDetail = '';
+  let budgetWarned = false;
+  let budgetExceeded = false;
+  let canceled = false;
+  let unchanged = 0;
+  let wrapUpLeft = Infinity;
+  const maxTurns = maxActions * 3 + 20;
+
+  const first = await driver.observe();
+  transcript.write({ kind: 'observation', step: first.step, text: first.text, url: first.url });
+  const landing = await safeScreenshot(driver, 'landing', screenshots, transcript);
+  messages.push({
+    role: 'user',
+    content: [
+      { type: 'text', text: `You are in front of the game now. ${landing ? `A screenshot is saved at ${landing.relativePath}. ` : ''}step ${first.step}${first.url ? ` (${first.url})` : ''}\n${first.text}` },
+      ...(first.screenshotBase64
+        ? [{ type: 'image', source: { type: 'base64', media_type: first.screenshotMediaType || 'image/png', data: first.screenshotBase64 } }]
+        : [])
+    ]
+  });
+
+  while (turns < maxTurns && actions < maxActions) {
+    if (heartbeat && heartbeat.canceled) {
+      canceled = true;
+      quitReason = 'error';
+      quitDetail = 'the job was cancelled';
+      break;
+    }
+    if (wrapUpLeft <= 0) {
+      quitReason = 'budget_exhausted';
+      break;
+    }
+
+    turns += 1;
+    let answer;
+    try {
+      answer = await callWithImageRetry({
+        client,
+        jobId,
+        runId,
+        step: STEPS.personaAct,
+        system,
+        messages,
+        tools: PLAY_TOOLS,
+        maxTokens: ACT_MAX_TOKENS,
+        escalate: shouldEscalate(persona),
+        imageBudget,
+        keepObservations,
+        onImageBudget: next => {
+          imageBudget = next;
+        }
+      });
+    } catch (error) {
+      if (error instanceof ProxyError && error.isBudget) {
+        budgetExceeded = true;
+        quitReason = 'cost_cap';
+        quitDetail = error.message;
+        break;
+      }
+      if (error instanceof ProxyError && error.isClosed) {
+        canceled = true;
+        quitDetail = error.message;
+        break;
+      }
+      throw error;
+    }
+
+    ledger.record({ model: answer.model, usage: answer.usage });
+    // The warn turn is a turn the developer paid for, so its tool calls are
+    // executed like any other and the wrap-up notice rides along on that
+    // turn's tool_result. Two things this avoids: discarding a paid action,
+    // and pushing a second consecutive `user` message, which the Messages API
+    // refuses when the previous turn ended in a tool_use.
+    let wrapUpNotice = null;
+    if (answer.budget === 'warn' && !budgetWarned) {
+      budgetWarned = true;
+      wrapUpLeft = WRAP_UP_TURNS;
+      // Surfaced, not swallowed: this is the developer's money and the one
+      // moment where telling them costs nothing and saying nothing costs a
+      // report.
+      log(`budget warning: this run has used at least 80 percent of its model budget. Wrapping up after ${WRAP_UP_TURNS} more turns so the report still gets written.`);
+      wrapUpNotice = `You are nearly out of budget for this session. Take a final screenshot if you need one, then stop calling tools so the report can be written. You have ${WRAP_UP_TURNS} turns left.`;
+      transcript.write({ kind: 'budget_warning', wrap_up_turns: WRAP_UP_TURNS });
+    }
+    if (budgetWarned) wrapUpLeft -= 1;
+
+    if (answer.toolUses.length === 0) {
+      // No tool call is how a persona stops: there is no quit tool in the
+      // step's allowlist, and adding one would be refused by the proxy. A warn
+      // on such a turn needs no notice either, since the loop ends here.
+      quitReason = budgetWarned && wrapUpNotice ? 'budget_exhausted' : 'persona_quit';
+      quitDetail = answer.text.slice(0, 400);
+      transcript.write({ kind: 'quit', reason: quitReason, text: answer.text });
+      break;
+    }
+
+    messages.push({ role: 'assistant', content: assistantContent(answer) });
+    const results = [];
+    for (const toolUse of answer.toolUses) {
+      const executed = await executeTool({
+        driver,
+        toolUse,
+        onNote: note => {
+          // The note is nested rather than spread: its own `kind`
+          // (bug, confusing, good, suggestion, reaction) would otherwise
+          // overwrite the transcript line's `kind`, and every note would
+          // read as a different sort of line.
+          notes.push({ ...note, at_action: actions });
+          transcript.write({ kind: 'note', tool: toolUse.name, note });
+        },
+        onScreenshot: shot => {
+          screenshots.push(shot);
+          transcript.write({ kind: 'screenshot', path: shot.relativePath, reason: shot.reason });
+        }
+      });
+      results.push(executed.result);
+      if (executed.spentAction) actions += 1;
+      transcript.write({
+        kind: 'action',
+        tool: toolUse.name,
+        input: redactToolInput(toolUse),
+        thought: (toolUse.input && toolUse.input.thought_in_character) || null,
+        ok: !executed.error,
+        error: executed.error,
+        changed: executed.changed,
+        actions
+      });
+      if (executed.observation) {
+        transcript.write({ kind: 'observation', step: executed.observation.step, text: executed.observation.text, url: executed.observation.url });
+        // Only an input to the game can tell us anything about being stuck. A
+        // `snapshot` or a `screenshot` never changes the screen by design, so
+        // counting those would have a persona that looks twice before acting
+        // declared wedged for doing the right thing.
+        if (ACTION_TOOLS.includes(toolUse.name)) unchanged = executed.changed ? 0 : unchanged + 1;
+      }
+      onProgress({ phase: 'playing', persona: persona.slug, actions, maxActions, tool: toolUse.name });
+    }
+
+    // Everything the runner wants to tell the model about this turn goes into
+    // the SAME user message as the tool results: console errors, the budget
+    // wrap-up, the stuck hint. Two reasons it is not a second message. The
+    // Messages API requires alternating roles, so a second consecutive `user`
+    // turn is refused outright. And a fabricated `tool_use_id` (which is what
+    // an "auto-console" tool_result would be) has no matching `tool_use` in
+    // the assistant turn, which is refused as well.
+    const asides = [];
+
+    const consoleErrors = typeof driver.consoleErrors === 'function' ? await driver.consoleErrors() : [];
+    if (consoleErrors.length > 0) {
+      // An uncaught error in the game is a finding whether or not the
+      // persona noticed it, so it is logged and evidenced automatically
+      // (spec 03). It is the model's job to decide the severity.
+      const shot = await safeScreenshot(driver, 'console-error', screenshots, transcript);
+      for (const entry of consoleErrors) {
+        const note = { kind: 'bug', severity: 'major', text: `${entry.type}: ${entry.text}`, automatic: true };
+        notes.push(note);
+        transcript.write({ kind: 'note', note });
+      }
+      asides.push(`The game logged ${consoleErrors.length} error(s): ${consoleErrors.map(entry => entry.text).join(' | ').slice(0, 800)}${shot ? ` A screenshot is saved at ${shot.relativePath}.` : ''}`);
+    }
+
+    if (wrapUpNotice) asides.push(wrapUpNotice);
+
+    const wedged = unchanged >= STUCK_LIMIT;
+    if (!wedged && unchanged > 0 && unchanged % STUCK_HINT_AFTER === 0) {
+      transcript.write({ kind: 'stuck', unchanged, fatal: false });
+      asides.push(`The screen has not changed for ${unchanged} actions. Your persona would notice that. Try something different, or stop.`);
+    }
+
+    messages.push({
+      role: 'user',
+      content: asides.length > 0
+        ? [...results, { type: 'text', text: asides.join('\n\n') }]
+        : results
+    });
+
+    if (wedged) {
+      quitReason = 'blocker';
+      quitDetail = `the screen did not change for ${unchanged} actions`;
+      transcript.write({ kind: 'stuck', unchanged, fatal: true });
+      break;
+    }
+
+    if (heartbeat) await heartbeat.beat({ actionsTaken: actions, checkpointStep: turns });
+  }
+
+  if (actions >= maxActions && quitReason === 'budget_exhausted') {
+    quitReason = 'budget_exhausted';
+    quitDetail = `the action budget of ${maxActions} ran out`;
+  }
+
+  const final = await safeScreenshot(driver, 'final', screenshots, transcript);
+  return {
+    actionsTaken: actions,
+    turns,
+    quitReason,
+    quitDetail,
+    budgetWarned,
+    budgetExceeded,
+    canceled,
+    imageBudget,
+    finalScreenshot: final ? final.relativePath : null
+  };
+}
+
+/**
+ * The REPORTING phase: a separate call, a separate step, a separate tool
+ * allowlist (`write_file` only), and only stored inputs.
+ */
+async function reportPhase({
+  client,
+  jobId,
+  runId,
+  persona,
+  driverName,
+  target,
+  runDirectory,
+  validator,
+  skill,
+  brief,
+  intentNotes,
+  transcript,
+  ledger,
+  notes,
+  screenshots,
+  play,
+  startedAt,
+  endedAt,
+  log
+}) {
+  const system = buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions: play.actionsTaken });
+  const messages = [{
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: [
+        `The session is over. Write report.md and report.json for run ${runId} of job ${jobId}.`,
+        `persona: ${persona.slug}   driver: ${driverName}   target: ${target}`,
+        `actions taken: ${play.actionsTaken}   stop reason: ${play.quitReason}${play.quitDetail ? ` (${play.quitDetail})` : ''}`,
+        '',
+        'Notes you logged, in order:',
+        notes.length > 0 ? notes.map((note, i) => `${i + 1}. [${note.kind}${note.severity ? `/${note.severity}` : ''}] ${note.text}`).join('\n') : '(none)',
+        '',
+        'Screenshots available as evidence (use these exact paths in evidence refs):',
+        screenshots.length > 0 ? screenshots.map(shot => `- ${shot.relativePath}${shot.reason ? ` (${shot.reason})` : ''}`).join('\n') : '(none)',
+        '',
+        `report.md must contain these section headings, spelled exactly: ${REQUIRED_MARKDOWN_SECTIONS.map(section => `"${section}"`).join(', ')}.`,
+        'Write report.md first, then report.json. Leave usage as zeros; the runner fills it in.'
+      ].join('\n')
+    }]
+  }];
+
+  let report = null;
+  let markdown = null;
+  let lint = [];
+
+  // Two attempts at most: the first, and one repair if the schema or the
+  // evidence refs refuse it. Each attempt is a metered question, and the
+  // dogfood gate asks for "first or the repair attempt", not an
+  // open ended loop.
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    const answer = await callStepWithRetry({
+      client,
+      jobId,
+      runId,
+      step: STEPS.personaReport,
+      system,
+      messages,
+      tools: REPORT_TOOLS,
+      maxTokens: REPORT_MAX_TOKENS,
+      escalate: shouldEscalate(persona)
+    });
+    ledger.record({ model: answer.model, usage: answer.usage });
+    transcript.write({ kind: 'report_turn', attempt, stop_reason: answer.stopReason, files: answer.toolUses.map(t => t.input && t.input.path) });
+
+    const files = new Map();
+    for (const toolUse of answer.toolUses) {
+      if (toolUse.name !== 'write_file' || toolUse.malformed) continue;
+      const name = String(toolUse.input.path || '');
+      if (name !== RUN_FILES.reportMd && name !== RUN_FILES.reportJson) continue;
+      files.set(name, String(toolUse.input.content || ''));
+    }
+    if (files.has(RUN_FILES.reportMd)) markdown = files.get(RUN_FILES.reportMd);
+
+    let parsed = null;
+    let parseError = null;
+    if (files.has(RUN_FILES.reportJson)) {
+      try {
+        parsed = JSON.parse(files.get(RUN_FILES.reportJson));
+      } catch (error) {
+        parseError = String(error && error.message);
+      }
+    }
+
+    const facts = {
+      runId,
+      jobId,
+      persona: persona.slug,
+      driver: driverName,
+      target,
+      startedAt,
+      endedAt,
+      actionsTaken: play.actionsTaken,
+      usage: ledger.toReportUsage(),
+      promptVersion: promptVersionOf(skill),
+      quitReason: play.quitReason,
+      quitDetail: play.quitDetail
+    };
+    const candidate = parsed ? stampReport(parsed, facts) : null;
+    const validation = candidate ? validator.validate(candidate) : { ok: false, details: [{ instancePath: '/', message: parseError || 'report.json was not written' }] };
+    const evidenceProblems = candidate ? await checkEvidence(candidate, runDirectory) : [];
+    // The server lints the same four sections at `complete` and records the
+    // result on the run, where nobody sees it until after the run is over. One
+    // repair turn here is cheaper than a report the developer has to read
+    // around.
+    // A markdown that was never written is missing all four, which is what
+    // asks for it in the repair turn rather than silently falling back.
+    const missingSections = lintMarkdownSections(markdown || '');
+
+    if (validation.ok && evidenceProblems.length === 0 && missingSections.length === 0) {
+      report = candidate;
+      lint = [];
+      break;
+    }
+
+    lint = [
+      ...validation.details.map(detail => `${detail.instancePath}: ${detail.message}`),
+      ...evidenceProblems,
+      ...missingSections.map(section => `report.md has no "${section}" section`)
+    ];
+    if (attempt === 2) {
+      if (!candidate) throw new Error(`the report step did not produce a valid report.json: ${lint.join('; ')}`);
+      // Second attempt still imperfect: keep it, record the lint, and let
+      // the server have the final word. It validates the same schema and
+      // drops unevidenced findings itself, so this is a report with known
+      // problems rather than no report at all.
+      report = candidate;
+      log(`report.json still has problems after one repair: ${lint.join('; ')}`);
+      break;
+    }
+
+    messages.push({ role: 'assistant', content: assistantContent(answer) });
+    messages.push({
+      role: 'user',
+      content: answer.toolUses
+        .filter(toolUse => !toolUse.malformed)
+        .map(toolUse => ({ type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text: 'saved' }] }))
+        .concat([{ type: 'text', text: repairInstruction(validation.details, evidenceProblems, missingSections) }])
+    });
+  }
+
+  if (!markdown) {
+    markdown = renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason: 'The report step wrote report.json but no report.md.' });
+  }
+
+  await writeReportFiles({ runDirectory, markdown, report });
+  return { report, markdown, lint };
+}
+
+/**
+ * `callStepWithRetry`, plus the one retry that is about our own request
+ * rather than the server's mood: `too_many_images` means this step allows
+ * fewer images than we sent, so halve and send again instead of losing the
+ * run over a policy number the CLI is not allowed to read.
+ */
+async function callWithImageRetry({ imageBudget, keepObservations, messages, onImageBudget, ...rest }) {
+  let budget = imageBudget;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const prepared = prepareMessages(messages, { maxImages: budget, keepObservations });
+    try {
+      return await callStepWithRetry({ ...rest, messages: prepared });
+    } catch (error) {
+      if (!(error instanceof ProxyError) || error.code !== 'too_many_images' || budget === 0) throw error;
+      budget = shrinkImages(budget);
+      if (onImageBudget) onImageBudget(budget);
+    }
+  }
+  throw new ProxyError({ status: 400, code: 'too_many_images', message: 'This step refused every image budget we tried.' });
+}
+
+/**
+ * The system prompt: the skill, then the persona, then the brief and the
+ * design intent notes.
+ *
+ * A cache breakpoint goes on the last block because all of it is identical
+ * across every turn of a run, and the act step is the one place in this
+ * product where the same few thousand tokens are re-sent tens of times. The
+ * proxy allowlists `system` and passes the blocks through unchanged.
+ */
+export function buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions }) {
+  return [
+    { type: 'text', text: skill },
+    { type: 'text', text: `<persona_file>\n${persona.body}\n</persona_file>` },
+    {
+      type: 'text',
+      text: [
+        `driver: ${driverName}`,
+        `target: ${target}`,
+        `max_actions: ${maxActions}`,
+        `<expectations_brief>\n${briefForPrompt(brief)}\n</expectations_brief>`,
+        `<design_intent_notes>\n${intentNotesForPrompt(brief, intentNotes)}\n</design_intent_notes>`
+      ].join('\n'),
+      cache_control: { type: 'ephemeral' }
+    }
+  ];
+}
+
+/**
+ * The brief as the persona skill expects it: the `fields` object the
+ * expectations-brief schema describes, with the version alongside so a report
+ * can be attributed to it. The wrapper the API answers with (`brief_id`,
+ * `status`, `change_summary`, `created_by`) is not something a persona has any
+ * use for, and every token of it is re-sent on every turn of the run.
+ *
+ * `null` when there is no brief, which is the branch the skill's "when
+ * expectations_brief is not null" rules hang off.
+ *
+ * @param {Object|null} brief
+ * @returns {string}
+ */
+export function briefForPrompt(brief) {
+  if (!brief) return 'null';
+  const fields = brief.fields && typeof brief.fields === 'object' ? brief.fields : brief;
+  return JSON.stringify({ version: brief.version ?? null, ...fields }, null, 2);
+}
+
+/**
+ * Design intent comes from two places and both are binding: the brief's own
+ * `design_intent_notes`, and the notes the server derives from `intended`
+ * marks on earlier findings (the pack bundle's `intent_notes`). Anything
+ * matching either is deliberate and is never a finding.
+ *
+ * @param {Object|null} brief
+ * @param {Array<Object>} intentNotes
+ * @returns {string}
+ */
+export function intentNotesForPrompt(brief, intentNotes) {
+  const fields = (brief && brief.fields) || {};
+  const fromBrief = Array.isArray(fields.design_intent_notes) ? fields.design_intent_notes : [];
+  const lines = [
+    ...fromBrief.map(note => `- ${typeof note === 'string' ? note : note.text || JSON.stringify(note)}`),
+    ...(intentNotes || []).map(note => `- ${note.text}${note.scope ? ` (scope: ${note.scope})` : ''}`)
+  ];
+  return lines.length > 0 ? lines.join('\n') : '(none)';
+}
+
+/**
+ * A persona file may hint a tier. The hint only ever raises the tier, never
+ * lowers it below the step's floor, and the proxy is the one that applies
+ * it: all the CLI does is ask.
+ *
+ * @param {Object} persona
+ * @returns {boolean}
+ */
+export function shouldEscalate(persona) {
+  const hint = persona && persona.model_tier_hint;
+  return hint === 'tier_frontier' || hint === 'tier_apex';
+}
+
+/**
+ * Rebuild the assistant turn for the conversation. Text first, then the
+ * tool calls; a malformed call goes back as an empty input so the pairing
+ * with its error tool_result stays valid.
+ */
+export function assistantContent(answer) {
+  const content = [];
+  if (answer.text && answer.text.trim().length > 0) content.push({ type: 'text', text: answer.text });
+  for (const toolUse of answer.toolUses) {
+    content.push({ type: 'tool_use', id: toolUse.id, name: toolUse.name, input: toolUse.malformed ? {} : toolUse.input });
+  }
+  if (content.length === 0) content.push({ type: 'text', text: '(no output)' });
+  return content;
+}
+
+/** Keep the transcript readable without storing a whole screenshot in it. */
+function redactToolInput(toolUse) {
+  if (!toolUse.input) return null;
+  const { thought_in_character: ignored, ...rest } = toolUse.input;
+  return rest;
+}
+
+async function safeScreenshot(driver, name, screenshots, transcript) {
+  try {
+    const shot = await driver.screenshot(name);
+    screenshots.push({ ...shot, reason: name });
+    transcript.write({ kind: 'screenshot', path: shot.relativePath, reason: name });
+    return shot;
+  } catch (error) {
+    // Headless Godot cannot screenshot at all, which spec 03 says is
+    // expected and not a finding. Never let it end a run.
+    transcript.write({ kind: 'screenshot_failed', name, message: String(error && error.message) });
+    return null;
+  }
+}
+
+async function driverStop(driver, outcome, log) {
+  try {
+    const stopped = await driver.stop();
+    if (stopped && stopped.videoPath) outcome.videoPath = stopped.videoPath;
+    // The Godot driver captures frames rather than video, and stitching them
+    // needs ffmpeg, which is optional. No video is a normal outcome: say
+    // where the frames are and move on.
+    if (stopped && !stopped.videoPath && stopped.framesDir) {
+      outcome.framesDir = stopped.framesDir;
+      log(`no session.webm for this run; the frame sequence is in ${stopped.framesDir} and needs ffmpeg to stitch.`);
+    }
+  } catch (error) {
+    log(`the driver did not shut down cleanly: ${String(error && error.message)}`);
+  }
+}
+
+async function transition(api, gameId, jobId, runId, state, reason) {
+  // cli-core's transition takes an options object, not a bare reason string.
+  return api.runs.transition(gameId, jobId, runId, state, { reason });
+}
+
+async function finish(outcome, ledger, runDirectory, transcript, heartbeat) {
+  // One last beat before the ledger is written: the answer carries the run's
+  // authoritative spend, and prices are server side only, so without this
+  // `usage.json` says `unavailable` for a run that ended between two ticks.
+  if (heartbeat) {
+    try {
+      await heartbeat.beat();
+    } catch {
+      // A beat that fails here costs the dollar figure, not the run.
+    }
+  }
+  outcome.usage = ledger.toReportUsage();
+  await writeUsageFile(runDirectory, ledger);
+  transcript.write({ kind: 'end', state: outcome.state, quit_reason: outcome.quitReason, actions: outcome.actionsTaken });
+  await transcript.close();
+  return outcome;
+}
+
+/**
+ * The markdown written when there is no model turn left to write a real
+ * report with: cancelled, or out of budget. It carries the notes and the
+ * screenshot list and says plainly that it is partial, rather than
+ * inventing a persona verdict nobody gave.
+ */
+export function renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason }) {
+  const good = notes.filter(note => note.kind === 'good');
+  const bad = notes.filter(note => note.kind === 'bug' || note.kind === 'confusing');
+  const list = entries => (entries.length > 0
+    ? entries.map(note => `- **${note.kind}${note.severity ? `/${note.severity}` : ''}**: ${note.text}`).join('\n')
+    : '- Nothing was logged.');
+
+  // The four headings the server lints for are here too, even in a partial
+  // report. A partial report is still a report somebody reads, and a lint
+  // finding on it would be noise about a run that already went wrong.
+  return [
+    `# Playtest: ${persona.name || persona.slug} (partial)`,
+    `**Driver:** ${driverName} - **Target:** ${target}`,
+    `**Session length:** ${play.actionsTaken} actions / ${play.quitReason}`,
+    '',
+    '## Why this report is partial',
+    reason,
+    '',
+    '## What worked',
+    list(good),
+    '',
+    '## Top issues',
+    list(bad),
+    '',
+    "## What this run didn't cover",
+    `The session ended after ${play.actionsTaken} action(s) with ${play.quitReason}, so nothing past that point was played, and no persona verdict was recorded.`,
+    '',
+    '## Suggested next step',
+    'Run this persona again once the reason above is resolved.',
+    '',
+    '## Evidence',
+    screenshots.length > 0 ? screenshots.map(shot => `- ${shot.relativePath}`).join('\n') : '- (none)',
+    ''
+  ].join('\n');
+}
+
+async function writePartialMarkdown({ runDirectory, persona, driverName, target, notes, screenshots, play, reason }) {
+  const markdown = renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason });
+  assertNoSecrets('report.md', markdown);
+  await writeFile(path.join(runDirectory, RUN_FILES.reportMd), markdown, 'utf8');
+}
+
+/**
+ * The `prompt_version` the report has to carry, read out of the skill's own
+ * frontmatter so a content pack update moves it without a CLI release.
+ *
+ * @param {string} skill
+ * @returns {string|null}
+ */
+export function promptVersionOf(skill) {
+  const match = String(skill || '').match(/^prompt_version:\s*(\S+)\s*$/m);
+  return match ? match[1] : null;
+}
+
+export default { runPersona, buildSystem, promptVersionOf, shouldEscalate, renderFallbackMarkdown };