ravensight-playtest 0.5.2 → 0.7.0

package/src/run/acceptance.js

@@ -0,0 +1,212 @@
+/**
+ * Fix v2's acceptance contract and its Labs gate.
+ *
+ * The contract is written from the finding BEFORE anything is edited, sent at
+ * register, and frozen by the server on the job. From then on it is the only
+ * thing the verify brief is built from, and the apply step reads it but cannot
+ * change it: a repair turn is told what failed, never handed a new definition
+ * of success.
+ *
+ * Shape (the server's field names): `{ expected, actual, reproSteps[],
+ * regressionPersonas[] }`.
+ *
+ * Fix v2 is a Labs (Beta) capability, and the server decides whether it is
+ * on, not a client flag. Without a server that says so, and without a job
+ * that comes back carrying the frozen contract, `fix` behaves exactly as it
+ * did before Fix v2.
+ */
+
+/** Field limits, so a contract built from a long finding still fits. */
+export const ACCEPTANCE_LIMITS = Object.freeze({ text: 1000, steps: 20, step: 300, personas: 5 });
+
+/** The Labs capability this module depends on. */
+export const FIX_V2_CAPABILITY = 'fix_v2';
+
+function text(value, limit) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  return trimmed.length <= limit ? trimmed : trimmed.slice(0, limit);
+}
+
+/**
+ * Build the contract from a finding. Pure; nothing here asks a model.
+ *
+ * - `actual` is what the persona saw: the finding's own `actual`, else its
+ *   description, else its title.
+ * - `expected` is the finding's own `expected`, else the plain negation of
+ *   the title, which is what "fixed" means when nobody wrote more.
+ * - `reproSteps` are the finding's steps, as recorded.
+ * - `regressionPersonas` is the persona who filed it, who also plays verify.
+ *
+ * @param {Object} finding
+ * @param {{persona?: string|null, reproSteps?: Array<string>}} [options]
+ * @returns {{expected: string, actual: string, reproSteps: Array<string>, regressionPersonas: Array<string>}}
+ */
+export function buildAcceptance(finding = {}, { persona = null, reproSteps = [] } = {}) {
+  const title = text(finding.title, ACCEPTANCE_LIMITS.text);
+  const actual = text(finding.actual, ACCEPTANCE_LIMITS.text)
+    || text(finding.description, ACCEPTANCE_LIMITS.text)
+    || title
+    || 'the behaviour the finding describes';
+  const expected = text(finding.expected, ACCEPTANCE_LIMITS.text)
+    || (title ? `This no longer happens: ${title}` : 'The behaviour the finding describes no longer happens.');
+  const personas = [persona || finding.persona].filter(entry => typeof entry === 'string' && entry.trim());
+  return freeze({
+    expected,
+    actual,
+    reproSteps: reproSteps
+      .map(step => text(String(step), ACCEPTANCE_LIMITS.step))
+      .filter(Boolean)
+      .slice(0, ACCEPTANCE_LIMITS.steps),
+    regressionPersonas: [...new Set(personas)].slice(0, ACCEPTANCE_LIMITS.personas)
+  });
+}
+
+/**
+ * The contract the server froze, read from a register answer, or null when
+ * the server kept none (an older server, or Labs off). Null means the standard fix.
+ *
+ * @param {Object} registered
+ * @returns {Object|null}
+ */
+export function frozenAcceptance(registered) {
+  const raw = (registered && (registered.acceptance || (registered.job && registered.job.acceptance))) || null;
+  if (!raw || typeof raw !== 'object') return null;
+  const expected = text(raw.expected, ACCEPTANCE_LIMITS.text);
+  const actual = text(raw.actual, ACCEPTANCE_LIMITS.text);
+  if (!expected || !actual) return null;
+  const list = value => (Array.isArray(value) ? value.filter(entry => typeof entry === 'string' && entry.trim()) : []);
+  return freeze({
+    expected,
+    actual,
+    reproSteps: list(raw.reproSteps),
+    regressionPersonas: list(raw.regressionPersonas)
+  });
+}
+
+/**
+ * Whether the server says Fix v2 is live for this game. Anything other than a
+ * clear yes is no: a missing route (an older server), an error, Labs off for
+ * the game, or the capability's kill switch.
+ *
+ * Accepted answers: `{ enabled, capabilities: { fix_v2: true } }` or
+ * `{ capabilities: { fix_v2: { live: true } } }` (`enabled: true` is read the
+ * same as `live`).
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @returns {Promise<boolean>}
+ */
+export async function fixV2Live(api, gameId, { onUnfunded } = {}) {
+  if (!api || !api.labs || typeof api.labs.get !== 'function') return false;
+  let answer;
+  try {
+    answer = await api.labs.get(gameId);
+  } catch {
+    return false;
+  }
+  if (!capabilityLive(answer, FIX_V2_CAPABILITY)) return false;
+  // A register would refuse it, and the ordinary fix is right there at the same price.
+  const labs = answer.labs && typeof answer.labs === 'object' ? answer.labs : answer;
+  if (labs.funding_met && labs.funding_met[FIX_V2_CAPABILITY] === false) {
+    if (onUnfunded) onUnfunded();
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Whether this game's traces should be uploaded: any Labs capability that reads
+ * them back is on for it. Never throws; no answer is no upload.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @returns {Promise<boolean>}
+ */
+export async function tracesWanted(api, gameId) {
+  if (!api || !api.labs || typeof api.labs.get !== 'function') return false;
+  try {
+    const answer = await api.labs.get(gameId);
+    return capabilityLive(answer, 'validate') || capabilityLive(answer, FIX_V2_CAPABILITY);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {Object} answer
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function capabilityLive(answer, name) {
+  if (!answer || typeof answer !== 'object') return false;
+  const labs = answer.labs && typeof answer.labs === 'object' ? answer.labs : answer;
+  if (labs.enabled === false) return false;
+  const entry = labs.capabilities && labs.capabilities[name];
+  if (entry === true) return true;
+  return Boolean(entry && typeof entry === 'object' && (entry.live === true || entry.enabled === true));
+}
+
+/**
+ * The contract as the developer reads it, before agreeing to pay.
+ *
+ * @param {Object} acceptance
+ * @returns {Array<string>}
+ */
+export function acceptanceLines(acceptance) {
+  return [
+    'Acceptance contract (frozen at register; the fix is judged against this and nothing else):',
+    `  expected: ${acceptance.expected}`,
+    `  actual:   ${acceptance.actual}`,
+    acceptance.reproSteps.length > 0
+      ? `  repro:    ${acceptance.reproSteps.map((step, index) => `${index + 1}. ${step}`).join(' ')}`
+      : '  repro:    none recorded',
+    `  verify and regression personas: ${acceptance.regressionPersonas.join(', ') || 'none'}`
+  ];
+}
+
+/**
+ * The contract as a prompt block, marked read-only.
+ *
+ * @param {Object} acceptance
+ * @returns {string}
+ */
+export function acceptanceBlock(acceptance) {
+  return [
+    '<acceptance read_only="true">',
+    JSON.stringify(acceptance, null, 2),
+    '</acceptance>',
+    'The acceptance contract above was frozen before any edit. You cannot change it, and the fix is judged against it alone.'
+  ].join('\n');
+}
+
+/**
+ * The verify run's brief, built from the frozen contract only: not from the
+ * finding, not from the plan, not from anything the apply step said.
+ *
+ * @param {Object|null} base the game's brief
+ * @param {Object} acceptance
+ * @returns {Object}
+ */
+export function verifyBriefFromAcceptance(base, acceptance) {
+  const fields = (base && base.fields) || {};
+  return {
+    ...(base || {}),
+    fields: {
+      verify_task: `Check whether this still happens: ${acceptance.actual}`,
+      verify_expected: acceptance.expected,
+      verify_repro_steps: [...acceptance.reproSteps],
+      verify_instruction: 'Follow these steps first and say plainly whether the actual behaviour still happens or the expected behaviour happens instead. Then play as you normally would.',
+      ...fields
+    }
+  };
+}
+
+function freeze(value) {
+  for (const key of Object.keys(value)) {
+    if (Array.isArray(value[key])) Object.freeze(value[key]);
+  }
+  return Object.freeze(value);
+}
+
+export default { buildAcceptance, frozenAcceptance, fixV2Live, capabilityLive, acceptanceLines, acceptanceBlock, verifyBriefFromAcceptance };

package/src/run/args.js

@@ -20,6 +20,9 @@ const VALUED = new Map([
   ['--build-url', 'buildUrl'],
   ['--build-dir', 'buildDir'],
   ['--godot-project', 'godotProject'],
+  // The Godot binary, as check and the driver docs take it. RAVENSIGHT_GODOT
+  // and GODOT still work when it is not given.
+  ['--godot-path', 'godotPath'],
   ['--cli', 'cli'],
   ['--max-actions', 'maxActions'],
   ['--concurrency', 'concurrency'],
@@ -40,11 +43,25 @@ const BOOLEAN = new Map([
   // A long persona run: twice the actions, model budget and wall time of a
   // standard run, priced by the server as its own unit.
   ['--long', 'long'],
+  // godot_driver only: let the game run in real time between actions instead
+  // of pausing it while the persona thinks.
+  ['--realtime', 'realtime'],
   // Native drivers only: register without the free automation probe first.
   ['--skip-preflight', 'skipPreflight'],
   // Resume only: replay an interrupted run from the start instead of writing a
   // partial report from the transcript it already has.
-  ['--restart-interrupted', 'restartInterrupted']
+  ['--restart-interrupted', 'restartInterrupted'],
+  // Fix only, Fix v2 (Labs beta): after a verified fix, ask, then commit the
+  // fix's files, push the branch and open a pull request with gh.
+  ['--open-pr', 'openPr'],
+  // Fix only: run the standard fix even when Fix v2 is on for the game.
+  ['--no-labs', 'noLabs'],
+  // Fix v2: let the checks run the project's own tests, and run on edits to
+  // test files.
+  ['--allow-tests', 'allowTests'],
+  // Fix v2: let the checks import a project whose edits touched editor-side
+  // code (project.godot, export presets, addons, .godot, @tool scripts).
+  ['--allow-tool-scripts', 'allowToolScripts']
 ]);
 
 /** Options whose value is a number. */