ravensight-playtest 0.2.3 → 0.2.5

package/src/commands/run.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { buildAggregate, writeAggregate } from '../run/aggregate.js';
-import { optionsFrom } from '../run/args.js';
+import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { getDeps } from '../run/deps.js';
 import { createDriver } from '../run/drivers/index.js';
 import EXIT from '../run/exit.js';
@@ -10,6 +10,8 @@ import { createHeartbeat } from '../run/heartbeat.js';
 import { createUsageLedger } from '../run/usage.js';
 import { createModelClient, ModelUnavailableError, ProxyError } from '../run/model.js';
 import { jobDir, runDir as runDirFor, JOB_FILES, RUN_FILES } from '../run/paths.js';
+import { readBridgeConfig } from "../run/drivers/stdio.js";
+import { WEBDRIVER_NAMES, readDriverConfig } from '../run/drivers/webdriver.js';
 import { runPersona } from '../run/personaLoop.js';
 import * as stateFile from '../run/state.js';
 import { emitRunEvents } from '../run/synthetic.js';
@@ -78,6 +80,7 @@ async function run(flags, injected, deps, log) {
   const { options, unknown } = optionsFrom(flags);
   if (unknown.length > 0) {
     log(`I do not know these options: ${unknown.join(', ')}. Run "ravensight-playtest run --help".`);
+    for (const line of unknownOptionNotes(unknown)) log(line);
     return EXIT.ENVIRONMENT;
   }
   for (const line of unusedFlagWarnings(options)) log(line);
@@ -86,10 +89,11 @@ async function run(flags, injected, deps, log) {
   if (setup.code !== undefined) return setup.code;
   const { context, gameId, repoRoot, apiUrl, cliVersion, api } = setup;
 
+  if (options.controller && !['standard', 'jev'].includes(options.controller)) { log('Choose --controller standard or --controller jev.'); return EXIT.ENVIRONMENT; }
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
   const target = resolveTarget(options, context.config, driverName);
   if (!target) {
-    log('Point the run at a build: --build-url for a web build, or --godot-project for a Godot project.');
+    log('Point the run at a build: --build-url for a web build, --godot-project for Godot, or --driver-config for a native or text bridge.');
     return EXIT.ENVIRONMENT;
   }
 
@@ -97,8 +101,11 @@ async function run(flags, injected, deps, log) {
   // `aggregate.*` steps are spendable from, and it is free (the price list has
   // no unit for it), so asking costs nothing and not asking costs the judged
   // dedup and success-criteria passes.
+  if (WEBDRIVER_NAMES.includes(driverName)) await readDriverConfig(target);
+  if (driverName === "cli_stdio") await readBridgeConfig(target);
   const modules = ['persona_playtest', 'aggregate_report'];
   const pack = await deps.packs.get({ api, gameId, modules });
+  if (options.controller === 'jev' && !pack.routing?.action_controllers?.includes('jev')) { log('This server does not currently support the requested action controller. No job was registered.'); return EXIT.ENVIRONMENT; }
   const personaSlugs = resolvePersonas(options, context.config, pack);
   const personas = personaSlugs.map(slug => {
     const found = (pack.personas || []).find(persona => persona.slug === slug);
@@ -164,7 +171,7 @@ async function run(flags, injected, deps, log) {
       cli_version: cliVersion,
       confirm_price_cents: estimate.estimate_cents,
       brief_version: brief.version ?? null,
-      build: { kind: driverName === 'playwright_web' ? 'url' : 'godot_project', ref: target },
+      build: { kind: driverName === 'playwright_web' ? 'url' : (WEBDRIVER_NAMES.includes(driverName) || driverName === 'cli_stdio') ? 'driver_config' : 'godot_project', ref: target },
       repo: { commit: (context.config && context.config.commit) || '', dirty: Boolean(context.config && context.config.dirty) },
       max_actions: Number.isInteger(options.maxActions) ? options.maxActions : null,
       pack_versions: { pack: pack.pack_version }
@@ -191,6 +198,7 @@ async function run(flags, injected, deps, log) {
     priceCents: registered.price && registered.price.price_cents,
     options: {
       maxActions: options.maxActions ?? null,
+      controller: options.controller || 'standard',
       concurrency: options.concurrency ?? DEFAULT_CONCURRENCY,
       uploadVideo: Boolean(options.uploadVideo),
       uploadTranscript: Boolean(options.uploadTranscript)
@@ -287,17 +295,17 @@ export function personaCountRefusal(count, maxPersonas) {
 /**
  * Flags this release parses and then does not act on.
  *
- * Saying so is the point: a developer who passes `--budget-usd 1` and is not
- * told it did nothing will believe they capped the spend.
+ * Saying so is the point: a developer who passes a flag and is not told it
+ * did nothing will believe it did something. `--budget-usd` is not here
+ * because it is not parsed at all any more: the model budget is the server's,
+ * derived from what the job was charged and enforced per call at the proxy,
+ * so a spending flag the CLI cannot honour is refused rather than accepted.
  *
  * @param {Object} options
  * @returns {Array<string>}
  */
 export function unusedFlagWarnings(options) {
   const warnings = [];
-  if (options.budgetUsd !== undefined) {
-    warnings.push('--budget-usd is not applied by this release: the model budget is the server\'s, derived from what the job was charged, and it is enforced per call at the proxy.');
-  }
   if (options.quality !== undefined) {
     warnings.push('--quality is not applied by this release: the model tier is the server\'s decision, and the CLI is not allowed to name one.');
   }
@@ -349,7 +357,7 @@ export async function playJob({
 
   const results = [];
   const queue = personaRuns.filter(entry => !stateFile.isRunDone(journal.runs[entry.run_id]));
-  const concurrency = Math.max(1, Math.min(Number(options.concurrency) || DEFAULT_CONCURRENCY, queue.length || 1));
+  const concurrency = WEBDRIVER_NAMES.includes(driverName) ? 1 : Math.max(1, Math.min(Number(options.concurrency) || DEFAULT_CONCURRENCY, queue.length || 1));
 
   /**
    * Runs the process is in the middle of. A Ctrl-C has to move these to
@@ -385,6 +393,7 @@ export async function playJob({
           journal,
           inFlight,
           makeDriver,
+          brief,
           log
         }));
       }
@@ -467,6 +476,7 @@ export async function playPersonaRun({
   journal,
   inFlight = null,
   makeDriver,
+  brief = null,
   log
 }) {
   const runId = entry.run_id;
@@ -479,7 +489,7 @@ export async function playPersonaRun({
   // Headless is right for a browser and wrong for Godot: a headless Godot
   // routes no GUI input, so it is a smoke-test mode rather than a way to play.
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
-  const driver = await makeDriver(driverName, { headless });
+  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId }));
   // The ledger is created here rather than inside the loop so the heartbeat
   // can feed it the server's own figure for what this run has spent. Prices
   // are server side only, so that answer is the only real one.
@@ -516,6 +526,7 @@ export async function playPersonaRun({
   try {
     if (inFlight) inFlight.set(runId, { state: 'launching' });
     outcome = await runPersona({
+      controller: options.controller || 'standard',
       client,
       api,
       gameId,
@@ -527,7 +538,9 @@ export async function playPersonaRun({
       target,
       runDirectory: directory,
       skill,
-      brief: pack.brief || null,
+      // The brief this command fetched and checked is complete, not the
+      // pack's copy, which a pack bundle does not always carry.
+      brief: brief || pack.brief || null,
       intentNotes: pack.intent_notes || [],
       schemas: pack.schemas || [],
       maxActions,
@@ -579,10 +592,10 @@ export async function playPersonaRun({
  * Upload the run directory and complete the run, through cli-core's
  * `finalizeRun` so the 422 `upload_unverified` repair pass lives in one place.
  *
- * A budget-capped or cancelled run sends no `report`: the route accepts that,
- * and it is the honest answer. Inventing a sentiment score nobody gave so a
- * placeholder report would validate would put a fabricated verdict in front of
- * the developer.
+ * A cancelled run sends no `report`. A budget-capped run sends the partial
+ * report built from its notes (`partial: true`, placeholder sentiment the
+ * report itself marks as no verdict), because the notes are what the run
+ * bought before the money ran out.
  *
  * A refused delivery does not take the job down. `finish` still settles it, the
  * artifacts are on disk, and `resume` can retry.
@@ -624,15 +637,27 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
   }
 
   try {
-    const answer = await deps.finalizeRun(directory, {
-      api,
-      gameId,
-      jobId,
-      runId,
-      includeVideo: Boolean(options.uploadVideo),
-      includeTranscript: Boolean(options.uploadTranscript),
-      body
-    });
+    let answer;
+    try {
+      answer = await deps.finalizeRun(directory, {
+        api,
+        gameId,
+        jobId,
+        runId,
+        includeVideo: Boolean(options.uploadVideo),
+        includeTranscript: Boolean(options.uploadTranscript),
+        body
+      });
+    } catch (error) {
+      // A server older than partial reports refuses one as `invalid_report`.
+      // The uploads are already done by then, so the run is completed
+      // without it rather than left open: the notes stay on disk in
+      // report.json either way.
+      if (!(body.report && body.report.partial && error && error.status === 422 && error.code === 'invalid_report')) throw error;
+      log(`run ${runId}: the server refused the partial report (${String(error.message)}), so the run is completed without it. The notes are in ${directory}.`);
+      const { report: ignored, report_md: alsoIgnored, ...withoutReport } = body;
+      answer = await api.runs.complete(gameId, jobId, runId, withoutReport);
+    }
     if (journal) await stateFile.patchRun(repoRoot, journal, runId, { uploaded: true, completed: true });
     if (answer && answer.dropped_findings > 0) {
       log(`run ${runId}: the server dropped ${answer.dropped_findings} finding(s) with no usable evidence.`);
@@ -911,12 +936,41 @@ export async function resolveSetup(deps, options, log) {
   };
 }
 
-async function loadRunReports(repoRoot, jobId, personaRuns) {
+/**
+ * What a driver is created with. The playtest identity is the run's own: the
+ * Godot driver passes it into the game's environment and the web driver into
+ * the page, and the game's SDK sends the token on `POST /session`, which is
+ * what makes the server force the device id and mark the session synthetic.
+ * Without it the game's own events from a playtest count as a real player.
+ *
+ * @returns {Object}
+ */
+export function driverOptions({ headless, driverName, target, directory, entry, jobId }) {
+  return {
+    headless,
+    playtest: {
+      token: entry.playtest_token || null,
+      runId: entry.run_id,
+      jobId,
+      persona: entry.persona || null
+    },
+    projectDir: driverName === 'godot_driver' ? target : undefined,
+    runDir: directory
+  };
+}
+
+/**
+ * The persona reports on disk, for the aggregate. A partial report (written
+ * from the notes when the money ran out) is loaded as a `budget_exceeded`
+ * run: its findings count, and the aggregate says the job is partial.
+ */
+export async function loadRunReports(repoRoot, jobId, personaRuns) {
   const out = [];
   for (const entry of personaRuns) {
     const file = path.join(runDirFor(repoRoot, jobId, entry.run_id), RUN_FILES.reportJson);
     try {
-      out.push({ runId: entry.run_id, persona: entry.persona, state: 'succeeded', report: JSON.parse(await readFile(file, 'utf8')) });
+      const report = JSON.parse(await readFile(file, 'utf8'));
+      out.push({ runId: entry.run_id, persona: entry.persona, state: report && report.partial === true ? 'budget_exceeded' : 'succeeded', report });
     } catch {
       out.push({ runId: entry.run_id, persona: entry.persona, state: 'failed', report: null });
     }
@@ -985,6 +1039,7 @@ export function resolveMaxActions(options, persona, pack) {
 }
 
 export function resolveTarget(options, config, driverName) {
+  if (WEBDRIVER_NAMES.includes(driverName) || driverName === 'cli_stdio') return options.driverConfig || (config?.build?.kind === 'driver_config' ? config.build.ref : null);
   const build = (config && config.build) || {};
   if (driverName === 'playwright_web') return options.buildUrl || (build.kind === 'url' ? build.ref : null) || null;
   if (driverName === 'godot_driver') return options.godotProject || (build.kind === 'godot_project' ? build.ref : null) || null;

package/src/run/actionSelector.js

@@ -0,0 +1,47 @@
+import { ProxyError, STEPS } from './model.js';
+export const CONTROLLERS = ['standard', 'jev'];
+export const JEV_CONTROLLER_PROMPT = '\nRavensight Playtester action-selection mode: describe the currently visible screen briefly in text, including each proposed target and its screenshot coordinates, then propose one to three ALTERNATIVE next actions as tool calls. Only one will be executed after a separate selector chooses. These are alternatives, never a sequential plan. Use only observed controls. For a canvas game without accessible DOM controls, include a target label describing the visible control AND screenshot x/y coordinates; the driver uses those coordinates. Never invent selectors such as textbox or button names. When the brief identifies a field as a public player label, use Ravensight Playtester. Credentials or private access codes require human review. When the game is loading or transitioning, propose a bounded wait tool call. Do not place secrets in proposals. After their tool results, observe the resulting state before proposing again.';
+export function describeAction(tool) {
+  const input = tool.input || {};
+  const descriptions = {
+    click: input.target ? `Click the visible ${input.target}${Number.isFinite(input.x) && Number.isFinite(input.y) ? ` at (${input.x}, ${input.y})` : ''}.` : `Click the observed screenshot position (${input.x}, ${input.y}).`,
+    type: `Type the prepared text into the focused field${input.submit ? ' and press Enter' : ''}.`,
+    key: `Press the ${input.key} key.`,
+    wait: `Wait ${input.ms} milliseconds for the screen to finish transitioning.`,
+    snapshot: 'Observe the current screen again.',
+    screenshot: 'Save a screenshot of the current screen for the report.',
+    navigate: `Navigate to the supplied build URL ${input.url}.`
+  };
+  return String(descriptions[tool.name] || `${tool.name}: ${JSON.stringify(input)}`).slice(0, 300);
+}
+export async function selectAction({ api, jobId, runId, persona, observation, toolUses, recentActions = [], intentNotes = [] }) {
+  const proposals = toolUses.slice(0, 8);
+  // Observation does not input anything into the game. Keep it in the existing
+  // bounded driver loop; Jev selects game inputs, not whether a frame may load.
+  if (proposals.length && proposals.every(tool => ['wait', 'snapshot', 'screenshot'].includes(tool.name))) {
+    return { status: 'selected', toolId: proposals[0].id, source: 'observation' };
+  }
+  const body = {
+    objective: ('Play the game according to the supplied persona, exploring visible controls and gathering evidence. Developer scope: ' + intentNotes.map(note => note.text || '').join(' ')).slice(0, 1000),
+    // The observer already applies the full persona. The selector needs its identity,
+    // current visible state and proposed inputs, not a second personality prompt.
+    persona: String(persona.name || persona.slug || 'Playtester').slice(0, 200),
+    observation: String(observation).slice(0, 6000),
+    actions: proposals.map((tool, index) => ({ id: `action_${index}`, description: describeAction(tool) })),
+    recentActions: recentActions.slice(-10).map(value => String(value).slice(0, 100))
+  };
+  let result;
+  try {
+    result = (await api.request('POST', '/api/v1/playtest/model/v1/decisions', {
+      body, idempotent: false,
+      headers: { 'X-Playtest-Job': jobId, 'X-Playtest-Run': runId, 'X-Playtest-Step': STEPS.personaAct }
+    })).body;
+  } catch (error) {
+    if (error.status === 402 || error.status === 409) throw new ProxyError({ status: error.status, code: error.code || 'decision_refused', message: 'The action selector stopped because this run is no longer spendable.' });
+    return { status: 'review', reason: 'decision_unavailable' };
+  }
+  if (result.status !== 'suggested') return result;
+  const index = body.actions.findIndex(action => action.id === result.actionId);
+  if (index < 0 || !Number.isFinite(result.confidence) || result.confidence < 0.75) return { status: 'review', reason: result.actionId === 'stop' ? 'selector_stopped' : 'uncertain_action' };
+  return { status: 'selected', toolId: proposals[index].id, confidence: result.confidence, budget: result.budget };
+}

package/src/run/aggregate.js

@@ -344,7 +344,9 @@ export async function buildAggregate({
   const issues = clusters.flatMap(cluster => toIssues(cluster, verdicts.get(cluster.signature)));
   const ranked = rankIssues(issues, personasRun);
 
-  const partial = runs.some(run => !run.report || ['failed', 'canceled', 'budget_exceeded'].includes(run.state));
+  // A run whose report is partial (the CLI wrote it from the notes when the
+  // money ran out) counts toward the issues, and makes the job partial.
+  const partial = runs.some(run => !run.report || run.report.partial === true || ['failed', 'canceled', 'budget_exceeded'].includes(run.state));
   const judgement = aggregateRunId
     ? await judgeAggregate({ client, jobId, runId: aggregateRunId, ranked, inputs, brief, intentNotes, ledger, log })
     : null;
@@ -374,8 +376,11 @@ export async function buildAggregate({
       state: run.state,
       actions_taken: run.report.actions_taken,
       quit_reason: run.report.quit_reason,
-      sentiment: run.report.sentiment,
-      would_continue: run.report.would_continue
+      // A partial report's sentiment is the schema's placeholder, not a
+      // persona verdict, so it is not shown as one.
+      sentiment: run.report.partial ? null : run.report.sentiment,
+      would_continue: run.report.partial ? null : run.report.would_continue,
+      ...(run.report.partial ? { partial: true } : {})
     })),
     issues: applied.issues,
     praise: ranked.praise,
@@ -450,7 +455,7 @@ export async function judgeAggregate({ client, jobId, runId, ranked, inputs, bri
     '',
     `issues:\n${ranked.issues.map(issue => `  ${issue.issue_id} [${issue.severity}/${issue.category}] ${issue.title}: ${String(issue.description || '').slice(0, 300)} (personas: ${issue.personas_affected.join(', ') || 'none'})`).join('\n') || '  (none)'}`,
     `praise:\n${ranked.praise.map(issue => `  ${issue.issue_id} ${issue.title}`).join('\n') || '  (none)'}`,
-    `runs:\n${inputs.map(run => `  ${run.persona}: ${run.report.actions_taken} actions, ${run.report.quit_reason}, would_continue=${run.report.would_continue}`).join('\n') || '  (none)'}`
+    `runs:\n${inputs.map(run => `  ${run.persona}: ${run.report.actions_taken} actions, ${run.report.quit_reason}, ${run.report.partial ? 'partial (out of budget, no verdict)' : `would_continue=${run.report.would_continue}`}`).join('\n') || '  (none)'}`
   ].join('\n');
 
   try {
@@ -582,7 +587,7 @@ export function renderAggregateMarkdown(json) {
   lines.push('|---|---|---|---|---|---|---|');
   for (const run of json.runs) {
     const sentiment = run.sentiment || {};
-    lines.push(`| ${run.persona} | ${run.actions_taken} | ${run.quit_reason} | ${sentiment.fun ?? '-'} | ${sentiment.clarity ?? '-'} | ${sentiment.frustration ?? '-'} | ${run.would_continue ? 'yes' : 'no'} |`);
+    lines.push(`| ${run.persona} | ${run.actions_taken} | ${run.quit_reason} | ${sentiment.fun ?? '-'} | ${sentiment.clarity ?? '-'} | ${sentiment.frustration ?? '-'} | ${run.would_continue === null || run.would_continue === undefined ? '-' : run.would_continue ? 'yes' : 'no'} |`);
   }
   lines.push('');
   lines.push('## Top issues (ranked)');

package/src/run/args.js

@@ -14,13 +14,14 @@
 const VALUED = new Map([
   ['--personas', 'personas'],
   ['--driver', 'driver'],
+  ['--driver-config', 'driverConfig'],
+  ['--controller', 'controller'],
   ['--build-url', 'buildUrl'],
   ['--build-dir', 'buildDir'],
   ['--godot-project', 'godotProject'],
   ['--cli', 'cli'],
   ['--max-actions', 'maxActions'],
   ['--concurrency', 'concurrency'],
-  ['--budget-usd', 'budgetUsd'],
   ['--quality', 'quality']
 ]);
 
@@ -39,7 +40,7 @@ const BOOLEAN = new Map([
 ]);
 
 /** Options whose value is a number. */
-const NUMERIC = new Set(['maxActions', 'concurrency', 'budgetUsd']);
+const NUMERIC = new Set(['maxActions', 'concurrency']);
 
 /**
  * @param {string[]} argv the leftovers commander handed over
@@ -75,6 +76,21 @@ export function parseRunArgv(argv = []) {
   return { options, unknown };
 }
 
+/**
+ * Extra lines for unknown options that used to exist, so a removed flag is
+ * explained rather than just refused.
+ *
+ * @param {string[]} unknown
+ * @returns {string[]}
+ */
+export function unknownOptionNotes(unknown = []) {
+  const notes = [];
+  if (unknown.includes('--budget-usd')) {
+    notes.push('--budget-usd was removed: the model budget is set by the server for each run, from what the job was charged, and enforced at the proxy.');
+  }
+  return notes;
+}
+
 /**
  * Merge the flags cli-core parsed with the ones this file parsed, flags
  * winning, and normalise the two names for the repository root.
@@ -113,4 +129,4 @@ function stripUndefined(value) {
   return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }
 
-export default { parseRunArgv, optionsFrom };
+export default { parseRunArgv, optionsFrom, unknownOptionNotes };

package/src/run/context.js

@@ -31,6 +31,13 @@ export const MAX_IMAGES_IN_CONTEXT = 1;
 /** How many full observations stay in context (spec 03's K). */
 export const KEEP_OBSERVATIONS = 6;
 
+/**
+ * What an observation identical to the one before it is sent as. The driver
+ * marks it (`observation.unchanged`) and ./tools.js writes this in place of
+ * the screen, keeping the `step N` line so it is still an observation.
+ */
+export const UNCHANGED_OBSERVATION_TEXT = '(unchanged)';
+
 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]';
 
@@ -138,7 +145,11 @@ export function pruneObservations(messages, keep = KEEP_OBSERVATIONS) {
     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]);
+        // An unchanged marker is not counted: it is a few bytes, and counting
+        // it would let a run of identical screens push the last REAL screen
+        // out of context, leaving the persona nothing to act on.
+        const text = String(first && first.text);
+        if (first && /^(?:[^\n]*\n)?step \d+/.test(text) && !text.endsWith(`\n${UNCHANGED_OBSERVATION_TEXT}`)) indexes.push([i, j]);
       }
     });
   });

package/src/run/drivers/driver.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 
 /**
- * The driver interface. One shape, three implementations (spec 03's
+ * The driver interface. One shared shape across implementations (spec 03's
  * "Driver interface (all drivers)"): `playwright_web` here in ./web.js,
- * `godot_driver` in ./godot.js, and `cli_stdio` later.
+ * `godot_driver` in ./godot.js, plus native and custom bridge adapters.
  *
  * 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
@@ -138,7 +138,10 @@ export function assertDriver(driver, name) {
 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);
+  const hash = createHash('sha256').update(normalized, 'utf8');
+  // Canvas games keep the same DOM text while their visible state changes.
+  if (observation && observation.screenshotBase64) hash.update(observation.screenshotBase64, 'base64');
+  return hash.digest('hex').slice(0, 32);
 }
 
 /**

package/src/run/drivers/index.js

@@ -1,16 +1,18 @@
 import { assertDriver, DriverError } from './driver.js';
 import { createWebDriver } from './web.js';
+import { createWebDriverAdapter, WEBDRIVER_NAMES } from './webdriver.js';
+import { createStdioDriver } from './stdio.js';
 
 /**
  * The driver registry. `playwright_web` is here; `godot_driver` lives in
  * ./godot.js and is imported lazily so this package still loads on a
- * machine with no Godot and no addon, and `cli_stdio` is not in v1.
+ * machine with no Godot and no addon, and native/custom adapters use local developer-owned connections.
  *
  * The names are the server's `PlaytestRun.driver` enum and the report
  * schema's `driver` enum, not ours to invent.
  */
 
-export const DRIVERS = Object.freeze(['playwright_web', 'godot_driver', 'cli_stdio']);
+export const DRIVERS = Object.freeze(['playwright_web', 'godot_driver', 'cli_stdio', ...WEBDRIVER_NAMES]);
 
 /**
  * @param {string} name
@@ -19,6 +21,7 @@ export const DRIVERS = Object.freeze(['playwright_web', 'godot_driver', 'cli_std
  * @returns {Promise<Object>} a driver satisfying ./driver.js
  */
 export async function createDriver(name, options = {}) {
+  if (WEBDRIVER_NAMES.includes(name)) return assertDriver(createWebDriverAdapter({...options,name}),name);
   const load = options.importer || (specifier => import(specifier));
   switch (name) {
     case 'playwright_web':
@@ -40,10 +43,7 @@ export async function createDriver(name, options = {}) {
       return assertDriver(await factory(options), name);
     }
     case 'cli_stdio':
-      throw new DriverError(
-        'The cli_stdio driver is not in this release. In v1 a text build is played through its web front end with --driver playwright_web.',
-        { fatal: true }
-      );
+      return assertDriver(createStdioDriver(options), name);
     default:
       throw new DriverError(`unknown driver "${name}"; one of: ${DRIVERS.join(', ')}`, { fatal: true });
   }

package/src/run/drivers/stdio.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { DriverError, observationHash, screenshotName, truncateObservation } from './driver.js';
+
+// A developer-owned bridge implements newline-delimited JSON-RPC. The model
+// receives game controls only, never command arguments or process access.
+export async function readBridgeConfig(file) {
+  if ((await fs.stat(file)).size > 64000) throw new DriverError('Bridge configuration exceeds 64 KB.');
+  const config = JSON.parse(await fs.readFile(file, 'utf8'));
+  if (typeof config.command !== 'string' || !path.isAbsolute(config.command) ||
+      (config.args !== undefined && (!Array.isArray(config.args) || config.args.some(v => typeof v !== 'string'))) ||
+      (config.cwd !== undefined && !path.isAbsolute(config.cwd))) {
+    throw new DriverError('Bridge config needs an absolute command, string arguments and an optional absolute cwd.');
+  }
+  await fs.access(config.command, fs.constants.X_OK);
+  return config;
+}
+
+export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000 } = {}) {
+  let child, buffer = '', nextId = 0, runDirectory, step = 0, shots = 0, lastHash;
+  const pending = new Map();
+  const fail = message => {
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new DriverError(message, { fatal: true })); }
+    pending.clear();
+  };
+  function request(method, params = {}) {
+    if (!child || child.exitCode !== null || child.killed) return Promise.reject(new DriverError('Game bridge is not running.', { fatal: true }));
+    return new Promise((resolve, reject) => {
+      const id = ++nextId;
+      const timer = setTimeout(() => { pending.delete(id); reject(new DriverError('Game bridge timed out.', { fatal: true })); child.kill(); }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => {
+        if (error) { clearTimeout(timer); pending.delete(id); reject(new DriverError('Game bridge input failed.')); }
+      });
+    });
+  }
+  async function observe() {
+    const value = await request('observe');
+    if (!value || typeof value.text !== 'string') throw new DriverError('Bridge observation needs text.');
+    const observation = { step: ++step, text: truncateObservation(value.text), elapsedMs: 0 };
+    if (typeof value.screenshotBase64 === 'string' && value.screenshotBase64.startsWith('iVBORw0KGgo')) {
+      observation.screenshotBase64 = value.screenshotBase64;
+      observation.screenshotMediaType = 'image/png';
+    }
+    lastHash = observationHash(observation);
+    return observation;
+  }
+  return {
+    name: 'cli_stdio', supportedActions: ['type', 'key', 'click', 'wait'],
+    async launch({ target, runDir }) {
+      const config = await readBridgeConfig(target);
+      runDirectory = runDir;
+      child = spawnImpl(config.command, config.args || [], { cwd: config.cwd || path.dirname(path.resolve(target)), shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+      child.stdout.setEncoding('utf8');
+      child.stdout.on('data', chunk => {
+        buffer += chunk;
+        if (Buffer.byteLength(buffer) > 8 * 1024 * 1024) { fail('Game bridge response exceeded 8 MB.'); child.kill(); return; }
+        let end;
+        while ((end = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+          let value;
+          try { value = JSON.parse(line); } catch { fail('Game bridge returned invalid JSON.'); child.kill(); return; }
+          const entry = pending.get(value?.id);
+          if (!entry) continue;
+          pending.delete(value.id); clearTimeout(entry.timer);
+          if (value.jsonrpc !== '2.0' || value.error) entry.reject(new DriverError('Game bridge command failed.'));
+          else entry.resolve(value.result);
+        }
+      });
+      // Drain diagnostics without copying arbitrary game output into reports.
+      child.stderr.resume();
+      child.stdin.on('error', () => fail('Game bridge input failed.'));
+      child.on('error', () => fail('Game bridge could not start.'));
+      child.on('exit', () => fail('Game bridge exited.'));
+      await fs.mkdir(path.join(runDir, 'screenshots'), { recursive: true });
+      await request('launch', { protocolVersion: 1 });
+    },
+    observe,
+    async act(action) {
+      if (!['type', 'key', 'click', 'wait'].includes(action.kind)) return { ok: false, changed: false, error: 'Unsupported bridge action.' };
+      const before = lastHash;
+      const safe = action.kind === 'type' ? { kind: 'type', text: String(action.text || '').slice(0, 2000), submit: Boolean(action.submit) }
+        : action.kind === 'key' ? { kind: 'key', key: String(action.key || '').slice(0, 64) }
+        : action.kind === 'wait' ? { kind: 'wait', ms: Math.min(5000, Math.max(0, Number(action.ms) || 0)) }
+        : { kind: 'click', target: typeof action.target === 'string' ? action.target.slice(0, 500) : action.target };
+      const answer = await request('act', safe);
+      if (answer?.ok !== true) return { ok: false, changed: false, error: 'Game bridge refused this action.' };
+      return { ok: true, changed: observationHash(await observe()) !== before };
+    },
+    async screenshot(reason) {
+      const image = await request('screenshot');
+      if (typeof image?.pngBase64 !== 'string' || !image.pngBase64.startsWith('iVBORw0KGgo')) throw new DriverError('This bridge did not return a PNG screenshot.');
+      const relativePath = path.join('screenshots', screenshotName(++shots, reason));
+      const file = path.join(runDirectory, relativePath);
+      await fs.writeFile(file, Buffer.from(image.pngBase64, 'base64'));
+      return { path: file, relativePath };
+    },
+    async consoleErrors() { return []; },
+    async stop() {
+      if (child && child.exitCode === null && !child.killed) {
+        child.kill('SIGTERM');
+        const process = child;
+        const timer = setTimeout(() => { if (process.exitCode === null) process.kill('SIGKILL'); }, 1000);
+        timer.unref();
+      }
+      fail('Game bridge stopped.');
+      return { videoPath: null };
+    }
+  };
+}